In order to call xml-space services, a client must send the xml-space server an xml 'command document', and will receive an xml 'response document' in reply. The command document contains the set of operations to be executed on the space, together with any associated data; the response document contains the results of these operations.

The listing below shows a very simple xml-space command document, which has been taken from our 'XML Ping-Pong' example.

It can be seen that the outer document element is an <xmlspace-commands> element, which can contain one or more <xmlspace-operation-set> elements.


    <?xml version='1.0' ?>

    <xmlspace-commands>
      <xmlspace-operation-set>
        <operation-put>
          <space-entry xtype="ping">
            <description>a ping message.</description>
            <header>
              <attribute name="count" value="#count" />
            </header>
            <body />
          </space-entry>
        </operation-put>
      </xmlspace-operation-set>
    </xmlspace-commands>

Note: In the above '#count' represents an integer variable.

The 'xmlspace-commands' element

This is the outer element of an xml-space command document, which can contain one or more 'xmlspace-operation-set' elements. For a detailed understanding of the structure of this document, refer to the xml schema definition.

The 'xmlspace-operation-set' element

This element gives a degree of control over the order of execution of operations within the xml-space core. Where possible, all of the operations in an operation set, some of which might be 'blocking', will be executed in parallel by the xml-space core, and are therefore completed in an indeterminate order.

However, when space operations are in separate operation sets, then those operations in earlier sets are guaranteed to have completed before those operations in later sets start.

For more details see the RCRT XML-Space Technical Manual.

An operation set element can contain an arbitrary number of consecutive xml-space operations, a list of which is given in the table below.

XML-Space Operations

This table below shows a list of the operations that are supported by the xml-space API:

»	operation-getentrycount	Returns the number of entries in the space.
»	operation-gettypecount	Returns the number of different types of entry in the space.
»	operation-getpartitioncount	Returns the number of entry partitions in the space.
»	operation-getxmlvolume	Returns the total number of xml characters in the space.
»	operation-getxspaceentropy	Returns the partition entropy of the space.

»	operation-put	Puts an entry into the space.
»	operation-multiput	Puts multiple entries into the space.
»	operation-read	Reads an entry from the space that matches a given xml template. This is a blocking operation with a user-defined time-out.
»	operation-take	Takes an entry from the space that matches a given xml template. This is a blocking operation with a user-defined time-out.
»	operation-find	Finds an entry in the space that matches a given xml template. This is a blocking operation with a user-defined time-out. Note: this does not return the space entry, but instead returns a boolean flag indicating whether a matching entry was found.

»	operation-readifexists	Reads an entry from the space that matches a given xml template. This is not a blocking operation, and will return straight away whether or not a matching entry is found.
»	operation-takeifexists	Takes an entry from the space that matches a given xml template. This is not a blocking operation, and will return straight away whether or not a matching entry is found.
»	operation-findifexists	Finds an entry in the space that matches a given xml template. This is not a blocking operation, and will return straight away whether or not a matching entry is found. This does not return the space entry, but instead returns a boolean flag indicating whether a matching entry was found.

»	operation-multireadifexists	Reads multiple entries from the space that match a given xml template. The maximum number of entries to be read is specified in the call. This is not a blocking operation, and will return straight away whether or not any matching entries are found.
»	operation-multitakeifexists	Takes multiple entries from the space that match a given xml template. The maximum number of entries to be taken is specified in the call. This is not a blocking operation, and will return straight away whether or not any matching entries are found.
»	operation-multifindifexists	Finds multiple entries in the space that match a given xml template. The maximum number of entries to be found is specified in the call. This is not a blocking operation, and will return straight away whether or not any matching entries are found. Note: This does not return the entries, but instead returns a boolean flag indicating whether any matching entries were found.