Changes From FQP 1.3

The Federated Query Processor in caGrid 1.4 contains improvements and changes over the previous version, while maintaining backwards compatibility with the existing web interface and client API.

	Contents DCQL 2 Support Client API Federated Query Processor Client

DCQL 2 Support

caGrid 1.4 data services now support CQL 2, the successor language to CQL. In conjunction with this new query language, the Federated Query Processor now supports DCQL 2, which incorporates the new features of CQL 2. Internally, the Federated Query Engine and FQP service utilize DCQL 2 and CQL 2 constructs when building sub queries. When a data service which does not support CQL 2 is encountered, the Federated Query Engine converts the outgoing query to CQL 1 and then upconverts the results to CQL 2 to continue processing internally. If the original DCQL 2 query utilizes features of CQL 2 or DCQL 2 which are not present in CQL 1 or DCQL 1, an exception will be thrown indicating which service in the query doesn't support the requested feature.

Client API

In support of DCQL 2, new methods have been added to the public API of the Federated Query Engine and Federated Query Processor service. These methods exist in parallel to the methods related to DCQL 1, however the DCQL 1 methods have been marked as deprecated in their Javadoc and in the caGrid deprecation plan as well. A new results retrieval resource has been created as well for dealing with DCQL 2 results, however its API mimics the existing one for handling DCQL 1 results.

Federated Query Processor Client

The new public methods on the Federated Query Processor Client are as follows:

• executeQuery: Executes a DCQL 2 query and returns a DCQLQueryResultsCollection instance, the DCQL 2 results container.
• executeQueryAndAggregate: Executes a DCQL 2 query and returns a CQLQueryResults instance, the CQL 2 results container. Results from individual data services are aggregated into a single results instance, which can be handled with any existing CQL 2 results handling APIs.
• queryAsynchronously: This method is a single substitute for all the previously available asynchronous query methods from DCQL 1. This method returns a FederatedQueryResultsRetrievalClient instance, which can be used to retrieve the results of the federated query at a later time. It takes three parameters:
  • A DCQL 2 query to execute
  • A delegated credential reference (optional)
    • If supplied, the Federated Query Processor will obtain the referenced credential and queries to data services involved in the DCQL 2 query will be made using the identity in that credential.
  • Query Execution Parameters (optional)
    • If supplied, these execution parameters inform the Federated Query Processor of how to handle failed queries, the number of retries to make to failing data services, etc.

The FederatedQueryResultsRetrievalClient has the following public API:

• isProcessingComplete: Returns a boolean flag indicating if all query processing operations have completed and results are ready to be retrieved.
• getExecutionStatus: Returns a FederatedQueryExecutionStatus instance which indicates the current state of federated query processing, which data services have returned results, etc.
• getAggregateResults: Gets the results of the query processing operation as a single, unified CQL 2 query results instance.
• getResults: Gets the DCQL 2 query results.
• enumerate: Retrieves the results of query processing using WS-Enumeration.
• transfer: Retrieves the results of query processing using WS-Enumeration.

In the case of the results retrieval methods, an exception will be thrown if processing has not completed, or if an irrecoverable error occurred while processing the DCQL 2 query on the service.