VoSpace 2.x

PullDataToVoSpace

Import data into a VoSpace node.

This method was ImportData .

This method asks the server to fetch data from a remote location. The data transfer is initiated by the VoSpace service, using a get request, and the response is transferred direct into the target data node.

The primary use case for this method is transferring data from one server or service to another. The data source can be another VoSpace service, or a standard HTTP or FTP server.

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-get
  • ivo://org.astrogrid.vospace/protocols/dime-get

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

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="DimePutLocation">
        <url>http://[host]/[path]</url>
        <ident>5117-00BC6</ident>
    </location>

Other protocols may require different a set of params.

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

• Additional type specific data.

An XML friendly way to include the 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 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-get

• A <location> element containing details of how the data was transferred
  • Again, this could use xsi:type to include specific params required by the transfer protocol.

• Status - For a synchronous transfer, the status should be 'completed'

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 an 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 a TransferFailed exception if the data transfer does not complete.

• 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 should be full a URI including the service identifier and node path.
  • vos://[service]/000-517
  • vos://[service]/path/my%20results

• In version 1.0 of the specification, the transfer is synchronous, and the SOAP call does not return until the transfer has been completed.
• Later versions of the specification will introduce asynchronous transfers.

• The transfer information 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