Scratch page for working on the VOSpace specification.

---

Web service operations

A VOSpace-1 service shall be a SOAP service with the following operations. The contract for the forthcoming VOSpace-2, which will support hierarchies of containers and links between spaces, is a superset of the contract in this section. Please see the original discussion of VOSpace semantics [1] to see how the contract changes.

Service metadata

getProtocols

Get a list of the supported transfer Protocols forsupported by the space service.

Parameters

• none

Returns

• A list of protocol elements for the supported transfer protocol, each containing:
  • zero or more param subelements describing any parameters that are required by the service implementation of the transfer protocol.

• accepts : A list of Protocols that the service can accept
  • In this context 'accepting a protocol' means that the service can act as a client for the protocol
  • e.g. 'accepting http-get' means the service can read data from an external http web server
• provides : A list of Protocols that the service can provide
  • In this context 'providing a protocol' means that the service can act as a server for the protocol
  • e.g. 'providing http-get' means the service can act as a http web server

Faults

• The service shall throw an InternalFault^? exception if anthe operation fails

getViews

Get a list of the available import and export Views and data formats forsupported by the space service.

Parameters

• none

Returns

• accepts - a list of view elements for the supported data formats when importing data
• provides - a list of view elements for the supported data formats when exporting data

• accepts : A list of Views that the service can accept
  • In this context 'accepting a view' means that the service can receive input data in this format
  • A simple file based system may use the reserved View URI ivo://net.ivoa.vospace/views/any to indicate that it can accept data in any format

• provides : A list of Views that the service can provide
  • In this context 'providing a view' means that the service can produce output data in this format
  • A simple file based system may use the reserved View URI ivo://net.ivoa.vospace/views/any to indicate that it can provide data in any format

We need to setup the vospace registry and register the reserved URIs

Faults

• The service shall throw an InternalFault^? exception if anthe operation fails

getProperties

Parameters

• none

Returns

• A list of property elements for the service properties.

• accepts : A list of identifiers for the Properties that the service accepts and understands.
• provides : A list of identifiers for the Properties that the service provides.
• contains : A list of identifiers for all the Properties currently used by Nodes within the service.

Faults

• The service shall throw an InternalFault^? exception if anthe operation fails

Creating and manipulating data nodes

createNode

Create a new node in a space. This method is used to create a node at thea specified location.

Parameters

• node : a template Node element for the node to be created

TheA valid uri attribute is required.

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

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

The permitted values of xsi:type are:

• vos:Node
• vos:DataNode
• vos:UnstructuredDataNode
• vos:StructuredDataNode

If a parent type is requested,When creating a new Node the service can implementmay substitute a valid subtype, i.e. If xsi:type is set to vos:DataNode then thisa DataNode can be implemented as either a StructuredDataNode or an UnstructuredDataNode

TheNode properties of the new Node can be set with the subelementby adding Properties to the template. Attempting to set a Property that the service considers to be 'readonly' will cause a PermissionDenied exception

The 'accepts' and 'provides' lists of Views cannot be set for a DataNode^? using this method

Returns

• node : A Node element fordetails of the new Node.

The accepts list of Views for a DataNode^?the Node will be provided by the service based on service capabililites.

The provides list of Views for the Node may not be filled in until some data has been imported into the Node .

Faults

• The service shall throw an InternalFault^? exception if anthe operation fails
• The service shall throw a DuplicateNode^? exception if a Node already exists with the same URI
• The service shall throw an InvalidURI^? exception if the user-suppliedrequested URI is invalid
• The service shall throw a TypeNotSupported^? exception if the value oftype specified in xsi:type is not supported
• The service shall throw a PermissionDenied^? exception if the user does not have permissions to perform the operation

deleteNode

Delete a node from VOSpace.

Parameters

• target : the URI for theof an existing Node to be deleted

Returns

• void

Faults

• The service shall throw an InternalFault^? exception if anthe operation fails
• The service shall throw a PermissionDenied^? exception if the user does not have permissions to perform the operation
• The service shall throw a NodeNotFound^? exception if the target node does not exist.

listNodes

List the nodes in a VOSpace-1the space.

In order to support large numbers of nodes, this method uses a continuation token to enable the list of results to be split across more than response.

Parameters

• token : An optional continuation token from a previous request, e.g. 5177-B8
  • No token indicates a request for a new list

The server may impose a limited lifetime on the continuation token. If thea token has expired, the server will throw an exception, and the client will have to make a new request.

• limit : An optional limit indicating the maximum number of results in the response, e.g. 10
  • No limit indicates a request for an unpaged result:list. However the server may either return all results in one list or split them across multiple pagesstill impose its own limit on the size of an individual response, splitting the results into more than one block if required.

• detail : The level of detail in the returned listing
  • The permitted values are:
  • min : this returns the node elementthe resulting list contains the minimum detail for each Node with all optional parts removed
    • The minimun XML for a Node is an empty node element with a valid uri attribute <node uri="vos:service/name"/>
  • max : this returns the full expanded record for the nodethe resulting list contains the maximum detail for each Node, including any xsi:type specific extensions
  • properties : this returns thethe resulting list contains a basic Node with Properties element for each Node with no extension-type specifics xsi:type specific extensions.

• nodes : A nodes elementlist containing zero or more Nodes elements identifying each nodethe target URIs to be listed

Only the URIs of the Nodes in the request list are used, this method does not perform a search based on Node Properties or other attributes.

The Node URIs in the request list may contain a '*' wildcard character in the name part of the URI (the remaining text following the last '/' character).

A single request may include more than one target Node containing a wildcard. For example, the following request lists all Nodes with names that that match either *.xml or *.txt

    <listNodes>
        <nodes>
            <node uri="vos://service/*.xml"/>
            <node uri="vos://service/*.txt"/>
        </nodes>
    </listNodes>

Note that the wildcard subsitution for the '*' is a simple 'zero or more of any characters' match.

So *.txt will match Nodes with the the following names

• .txt
• frog.txt
• .txtinfo
• toad.txtinfo

This method does not support regular expression matches.

An empty list of target Nodes list implies a full listing of the space.

A request with an empty list of target Nodes :

    <listNodes>
        <nodes/>
    </listNodes>

is equivalent to a request with a single target Node URI of '*' :

    <listNodes>
        <nodes>
            <node uri="vos://service/*"/>
        </nodes>
    </listNodes>

Returns

• token : An optional continuation token, indicating that the list is incomplete
  • The client may use this token to request the next listblock of Nodes in the sequence.
  • No token implies that the list is complete.

• limit : An optional limit which must be present if a limit parameter was used in the request.
  • If present, the value is the value from the original request and not any limit imposed by the service.

• nodes : A nodes element containing a Node element for each nodelist of the Nodes matching the requested Node URIs

Faults

• The service shall throw an InternalFault^? exception if anthe operation fails
• The service shall throw a PermissionDenied^? exception if the user does not have permissions to perform the operation

• The service shall throw a NodeNotFound^? exception if anya specific target Node does not exist.
  • This does not apply if the target Node URI contains a wildcard

• The service shall throw an InvalidToken^? exception if it does not recognize the continuation token.
• The service shall throw an InvalidToken^? exception if the continuation token has expired.

moveNode

Move a node within a VOSpace service.

Note that this does not cover moving data between two separate VOSpace services.

Moving nodes between separate VOSpace services should be handled by the client, using the import, export and delete methods.

Parameters

• source : The URI forof an existing Node

• destination : The Node elementA template describing the new location. Node.

The contents of the template will be used to update those of the new Node.

The value of the xsi:type attribute will ignored in the sense that type change is not permitted.

The accepts and provides lists of Views for the new Node cannot be set for a DataNode^? using this method.

Returns

• node : A node element forDetails of the Node in its new location

Faults

• The service shall throw an InternalFault^? exception if anthe operation fails
• The service shall throw a PermissionDenied^? exception if the user does not have permissions to perform the operation

• The service shall throw a NodeNotFound^? exception if the targetsource Node does not exist
• The service shall throw a DuplicateNode^? exception if a Node already exists with the same nameat the destination
• The service shall throw an InvalidURI^? exception if a specified URI is invalid
• The service shall throw an InvalidArgument^? exception if a specified value is invalid

copyNode

Copy a node within a VOSpace service.

Note that this does not cover copying data between separate two VOSpace services.

Copying nodes between separate VOSpace services should be handled by the client, using the import and export methods.

Parameters

• source : The URI forof an existing Node

• destination : TheA template Node element describing the new location. Node.

The contents of the template will be used to update those of the new Node.

The value of the xsi:type attribute will ignored in the sense that type change is not permitted.

The accepts and provides lists of Views for the new Node cannot be set for a DataNode^? using this method.

Returns

• node : A node element forDetails of the new Node

Faults

• The service shall throw an InternalFault^? exception if anthe operation fails
• The service shall throw a PermissionDenied^? exception if the user does not have permissions to perform the operation

• The service shall throw a NodeNotFound^? exception if the targetsource Node does not exist
• The service shall throw a DuplicateNode^? exception if a Node already exists with the same nameat the destination
• The service shall throw an InvalidURI^? exception if a specified URI is invalid
• The service shall throw an InvalidArgument^? exception if a specified value is invalid

Manipulating metadata of data sets

getNode

Get the details for a specific Node.

Parameters

• target : The URI forof an existing Node

Returns

• node : A node element forDetails of the Node

The full expanded record for the node is returned, including any xsi:type specific extensions.

The provides list of Views may not be filled in until some data has been imported into the node.

Faults

• The service shall throw an InternalFault^? exception if anthe operation fails
• The service shall throw a PermissionDenied^? exception if the user does not have permissions to perform the operation
• The service shall throw a NodeNotFound^? exception if the target Node does not exist

setNode

Set the property values for a specific node.

Parameters

• node : A Node element for the nodecontaining a list of the Properties to set.

This will add or update node properties including type specific elements.

The operation is the union of existing values and new ones.

An empty value sets the value to blank.

To delete an element or Property, use xsi:nill="true" set the xsi:nill attribute to true

This method cannot be used to modify the Node type.

This method cannot be used to modify the accepts or provides list of Views for the Node .

Returns

• node : An updated node element forDetails of the Node

The full expanded record for the node is returned, including any xsi:type specific extensions.

Faults

• The service shall throw an InternalFault^? exception if anthe operation fails
• The service shall throw a PermissionDenied^? exception if the requests attempts to modify a readonly Property
• The service shall throw a PermissionDenied^? exception if the user does not have permissions to perform the operation
• The service shall throw a NodeNotFound^? exception if the target Node does not exist
• The service shall throw an InvalidArgument^? exception if a specified property value is invalid.

Notes

Some properties may be read-only e.g. MD5 checksum.

-- DaveMorris - 01 Mar 2007