VoSpace 2.x

PushDataToVoSpace

Request a URL to send data to a VoSpace node.

This method was called ImportInit

This method asks the server for a URL that the client can use to send data to. The data transfer is initiated by the client, after it has received the response from the VoSpace service. The client sends the data using a put request, and the data is transferred into the target node.

The primary use case for this method is a laptop or desktop client that wants to send some data to a VoSpace service.

Parameters

Import into an existing node

• Target - The URI of an existing data node. note
  • vos://[service]/000-517
  • vos:///000-517
  • vos://[service]/path/my%20results
  • vos:///path/my%20results
  • vos:///my%20results

Import into a new node

• Parent - The URI of an existing parent node. note
  • vos://[service]/path/path/
  • vos:///path/path/
  • vos://[service]/
  • vos:///

• Name - A (optional) human readable name for the new node. note
  • my results

• Type - The URI of the node type
  • ivo://org.astrogrid.vospace/types/data.node

• Replace - A (optional) boolean flag to indicate if the service should replace an existing node (defaults to true).

• Any additional data required to create the node type

As with CreateNode, this could use a generic <node> template element,

    ....
    <node>
        <name>My new node</name>
        <properties>
            ....
        </properties>
    </node>
    ....

and then use xsi:type attribute to extend it as required.

    ....
    <node xsi:type="DataNode">
        <name>My new node</name>
        <properties>
            ....
        </properties>
        <!--+
            | Additional data required for a new DataNode
            +-->
    </node>
    ....

Generic import params

• Properties - An optional set of name value properties to update the node

• Format - The URI of the data format.
  • ivo://org.astrogrid.vospace/formats/binary
  • ivo://org.astrogrid.vospace/formats/votable-1.0

• Protocol - The URI of the transfer protocol.
  • ivo://org.astrogrid.vospace/protocols/http-put
  • ivo://org.astrogrid.vospace/protocols/http-put-chunked
  • ivo://org.astrogrid.vospace/protocols/dime-put

Returns

A <node> element for the updated node, containing

• The full URI encoded identifier for the node. note
  • vos://[service]/000-517
  • vos://[service]/my%20results
  • vos://[service]/path/path/my%20results

• The node name as a plain string
  • 000-517
  • my results

• Type - The URI of the node type
  • ivo://org.astrogrid.vospace/types/data.node

• Properties - The set of name value properties for the new node

Again, an XML friendly way to include any additional type specific data could be to use a generic <node> element,

    ....
    <node>
        <uri>vos://[service]/path/my%20results</uri>
        <type>ivo://org.astrogrid.vospace/types/base.node</type>
        <name>My results</name>
        <properties>
            ....
        </properties>
    </node>
    ....

and then use xsi:type attribute to extend it as required.

    ....
    <node xsi:type="DataNode">
        <uri>vos://[service]/path/my%20results</uri>
        <type>ivo://org.astrogrid.vospace/types/data.node</type>
        <name>My new node</name>
        <properties>
            ....
        </properties>
        <!--+
            | Additional data required for a DataNode
            +-->
    </node>
    ....

Plus, a <transfer> element, containing details of the data transfer.

• The full URI of the transfer object (if the server supports status queries)
  • vos://[service]/[ident]

• Format - The URI of the data format.
  • ivo://org.astrogrid.vospace/formats/binary
  • ivo://org.astrogrid.vospace/formats/votable-1.0

• Protocol - The URI of the transfer protocol.
  • ivo://org.astrogrid.vospace/protocols/http-put
  • ivo://org.astrogrid.vospace/protocols/http-put-chunked

• A <location> element containing details of where to send the data to

This could use xsi:type to include specific params required by the transfer protocol.

A standard http transfer only requires the URL to send the data to

    <location xsi:type="HttpPutLocation">
        <url>http://[host]/[path]</url>
    </location>

A SOAP DIME transfer requires the endpoint of the service, and an identifier for the transfer.

    <location xsi:type="HttpPutLocation">
        <url>http://[host]/[path]</url>
        <ident>5117-00BC6</ident>
    </location>

Other protocols may require different a set of params.

• Expiry date - An optional expiry date of the transfer window

• Status - For a new transfer, the status should be 'ready'

Throws

Target node specified

• The service will throw a NodeNotFound exception if the target node does not exist.

• The service will throw a LinkFound exception if the target path includes a link. note
• The service will throw a LinkFound exception if the target node is a link. note

Create node specified

• The service will throw a NodeNotFound exception if the parent node does not exist.
• The service will throw a OperationNotSupported exception if it does not support the requested type.
• The service may throw a OperationNotSupported exception if it does not support user defined names.
• The service may throw a DuplicateNode exception if <replace> is false, and a node with the same name already exists

• The service will throw a LinkFound exception if the parent path includes a link. note
• The service will throw a LinkFound exception if the parent node is a link. note

Import exceptions

• The service may throw a OperationNotSupported exception if it does not support the requested transfer protocol.
• The service may throw a OperationNotSupported exception if it does not support the requested data format.

• The service may throw an InternalFault exception if an operation fails.
• The service may throw a PermissionDenied exception if the user does not have permissions to perform the operation.

Notes

• The <target> identifier in the request can be full a URI including the service identifier and node path.
  • vos://[service]/000-517
  • vos://[service]/path/my%20results

• The <target> identifier in the request can be a relative URI just containing the node path.
  • vos:///000-517
  • vos:///path/my%20results

• The <parent> identifier in the request can be full a URI including the service identifier and node path.
  • vos://[service]/
  • vos://[service]/path/path/

• The <parent> identifier in the request can be a relative URI just contianing the node path.
  • vos:///
  • vos:///path/path/

• To create a new top level node, the parent URI should have a path of '/', not a null or empty element.
  • vos://[service]/
  • vos:///

• If the <name> in the request is null or empty, then the service will generate a new unique name for the node.

• The <node> identifier in the response must be full a URI including the service identifier and node path.
  • vos://[service]/000-517
  • vos://[service]/path/my%20results

• The transfer information may have a limited lifetime, and may be deleted by the server when it has reached its expiry date.
• The transfer location may have a limited lifetime, and may be deleted by the server when it has reached its expiry date.

• Link nodes are not part of the V1.0 specification, they will be defined in a future version of the specification.
• LinkFound exceptions are defined in this version of the specification to enable future versions to extend the current interface, rather than require a completely new interface type.

Questions

• Do we need the <replace> flag to prevent overwriting an existing file ?

• Should we make the default format binary and allow the <format> element to be optional ?

• If we use xsi:type on the <location>, then do we need the <protocol>.
• Or should the xsi:type be on the <transfer> or <protocol> element ?

• What status codes do we want for transfers, or can we use URIs ?

• What URI syntax should we use for refernces to transfer objects ?
• Should the transfer object reference be moved to a future version ?

• Should the LinkFound exceptions be part of the V1.0 specification, or left until later ?

-- DaveMorris - 26 Apr 2006 -- DaveMorris - 16 May 2006