Scratch page for working on the VOSpace specification.

These edits and suggestions are based on the following versions of the specification and WSDL.

• VOSpace service specification (Working Draft 11 March 2008)
• VOSpaceContract-v1.1-rc3.wsdl: Service WSDL definition
• VOSpaceTypes-v1.1-rc3.xsd: Message schema

-- DaveMorris - 03 Sep 2008
-- DaveMorris - 15 Sep 2008

---

Acknowledgements

This document derives from discussions among the Grid and Web Services working group of the IVOA. It is particularly informed by prototypes built by Matthew Graham (Caltech/, NVO) and David Morris (Cambridge, Astrogrid).

VOSpace data model

VOSpace 1.1 extends the VOSpace 1.0 data model by introducing two new node types: ContainerNode and LinkNode. A new element, capabilities, is also added to the Data top level Node node tType.

[DISCUSSION POINT: Should capabilities only exist on the ContainerNode?]

Why restrict it to ContainerNode or DataNode, why not move it up to the top level NodeType ?
The element is optional, so if a node does not have additional capabilities then it won't be used, but if someone were to come up with a reason for adding capabilities to a generic Node, then why prevent them from doing it ?

ContainerNode

ContainerNode describes a data itemnode that can contain other data itemsnodes. These can be of any type, including other ContainerNodes.

A ContainerNode has no data bytes associated with it directly but only with its contents -
Do we need to say this ?

in a tree representation, a ContainerNode is a branch whereas data objects are leaves.
Do we need to say this ?

ContainerNode extends DataNode and so has the following elements:

• uri: the vos:// identifier for the node, URI-encoded according to RFC2396[2].
• properties: a set of metadata properties for the node.
• accepts: a list of the views (data formats) that the node can accept.
• provides: a list of the views (data formats) that the node can provide.
• capabilities: a list of the additional capabilities that the node can provide.
• busy: a boolean flag to indicate that the data associated withsome operations on the node or its children cannot be accessedmay be blocked.

[DISCUSSION POINT: capabilities should be in this list as well since we are adding to the standard definition of DataNode ].

The busy flag ismay be used to indicate that an internal operation, such as the service implementation unpacking an archive format, is in progress and so none ofsome operations on the node data are availablemay be blocked.
Best to leave this ambiguous as it will probably be very implementation specific.

Container identifiers

Slashes in the URI path imply a hierarchical arrangement of data: for example the data object identified by

    vos://nvo.caltech!vospace/tables/myTable1

is within the container identified by

    vos://nvo.caltech!vospace/tables

In fact, aAll ancestors in the hierarchy willmust be resolvable as cContainerNodes, backall the way up to to the root node of the space (Note, this precludes any system of implied hierarchy in the naming scheme for nodes with ancestors that are just logical entities and cannot be reified, e.g. the Amazon S3 system).

Inheritable properties

Properties on a ContainerNode may be designated as inheritable and will propagate to children nodes of the container if they are specified in the accepts or provides list for this node.

[DISCUSSION POINT: If a property is also declared on a child, which value takes priority? How are properties registered as inheritable?]

Container views

ForIn VOSpace 1.1, a view of a ContainerNode isdescribes the data representation (format) of thea file or data stream that is transferredrepresents the combined contents of the node and its children.

If the view isdescribes an archive format (tar, zip, etc.) then the spacea service that accepts this view (format) for a ContainerNode will provide access to the archive contents as children nodes of the container.

Whether or not the spaceservice actually unpacks the archive is implementation dependent, but the service will behave as though it has done so.

For example, a client wishesmay want to to upload a tar file containing several images to a VOSpace service. If hethey associates it with (uploads it to) an Structured/UnstructuredDataNode then it will treated as a blob and its contents will be not be availableprocessed or interpreted by the server.

However, if hethey usesupload it to a ContainerNode with an accepts view of "tar" then the image files within the tar file will be represented as children nodes of the ContainerNode and accessible like any other data object within the space.

[DISCUSSION POINT: What are the names of the children nodes? Are these Structured/UnstructuredDataNodes? What is the default? How is this set?]
Implementation dependent, unless you want to open this up for further discussion.

[DISCUSSION POINT: How does the service identify what it considers to be archive formats?]
Implementation dependent, unless you want to open this up for further discussion.

If a service provides view is an archive format (tar, zip, etc.) view of a ContainerNode then the spaceservice will package the contents of the container and all its children nodes in the specified format.

LinkNode

LinkNode describes a node that points to another noderesource. These link target can be ofa URI that points to any type of resource, including other Link VOSpace Nodes (within the same VOSpace service or in another service), or external resources outside VOSpace altogether.
The XML schema defines the link target as anyURI, without any additional restrictions.
One of the use cases for LinkNodes was to be able to refer to data in existing ftp or http repositories without having to move the data.

A LinkNode has no data bytes associated with it.
Do we need to say this ?

LinkNode extends Node and so has the following elements associated with it:

• uri: the vos:// identifier for the node, URI-encoded according to RFC2396[2].
• properties: a set of metadata properties for the node.The properties do not propagate ...(moved to next paragraph)
• target: the identifiertarget URI, URI-encoded according to RFC2396[2], for the data object to which the LinkNode points.
• capabilities: a list of the additional capabilities that the node can provide.

Capabilities on a LinkNode might sound odd, but inheriting them from NodeType does not do any harm.
Who knows, someone might invent a RDF or OWL service that infers meaning from the link properties.

The properties of a LinkNode do not propagate to the target of the LinkNode. One use case is to enable third-party annotations to be associated with a data objectresource but without the data objectresource itself getting cluttered with unnecessary metadata. In this case, the client creates a LinkNode pointing to the data objectresource in question and then adds the annotations as properties of the LinkNode.
Changed data node to resource because one use case was to use VOSpace links to refer to and annotate or 'tag' things in external services, including IVOA registry entries.

Capabilities

A Capability isdescribes a third-party interface to a data objectnode. ItOne application of this would be to enables data access to a node or its contents usingother non-VOSpace methods a 3rd party service interface.

A Capability has the following members:

• uri: the Capability identifier
• endpoint: the endpoint URL to use for the third-party interface
• param: a set of parameters for the capability

[DISCUSSION POINT: Should there be any more members to a Capability, e.g. param to specify additional arguments that might be required for access?]
Capability params added to the list (and the XML schema).

Example use cases

A ContainerNode containsing image files and hasmay offer a DAL SIAP capability so that the images in the container can also be accessed using a SIAP service. In this way, a user could create a (DAL enabled) cContainerNode in VOSpace, droptransfer some images into it and then query the set of images using the SIAP interface.

Another example is a DataNode withthat provides an iRODS capability so that the data replication for this data object can be handled using the iRODS service API located at the specified endpoint.

Capability identifiers

Every new type of Capability requires a unique URI to identify the Capability. The rules for the Capability identifiers are similar to the rules for namespace URIs in XML schema. The only restriction is that it must be a valid (unique) URI.

• An XML schema namespace identifier can be just a simple URN, e.g. urn:my-namespace
• Within the IVOA, the convention for namespace identifiers is to use a HTTP URL pointing to the namespace schema, or a resource describing it.

The current VOSpace schema defines Capability identifiers as anyURI [TBD]. The only restriction is that it must be a valid (unique) URI.

• A Capability URI can be a simple URN, e.g. urn:my-capability

This may be sufficient for testing and development on a private system, but it is not scalablesuitable for use on a public service. For a production system, any new Capabilities should have unique URIs that can be resolved into a description of the Capability. Ideally, these should be IVO registry URIs that point to a description registered in the IVO registry:

• ivo://my-registry/vospace/capabilities#my-capability

Using an IVO registry URI to identify Capabilities has two main advantages:

• IVO registry URIs are by their nature unique, which makes it easy to ensure that different teams do not accidentally use the same URI
• If the IVO registry URI points to a description registered in the IVO registry, this provides a mechanism to discover how to use the Capability.

Capability descriptions

If the URI for a particular Capability is resolvable, i.e. an IVO registry identifier or a HTTP URL then it should point to an XML resource that describes the Capability. A CapabilityDescription should describe the third-party interface and how it should be used in this context. A CapabilityDescription should have the following members:

• uri: the formal URI of the Capability
• DisplayName: a simple display name of the Capability.
• Description: a text block describing the third-party interface and how it should be used in this context.

Note that at the time of writing, the schema for registering CapabilityDescriptions in the IVO registry has not been finalized.
We need to get this done before this spec is released..

UI display name

If a client is unable to resolve a Capability identifier into a description then it may just display the identifier as a text string:

• Access data using urn:edu.sdsc.irods

If a client can resolve the Capability identifier into a description then the client may use the information in the description to display a human readable name and description of the Capability:

• Access data using iRODS

Standard capabilities

The VOSpace team intend to register Capability URIs and CapabilityDescriptions for the core set of Capabilities, e.g.

• Cone Search URI to be defined
• SIAP URI to be defined
• SSAP URI to be defined
• TAP URI to be defined

However, this is not intended to be a closed list and different implementations are free to define and use their own Capabilities.
We need to get these done before this spec is released..

Views

These are unchanged from VOSpace 1.0 (Sec 3.3) with the addition of:

Default views

The following standard URIs will be used to refer to the default import and export views.

• Default import view URI to be defined
• Default export view URI to be defined

These are intended as an interim measure to make it easier to integrate existing applications into the VO.
Most if not all of our existing applications are format agnostic. By this I mean that they are capable of importing and exporting data using URLs, and in most cases it is fairly easy to add new handlers for vos://... base URIs.
However, in many cases, it would take a lot more work to add the additional functionality needed to display a list of available formats and allow the user to select the one they want.
With command line or non-interactive applications, we will need to find a way of passing an extra parameter to the application to tell it what view we want it to select.
All of this is possible in the longer term, but for now having a "just store this data" and "just get the data as-is" option makes the initial integration much easier.

Default import view

If a client imports data using this view, the data is treated as a binary BLOB, and stored as-is with no additional processing.

This is equivalent to the application/binary MIME type.

Note, this view is not mandatory, and the service may throw a ViewNotSupported exception if it does not accept this view.

In particular, this view cannot be used to import data into a StructuredDataNode, because the service needs to know about and understand the data format to be able to create the StructuredDataNode.

Note, this view is only valid for the data import operations, pullToVoSpace and pushToVoSpace.
If this view is requested in an export operation, pullFromVoSpace and pushFromVoSpace, then the service should throw a ViewNotSupported exception.

Default export view

If a client requests data using this view, the server will choose whichever of the available views it (the server) thinks is the most apporpriate, based on how the data is stored.

In a simple file based system, this will probably be the same format that the data was originally imported in.

In a database table system, then this will probably either be VOTable or cvs, depending on the level of metadata available.

Note, this view is not mandatory, and the server may throw a ViewNotSupported exception if it does not provide this view. However, in most cases it is expected that a service would be able to select an appropriate 'default' format for data held within the service.

Note, this view is only valid for the data export operations, pullFromVoSpace and pushFromVoSpace.
If this view is requested in an inport operation, pullToVoSpace and pushToVoSpace, then the service should throw a ViewNotSupported exception.

Web service operations

A VOSpace 1.1 service shall be a SOAP service with the following operations:

Service metadata

getProtocols

This is unchanged from VOSpace 1.0 (Sec 5.1.1).

getViews

This is unchanged from VOSpace 1.0 (Sec 5.1.2).

getProperties

This is unchanged from VOSpace 1.0 (Sec 5.1.3).
[DISCUSSION POINT: Is this true - do we want to denote inheritable propertiesin some fashion?]

getCapabilities

[DISCUSSION POINT: Do we want this operation?]
Personally, I think it would be easily confused with the VOSI getCapabilities and as it stands it would not give us the level of detail we would actually need.
Not all the capabilities will be available on all nodes, so the only way to find out what is actually available is to query the individual nodes themselves.

Creating and manipulating data nodes

createNode

Create a new node at a specified location.

Parameters

This is the same as VOSpace 1.0 (Sec 5.2.1.1) except that:

• the permitted values of xsi:type are:
  • vos:Node
  • vos:DataNode
  • vos:UnstructuredDataNode
  • vos:StructuredDataNode
  • vos:ContainerNode
  • vos:LinkNode

The name .auto replaces vos://null as the reserved URI to indicate an auto-generated URI for the destination.

i.e. Given the following URI

    vos://service/path/.auto

a service will causecreate a new unique URI for the node within

    vos://service/path

to be generated.

The capabilities list for the Node cannot be set using this method.

Returns

This is the same as VOSpace 1.0 (Sec 5.2.1.2) except that:

• the capabilities list for the Node may not be filled in until some data has been imported into the Node.

Faults

This is the same as VOSpace 1.0 (Sec 5.2.1.3) except that:

• The service shall throw a LinkFound exception if the parent path includes a link.
• The service shall throw a LinkFound exception if the parent node is a link.
• The service shall throw a ContainerNotFound exception if the parent path is not composed solely of ContainerNodes.

• If a parent node in the URI path does not exist, then the service must throw a ContainerNotFound exception.
  • For example, given the URI path /a/b/c, then the service must throw a ContainerNotFound exception if either /a or /a/b do not exist.

• If a parent node in the URI path is a LinkNode, then the service must throw a LinkFound exception.
  • For example, given the URI path /a/b/c, then the service must throw a LinkFound exception if either /a or /a/b are LinkNodes.

[DISCUSSION POINT: Do we need both a LinkFound and a ContainerNotFound exception or does the latter work for both cases?]
Yes, we need both. ContainerNotFound means it one of the parents is missing, LinkFound says it is there, but points to somewhere else.
If the service responds with a LinkFound exception, then the client can can resolve the link and try again.
If the service responds with a ContainerNotFound exception, then the clian can't do anything more.

deleteNode

Delete a node. When the target is a ContainerNode, all its children (the contents of the container) will also be deleted.

Parameters

This is unchanged from VOSpace 1.0 (Sec 5.2.2.1).

Returns

This is unchanged from VOSpace 1.0 (Sec 5.2.2.2).

Faults

This is the same as VOSpace 1.0 (Sec 5.2.2.3) except that:

• The service shall throw a LinkFound exception if the parent path includes a link.
• The service shall throw a ContainerNotFound exception if the parent path is not composed solely of ContainerNodes.

• If a parent node in the URI path does not exist, then the service must throw a ContainerNotFound exception.
  • For example, given the URI path /a/b/c, then the service must throw a ContainerNotFound exception if either /a or /a/b do not exist.

• If a parent node in the URI path is a LinkNode, then the service must throw a LinkFound exception.
  • For example, given the URI path /a/b/c, then the service must throw a LinkFound exception if either /a or /a/b are LinkNodes.

• If the target node in the URI path does not exist, then the service must throw a NodeNotFound exception.
  • For example, given the URI path /a/b/c, then the service must throw a NodeNotFound exception if /a/b/c do not exist.

listNodes

List nodes in a space. When a target URI is a ContainerNode, only direct (first generation) children of the node will be listed.

Parameters

This is the same as VOSpace 1.0 (Sec 5.2.3.1) except that:

• Wild cards can only be used in the final part of the URL path: for example, a/b/c/*.txt is allowed byut a/*/c/*.txt is not.

Returns

This is unchanged from VOSpace 1.0 (Sec 5.2.3.2).

Faults

This is unchanged from VOSpace 1.0 (Sec 5.2.3.3).
Given a/b/c/*.txt, what happens if b is missing ?
Given a/b/c/*.txt, what happens if b is a LinkNode ?
Returning an empty list isn't correct, because there may indeed be a file called xyz.txt at the other end of the link.
Returning a LinkFound exception is complicated by the fact that the client could have specified multiple paths in the request.

This is the same as VOSpace 1.0 (Sec 5.2.3.3) except that:

• If a parent node in one of the search paths does not exist, then the service must throw a ContainerNotFound exception.
  • For example, given the search path /a/b/*, then the service must throw a ContainerNotFound exception if either /a or /a/b do not exist.

• If a parent node in one of the search paths is a LinkNode, then the service must throw a LinkFound exception.
  • For example, given the search path /a/b/*, then the service must throw a LinkFound exception if either /a or /a/b are LinkNodes.

findNodes

Find nodes whose properties match the specified values.

Parameters

• token: An optional continuation token from a previous request
  • No token indicates a request for a new find operation.

The server may impose a limited lifetime on the continuation token. If a 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 requests in the response
  • No limit indicates a request for an unpaged response. However the server may still impose its own limit on the size of an individual response, splitting the results into more than one page if required.
• detail: The level of detail in the returned response
  • min: The response contains the minimum detail for each Node with all optional parts removed - However, the node type should still be returned in the xsi:type attribute.
  • max: The response contains the maximum detail for each Node, including any xsi:type specific extensions
  • properties: The response contains a basic node element with a list of properties for each Node with no xsi:type specific extensions.
• matches: A list of match elements identifying the properties and values to match against and whether these should applied in conjunction (and) or disjunction (or).

The match element has a uri attribute to identify the property to which it is applying. The regular expression against which the property values are to be matched is then specified as the value of the match element:

    <match uri="..."> regex </match>

The match elements can be combined in conjunction and/or disjunction by specifying them as subelements of <or> and <and> respectively. For example, the predicate "(property1 and property2) or property3" would be specified as:

    <or>
          <and>
               <match uri="property1"> regex </match>
               <match uri="property2"> regex </match>
          </and>
          <match uri="property3"> regex </match>
    </or>

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

[DISCUSSION POINT: Are wildcards allowed in the property URIs - find me all nodes where any property matches this regular expression? ]
Complicated enough as it is.

We need to define the regex syntax. POSIX seems to be the most widely supported.

At the last interop, we decided that this method would be optional.
The simplest way of doing this would be to define it as a separate capablity, outside the main vospace-1.1 capablity.
So a service that supported the findNodes method would register two capabilities, vospace-1.1 and vospace-1.1-find.
The two capabilities would not require separate service endpoints, both of the capabilities could use the same service endpoint.

Need to figure out how to describe this clearly in the specification.

Returns

• token: An optional continuation token, indicating that the response is incomplete
  • The client may use this token to request the next block of Nodes in the sequence
  • No token indicates 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 list of the Nodes matching the requested properties

Faults

• The service shall throw an InternalFault exception if the 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 PropertyNotFound exception if a particular property is specified and does not exist in the space
  • This does not apply if wildcards are allowed in the property URIs
• 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.

When the source is a ContainerNode, all its children (the contents of the container) will also be moved to the new destination.

When the destination is an existing ContainerNode, the source will be placed under it (i.e. within the container).

Parameters

This is unchanged fromthe same as VOSpace 1.0 (Sec 5.2.4.1) except that.

• =.auto= replaces vos://null as the reserved URI to indicate an auto-generated URI for the destination.
  i.e. vos://service/path/.auto will cause a new unique URI for the node within vos://service/path to be generated.

Returns

This is unchanged from VOSpace 1.0 (Sec 5.2.4.2).

Faults

This is the same as VOSpace 1.0 (Sec 5.2.4.3) except that:

• The service shall throw a DuplicateNode exception if a Node already exists at the destination unless it is a ContainerNode.

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

• The service shall throw a LinkFound exception if the parent path includes a link.
• The service shall throw a LinkFound exception if the parent node is a link.
  This would mean you can never move a LinkNode

• The service shall throw a ContainerNotFound exception if the parent path is not composed solely of ContainerNodes.

• The service shall throw an InvalidArgument exception if the source is a ContainerNode and the destination is not.

• The service shall throw a ContainerNotFound exception if the target node is a ContainerNode and does not exist.
  This would mean you can never move a ContainerNode

• The service shall throw an InvalidArgument exception if the source is a ContainerNode and the destination is notrequest attempts to change the node type.

• If a parent node in the source URI does not exist, then the service must throw a ContainerNotFound exception.
  • For example, given the source URI /a/b/c, then the service must throw a ContainerNotFound exception if either /a or /a/b do not exist.

• If a parent node in the source URI is a LinkNode, then the service must throw a LinkFound exception.
  • For example, given the source URI /a/b/c, then the service must throw a LinkFound exception if either /a or /a/b are LinkNodes.

• If the source node does not exist, then the service must throw a NodeNotFound exception.
  • For example, given the source URI /a/b/c, then the service must throw a NodeNotFound exception if /a/b/c do not exist.

• If a parent node in the destination URI does not exist, then the service must throw a ContainerNotFound exception.
  • For example, given the destination URI /x/y/z, then the service must throw a ContainerNotFound exception if either /x or /x/y do not exist.

• If a parent node in the destination URI is a LinkNode, then the service must throw a LinkFound exception.
  • For example, given the destination URI /x/y/z, then the service must throw a LinkFound exception if either /x or /x/y are LinkNodes.

• If the destination URI points to an existing DataNode, then the service must throw a DuplicateNode exception.
  • For example, given the destination URI /x/y/z, then the service must throw a DuplicateNode exception if /z/y/x is a DataNode.

• If the destination URI points to an existing LinkNode, then the service must throw a LinkFound exception.
  • For example, given the destination URI /x/y/z, then the service must throw a LinkFound exception if /z/y/x is a LinkNode.
    This is diffferent to a DataNode because the link may point to a ContainerNode. In which case, to be consistent, the client should resolve the link and place the results in the ContainerNode pointed to by the LinkNode.

copyNode

Copy a node with a VOSpace service.

When the source is a ContainerNode, all its children (the full contents of the container) get copied, i.e. this is a deep recursive copy.

When the destination is an existing ContainerNode, the copy will be placed under it (i.e. within the container).

Parameters

This is the same as VOSpace 1.0 (Sec 5.2.5.1) except that:

• .auto replaces vos://null as the reserved URI to indicate an auto-generated URI for the destination.
  i.e. vos://service/path/.auto will cause a new unique URI for the node within vos://service/path to be generated.

Returns

This is unchanged from VOSpace 1.0 (Sec 5.2.5.2).

Faults

This is the same as VOSpace 1.0 (Sec 5.2.5.3) except that:

• The service shall throw a DuplicateNode exception if a Node already exists at the destination unless it is a ContainerNode.

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

• The service shall throw a LinkFound exception if the parent path includes a link.
• The service shall throw a LinkFound exception if the parent node is a link.
  This would mean you can never copy a LinkNode

• The service shall throw a ContainerNotFound exception if the parent path is not composed solely of ContainerNodes.

• The service shall throw an InvalidArgument exception if the source is a ContainerNode and the destination is not.

• The service shall throw a ContainerNotFound exception if the target node is a ContainerNode and does not exist.
  This would mean you can never copy a ContainerNode

• If a parent node in the source URI does not exist, then the service must throw a ContainerNotFound exception.
  • For example, given the source URI /a/b/c, then the service must throw a ContainerNotFound exception if either /a or /a/b do not exist.

• If a parent node in the source URI is a LinkNode, then the service must throw a LinkFound exception.
  • For example, given the source URI /a/b/c, then the service must throw a LinkFound exception if either /a or /a/b are LinkNodes.

• If the source node does not exist, then the service must throw a NodeNotFound exception.
  • For example, given the source URI /a/b/c, then the service must throw a NodeNotFound exception if /a/b/c do not exist.

• If a parent node in the destination URI does not exist, then the service must throw a ContainerNotFound exception.
  • For example, given the destination URI /x/y/z, then the service must throw a ContainerNotFound exception if either /x or /x/y do not exist.

• If a parent node in the destination URI is a LinkNode, then the service must throw a LinkFound exception.
  • For example, given the destination URI /x/y/z, then the service must throw a LinkFound exception if either /x or /x/y are LinkNodes.

• If the destination URI points to an existing DataNode, then the service must throw a DuplicateNode exception.
  • For example, given the destination URI /x/y/z, then the service must throw a DuplicateNode exception if /z/y/x is a DataNode.

• If the destination URI points to an existing LinkNode, then the service must throw a LinkFound exception.
  • For example, given the destination URI /x/y/z, then the service must throw a LinkFound exception if /z/y/x is a LinkNode.
    This is diffferent to a DataNode because the link may point to a ContainerNode. In which case, to be consistent, the client should resolve the link and place the results in the ContainerNode pointed to by the LinkNode.

Accessing metadata

getNode

Get the details for a specific Node.

Parameters

This is unchanged from VOSpace 1.0 (Sec 5.3.1.1).

Can this be used to set the link target of a LinkNode ?

Returns

This is unchanged from VOSpace 1.0 (Sec 5.3.1.2).

Faults

This is the same as VOSpace 1.0 (Sec 5.3.1.3) except that:

• The service shall throw a LinkFound exception if the target path includes a link.

• If a parent node in the URI path does not exist, then the service must throw a ContainerNotFound exception.
  • For example, given the URI path /a/b/c, then the service must throw a ContainerNotFound exception if either /a or /a/b do not exist.

• If a parent node in the URI path is a LinkNode, then the service must throw a LinkFound exception.
  • For example, given the URI path /a/b/c, then the service must throw a LinkFound exception if either /a or /a/b are LinkNodes.

• If the target node in the URI path does not exist, then the service must throw a NodeNotFound exception.
  • For example, given the URI path /a/b/c, then the service must throw a NodeNotFound exception if /a/b/c do not exist.

setNode

Set the property values for a specific node.

Changes to inheritable properties on ContainerNodes will propagate to children nodes of the container where applicable.

Parameters

This is unchanged from VOSpace 1.0 (Sec 5.3.2.1).

Returns

This is unchanged from VOSpace 1.0 (Sec 5.3.2.2).

Faults

This is the same as VOSpace 1.0 (Sec 5.3.2.3) except that:

• The service shall throw a LinkFound exception if the target path includes a link.

• If a parent node in the URI path does not exist, then the service must throw a ContainerNotFound exception.
  • For example, given the URI path /a/b/c, then the service must throw a ContainerNotFound exception if either /a or /a/b do not exist.

• If a parent node in the URI path is a LinkNode, then the service must throw a LinkFound exception.
  • For example, given the URI path /a/b/c, then the service must throw a LinkFound exception if either /a or /a/b are LinkNodes.

• If the target node in the URI path does not exist, then the service must throw a NodeNotFound exception.
  • For example, given the URI path /a/b/c, then the service must throw a NodeNotFound exception if /a/b/c do not exist.

Transferring data

pushToVoSpace

Request a list of URLs to send data to a VOSpace node.

Parameters

This is unchanged from VOSpace 1.0 (Sec 5.4.1.1) except that:

[DISCUSSION POINT: If a Node already exists at the target URI and it is a ContainerNode, should it be overwritten by the target Node or should the target Node become a child of the ContainerNode? This also applies to pullToVoSpace.]
To be consistent, it should probably behave the same way as create, move and copy.
So the results end up inside the existing ContainerNode.

Returns

This is unchanged from VOSpace 1.0 (Sec 5.4.1.2).

Faults

This is the same as VOSpace 1.0 (Sec 5.4.1.3) except that:

• The service shall throw a LinkFound exception if the target path includes a link.
• The service shall throw a LinkFound exception if the target node is a link.
• The service shall throw a ContainerNotFound exception if the parent path is not composed solely of ContainerNodes.

• If a parent node in the URI path does not exist, then the service must throw a ContainerNotFound exception.
  • For example, given the URI path /a/b/c, then the service must throw a ContainerNotFound exception if either /a or /a/b do not exist.

• If a parent node in the URI path is a LinkNode, then the service must throw a LinkFound exception.
  • For example, given the URI path /a/b/c, then the service must throw a LinkFound exception if either /a or /a/b are LinkNodes.

• If the target node in the URI path is a LinkNode, then the service must throw a LinkFound exception.
  • For example, given the URI path /a/b/c, then the service must throw a LinkFound exception if /a/b/c is a LinkNode.

pullToVoSpace

Import data into a VOSpace node.

Parameters

This is unchanged from VOSpace 1.0 (Sec 5.4.2.1).

Returns

This is unchanged from VOSpace 1.0 (Sec 5.4.2.2).

Faults

This is the same as VOSpace 1.0 (Sec 5.4.2.3) except that:

• The service shall throw a LinkFound exception if the target path includes a link.
• The service shall throw a LinkFound exception if the target node is a link.
• The service shall throw a ContainerNotFound exception if the parent path is not composed solely of ContainerNodes.

• If a parent node in the URI path does not exist, then the service must throw a ContainerNotFound exception.
  • For example, given the URI path /a/b/c, then the service must throw a ContainerNotFound exception if either /a or /a/b do not exist.

• If a parent node in the URI path is a LinkNode, then the service must throw a LinkFound exception.
  • For example, given the URI path /a/b/c, then the service must throw a LinkFound exception if either /a or /a/b are LinkNodes.

• If the target node in the URI path is a LinkNode, then the service must throw a LinkFound exception.
  • For example, given the URI path /a/b/c, then the service must throw a LinkFound exception if /a/b/c is a LinkNode.

pullFromVoSpace

Request a set of URLs that the client can read data from.

Parameters

This is unchanged from VOSpace 1.0 (Sec 5.4.3.1).

Returns

This is unchanged from VOSpace 1.0 (Sec 5.4.3.2).

Faults

This is the same as VOSpace 1.0 (Sec 5.4.3.3) except that:

• The service shall throw a LinkFound exception if the target path includes a link.
• The service shall throw a LinkFound exception if the target node is a link.
• The service shall throw a ContainerNotFound exception if the parent path is not composed solely of ContainerNodes.

• If a parent node in the URI path does not exist, then the service must throw a ContainerNotFound exception.
  • For example, given the URI path /a/b/c, then the service must throw a ContainerNotFound exception if either /a or /a/b do not exist.

• If a parent node in the URI path is a LinkNode, then the service must throw a LinkFound exception.
  • For example, given the URI path /a/b/c, then the service must throw a LinkFound exception if either /a or /a/b are LinkNodes.

• If the target node in the URI path is a LinkNode, then the service must throw a LinkFound exception.
  • For example, given the URI path /a/b/c, then the service must throw a LinkFound exception if /a/b/c is a LinkNode.

• If the target node in the URI path does not exist, then the service must throw a NodeNotFound exception.
  • For example, given the URI path /a/b/c, then the service must throw a NodeNotFound exception if /a/b/c do not exist.

pushFromVoSpace

Ask the server to send data to a remote location.

Parameters

This is unchanged from VOSpace 1.0 (Sec 5.4.4.1).

Returns

This is unchanged from VOSpace 1.0 (Sec 5.4.4.2).

Faults

This is the same as VOSpace 1.0 (Sec 5.4.4.3) except that:

• The service shall throw a LinkFound exception if the target path includes a link.
• The service shall throw a LinkFound exception if the target node is a link.
• The service shall throw a ContainerNotFound exception if the parent path is not composed solely of ContainerNodes.

• If a parent node in the URI path does not exist, then the service must throw a ContainerNotFound exception.
  • For example, given the URI path /a/b/c, then the service must throw a ContainerNotFound exception if either /a or /a/b do not exist.

• If a parent node in the URI path is a LinkNode, then the service must throw a LinkFound exception.
  • For example, given the URI path /a/b/c, then the service must throw a LinkFound exception if either /a or /a/b are LinkNodes.

• If the target node in the URI path is a LinkNode, then the service must throw a LinkFound exception.
  • For example, given the URI path /a/b/c, then the service must throw a LinkFound exception if /a/b/c is a LinkNode.

• If the target node in the URI path does not exist, then the service must throw a NodeNotFound exception.
  • For example, given the URI path /a/b/c, then the service must throw a NodeNotFound exception if /a/b/c do not exist.

Fault arguments

This is the same as VOSpace 1.0 [Sec 5.5] with the addition of:

ContainerNotFoundFault

Thise is thrown withfault details must contain the URI of the missing ContainerNode.

LinkFoundFault

Thise is thrown withfault details must contain the URIfull details of the found LinkNode.

Appendix: Machine readable definitions

WSDL

A working draft version of the VOSpace 1.1 WSDL can be found on the IVOA VOSpace page at:
http://www.ivoa.net/twiki/bin/view/IVOA/VOSpaceHome.
Need to post the rc3 wsdl.

Message schema

A working draft version of the XML message schema for VOSpace 1.1 can be found on the IVOA VOSpace page at:
http://www.ivoa.net/twiki/bin/view/IVOA/VOSpaceHome.
Need to post the rc3 schema.

References

[VOSpace] Matthew Graham, Paul Harrison, Dave Morris, Guy Rixon,
VOSpace service specification v1.02, IVOA Recommendation 2007 October 01,
http://www.ivoa.net/Documents/latest/VOSpace.htm
http://www.ivoa.net/Documents/cover/VOSpace-20070907.html