VoSpace 2.x

ListNodes

List the child nodes of a container.

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

Parameters

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

• Token - An optional continuation token from a previous request.
  • 5177-B8

• PageSize - A (optional) page size, indicating how many results per response.
  • 10

Returns

A continuation token, indicating that the list is incomplete. The client can use this token to request the next list of nodes in the sequence.

• A service specific contination token
  • 5177-B8

A list of <node> elements for each child 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 node

Throws

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

• The service may throw an InvalidToken exception if it does not recognise the continuation token.
• The service may throw an InvalidToken exception if the continuation token has expired.

• 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.

• 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

Notes

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

• 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 <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

• 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

• Need to define page size in more detail - is this a maximum, or an exact requirement ?

-- DaveMorris - 18 May 2006