Request and Operation Result

The repository web services operation takes a single input parameter of type String. This XML document represents the request. The following shows its DTD:

<!ELEMENT request (argument*, resourceDescriptor?)>
<!ATTLIST request
  operationName (get | list | put | runReport) "list"
  locale #IMPLIED
<!ELEMENT argument (#PCDATA)>
<!ATTLIST argument

A request is a very simple document that contains:

The operation to execute (list, get, put, delete, or runReport).
A set of optional arguments. Each argument is a pair of a key and a value that is used to achieve very particular results; arguments are only used rarely.
A resource descriptor.

The operation name is redundant, since the operation to execute is intrinsic in the invoked service. However, including the name can clarify the request document.

The services act on a single resource at time. The resource that is the subject of the request is described by a resourceDescriptor.

To get error messages in a particular locale supported by the server, specify the locale code with the locale attribute. Locale codes are in the form <language code>[_<country>[_<variant>]. Valid examples include en_US, it_IT, fr_FR, de_DE, ja_JP, and es_ES. For a list of Java-compliant locales, refer to Sun’s Java web site.

The following sample request lists the repository root:

<?xml version="1.0" encoding="UTF-8"?>
<request operationName="list" locale="en">
  <resourceDescriptor name="" wsType="folder" uriString="/">

Executing a service produces the operationResult in the form of a new XML document.

The DTD is very simple:

<!ELEMENT operationResult (code, message?, resourceDescriptor*)>
<!ATTLIST operationResult
<!ELEMENT message (#PCDATA)>

The operation result contains a return code, an optional return message, and zero or more resource descriptors. A return code other than 0 indicates an error, which is normally described in the message tag.

The operation result always includes the version attribute: it can be used to detect the server version. For example, you can list the repository root and read the version set by the server in the response. In this case, we aren’t interested in the root folder’s content. We just want the version information from the response object itself.

The operation result of such a request is:

<operationResult version="1.2.1">
  several resource descriptors...