Response Documents

Whenever a client submits a perform document to a data service, a response document will be received in return. A response document describes the status of execution of a perform document and also identifies the session that the request was joined to. Depending on the activities specified in the perform document, the response document may also contain result data such as the XML-encoded results of a database query.

Document Structure

The client can parse the response document to determine whether the request completed successfully and extract any content that may be of interest. The root element of a response document is a element. The first child element is a element identifying the session that the request was joined to for processing. The second child element is a element describing the status of execution of the request. The remainder of the content of this document depends on the activities used within the original perform document.

A response document contains result elements corresponding to parts of the perform document.

Recall that perform documents contining end-points, such as myActivityOutput in the figure above, are processed synchronously. This means that the response document is only returned to the client once processing of the request is complete. For requests of this form, the response document will contain a element corresponding to each activity and end-point of the perform document. So the response document in the figure above contains two result elements, one for the activity named myActivity and the other for the end-point named myActivityOutput

Each element will contain a status attribute describing the status of execution of the activity or end-point. Those that represent end-points will also contain the result data that was written to that end-point during the activity processing. Result data is embedded within child CDATA sections. The structure and format of result data depends on the implementation of the activity producing the data. For example, the sqlResultsToXML activity produces WebRowSet XML data.

If a perform document contains no end-points, then the activities described within it can be processed asynchronously. Since there is no result data to embed with the response document, the response document can be returned to the client as soon as the request has been initialised. A response document corresponding to this form of request will contain only the and elements and no elements.

Example

The following perform document sends an SQL query to a relational database and transforms the results into WebRowSet XML. It will be processed synchronously because there is an end-point named webRowSetOutput.



  
    Perform a simple SELECT statement then transform the results
    into WebRowSet XML.
  
  myQuery"/>
    select * from littleblackbook where id=10
    
  
  
    
    webRowSetOutput"/>

If the request completes successfully, then a response document similar to the one shown below will be returned to the client:



  
  
  
  
  
    
      
      ...
      
         10
         John Smith
         123 Some Lane, AnyTown
         0131-555-1234
      
      ...
    ]]>

Notice that the result data has been enclosed within a CDATA section. The Client Toolkit APIs provide a simple way to access this data through the conventional java.sql.ResultSet interface.

Specification

A response document consists of a root response element belonging to the namespace https://ogsadai.org.uk/namespaces/2005/10/types. This element contains:

One session element with an id attribute identifying the session that the request was joined to for processing.
One request element describing the status of the request and giving details of the cause of any errors:
- One status attribute describing the status of the execution of the perform document. This takes one of the following values:
  - INITIALISING - the request is initialising.
  - PROCESSING - the request is still running.
  - COMPLETED - the request has successfully completed.
  - TERMINATED - the request has been terminated.
  - ERROR - the request encountered a problem.
- Zero or one cause attribute identifying the error that caused the request to fail. This attribute is only present if the request has failed and the status attribute value is ERROR.
Zero or more result elements describing the status of each activity and end-point within the perform document.
- One name attribute identifying the activity or end-point that the result corresponds to. This will match the name attribute of one of the activities or end-points defined in the perform document.
- One status attribute describing the processing status of the activity or end-point. This takes one of the following values:
  - UNSTARTED - the activity has not yet been started.
  - INITIALISING - the activity is initialising.
  - PROCESSING - the activity is still running.
  - COMPLETED - the activity has successfully completed.
  - TERMINATED - the activity has been terminated.
  - ERROR - the activity encountered a problem.
- Zero or one CDATA child node containing result data. Any result element corresponding to an end-point will contain such a child element. The format of the result data depends on the implementation of the activity that produced the data.

XML Schema

OGSA-DAI/schema/ogsadai/xsd/response.xsd