Web service operations (cont)

pushDataToVoSpace

Request a URL to send data to a VOSpace node.

This method asks the server for aone or more URLs 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 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 directly to a VOSpace service.

Parameters

• destination : A description of the target Node element for the node into which data is to be imported

TheA valid uri attribute is required.

If a Node already exists at the target URI, then the data will be imported into the existing Node and the Node properties will be updated with the Properties in the request.

If there is no Node at the destination URI, then the service will create a new Node using the uri, xsi:type and properties supplied in the request. (see createNode for details)

If the value of vos://null is used then the service will replace it with a service-generated name that is unique and did not previously exist within the space.

If xsi:type is not specified then a node of type vos:Node is implied.

The permitted values of xsi:type are: vos:Node vos:DataNode vos:UnstructuredDataNode vos:StructuredDataNode

If a parent type is requested, the service can implement a subtype, e.g. a vos:DataNode can be implemented as either a vos:StructuredDataNode or a vos:UnstructuredDataNode

• transfer : A transfer element containing detailstemplate offor the data Transfer

The template for the Transfer should contain details of the View and a list of the Protocols that the client would like to use.

The list of Protocols should not contain endpoint addresses, the service will supply the endpoint addresses in the response.

The service will ignore any of the requested protocols that it does not understand or is unable to support.

Returns

• destination : A node element for the updatedUpdated details of the destination Node

• transfer : A transfer element containingUpdated details of the data Transfer

The service shall choose selects which of the requested Protocols it is willing to provide and fills in the operational details for each one.

It shall remove those requestedThe service response should not include any Protocols which it is unable to support.

Faults

• The service shall throw an InternalFault exception if anthe operation fails
• The service shall throw a PermissionDenied exceptionfault if the user does not have permissions to perform the operation
• The service will throw an TypeNotSupported exceptionfault if it does not support theit is unable to create a new Node of the requested node type
• The service shall throw an ViewNotSupported exceptionfault if a StructuredDataNode is requested with no View element
• The service shall throw a ViewNotSupported exceptionfault if the service does not support the data format specified in the requested View
• The service shall throw an ProtocolNotSupported exceptionfault if it supports none of the requested transfer Protocols
• The service shall throw an InvalidURI exceptionfault if the user-supplied URI is invalid.
• The service shall throw an InvalidArgument exceptionfault if one of thea parameter values in a Protocol orthe requested View is invalid
• The service shall throw an InvalidArgument exceptionfault if a parameter in one of the requested Protocols is invalid

pullDataToVoSpace

Import data into a VOSpace node.

This method asks the server to fetch the data from a remote location.

The data transfer is initiated by the VOSpace service and the response is transferred direct into the target data Node.

The data source can be another VOSpace service, or a standard HTTP or FTP server.

The primary use case for this method is transferring data from one server or service to another.

Parameters

• destination : A description of the target Node element for the node into which data is to be imported

TheA valid uri attribute is required.

If a Node already exists at the target URI, then the data will be imported into the existing Node and the Node properties will be updated with the Properties in the request.

If there is no Node at the destination URI, then the service will create a new Node using the uri, xsi:type and properties supplied in the request. (see createNode for details)

if the value of vos://null is used then the service will replace it with a service-generated name that is unique and did not previously exist within the space.

If xsi:type is not specified then a node of type Node is implied.

The permitted values of xsi:type are: Node, DataNode^?, UnstructuredDataNode^? and StructuredDataNode^?.

If a parent type is requested, the service can implement a subtype, e.g. a DataNode^? can be implemented as either a StructuredDataNode^? or an UnstructuredDataNode^?.

• transfer : A transfer element containing dDetails of the data Transfer

The Transfer details should include the View and a list of one or more Protocols with valid endpoint and params for each one.

Returns

• destination : A node element for the updatedUpdated details of the destination Node

Faults

• The service shall throw an InternalFault exception if anthe operation fails
• The service shall throw a PermissionDenied exceptionfault if the user does not have permissions to perform the operation
• The service will throw an TypeNotSupported exceptionfault if it does not support theit is unable to create a new Node of the requested node type
• The service shall throw a ViewNotSupported exceptionfault if the service does not support the data format specified in the requested View
• The service shall throw an ProtocolNotSupported exceptionfault if it supports none of the requested transfer Protocols
• The service shall throw an InvalidURI exceptionfault if the user-supplied URI is invalid.
• The service shall throw an InvalidArgument exceptionfault if one of thea parameter values in a Protocol orthe requested View is invalid
• The service shall throw an InvalidArgument exceptionfault if a parameter in one of the requested Protocols is invalid
• The service shall throw a TransferFailed exceptionfault if the data transfer does not complete.
• The service shall throw an InvalidData exceptionfault if the data format does not match the format specified in the View element

This implies that we are expecting the service to guess the View from the data it receives

• The service shall throw an InvalidData exceptionfault if a StructuredDataNode is request with no View element specified and the service is unable to determine the appropriate data type

Unless there is a really good use case for this, I'd like to require the View specified in the request for both pushDataTo and pullDataTo

• The service shall throw an ViewNotSupported exceptionfault if a StructuredDataNode is requested with no View element

Notes

In VOSpace version 1.0, the transfer is synchronous, and the SOAP call does not return until the transfer has been completed.

If the Transfer request contains more than one Protocol then tThe service may failover to use one or more Protocol of the options if the first one faileds. The service should try each method Protocol option in turn until one succeeds or all have been tried.

-- DaveMorris - 02 Mar 2007