caGrid Data Services provide a standard query method which all data services have in common. This query method is exposed to the grid via a uniform WSDL using request and response messages of a consistent namespace and type. This allows for a uniform client to invoke any arbitrary data service. Such a client is provided with the data services infrastructure, along with several helper classes. This is also true for data services which support WS-Enumeration or caGrid Bulk Data Transfer.
Data services in caGrid use CQL to compose queries. A query can be produced programmatically, building up parts of the query using the supplied object model.
Alternatively, a CQL query can be loaded from a string of XML text, or an XML file and deserialized into the object model.
The generic data service client can be initialized simply by passing the URL of the remote data service service to the constructor:
The generic data service client has only the query method in its public API. To make use of any additional methods you may have added to your service, the specific client generated by Introduce for your service must be used.
A query can be submitted to the standard data service client, which will return the query results when processing is complete. The query method can throw two typed exceptions:
- Query Processing Exception
- Thrown when an error occurs in actually processing the query or formulating a result set. This might include database errors and misconfiguration of the query processor.
- Malformed Query Exception
- This is generally thrown from the query validation process, and indicates a query which violates the CQL schema, or attempts to reach parts of a domain model which are either excluded from queries or do not exist.
- Query processor implementations may also throw this exception in response to queries which attempt to use features of CQL which are not supported by that particular implementation (eg. Attribute Results)
The results of a CQL query are returned in an object model which can hold one of either object results, attribute results, or a count result. These results can be iterated as single items using a specialized implementation of the standard Java Iterator interface.
Alternatively, the data service infrastructure provides a simplified handle class which hides the complexity of setting up an iterator to handle the query results.
Just as the standard data service client, the enumeration data services client can be initialized with the URL of your grid service:
The generic enumeration client supports a single method:
When this method is invoked, the service executes the CQL query as it would for a standard data service, but rather than returning the result directly, an enumeration resource is created to store the results, and an EnumerationResponseContainer instance is returned.
The EnumerationResponseContainer is a caGrid data type which encapsulates both the WS-Enumeration spec EnumerationContext and the endpoint reference (EPR) of the enumeration service context and the resource key of created enumeration resource. More information on caGrid's support for WS-Enumeration is provided here.
The data service infrastructure provides tooling to assist in creating a ClientEnumIterator instance which can communicate with the remote enumeration service context.
The contents of each SOAP Element are an XML representation CQLObjectResult instances, and can be deserialized as such.
Alternatively, the whole querying and result handling process can be condensed to a few lines using the supplied EnumDataServiceHandle class:
As with all service clients, the generic BDT Data Service client can be initialized with the URL of the remote data service:
The generic BDT data service client implementation exposes one public query method:
The returned BulkDataHandlerClient can be used to invoke either the WS-Enumeration or WS-Transfer support methods.
In the case of using enumeration from BDT, the result handling is exactly the same as for a data service with enumeration.
For WS-Transfer's get method, the returned xsd AnyType contains the serialized XML of the CQLQueryResults, and can be handled as it is in a standard data service query.