VoSpace 2.x

CreateNode

Creates a new node in a space.

This is the primary method for creating new nodes in a VoSpace service.

The initial V1.0 specification only supports data nodes.

However, future versions of the spcification will add new types of nodes, including containers and links.

Parameters

• 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
  • ivo://org.astrogrid.vospace/types/link.node note
  • ivo://org.astrogrid.vospace/types/container note

• Properties - An optional set of name value properties for the new node
• Type specific data - Any additional data required to create the specific node type

An XML friendly way to include any type specific data required to create the node could be to start with 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>
    ....

Returns

A full <node> element for the new node, containing

• The full URI encoded identifier for the new 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
  • ivo://org.astrogrid.vospace/types/link.node note
  • ivo://org.astrogrid.vospace/types/container note

• Properties - The set of name value properties for the new node

Again, an XML friendly way to include any 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 new DataNode
            +-->
    </node>
    ....

Throws

• 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 will throw a DuplicateNode exception if a node already exists with the same name.

• The service may throw an OperationNotSupported exception if it does not support user defined names.

• 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 parent path includes a link. note
• The service will throw a LinkFound exception if the parent node is a link. note

Notes

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

• 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

• If the <name> in the request is null or empty, then the service will generate a new unique name for the node.

• Containers are not part of the V1.0 specification, they will be defined in a future version of the specification.

• 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

• Should the LinkFound exceptions be part of the V1.0 specification, or left until later ?

-- DaveMorris - 26 Apr 2006 -- DaveMorris - 16 May 2006