CQL Query Processors

This page contains information pertaining to CQL 2 query processors used by caGrid 1.4 data services. CQL 2 query processors can handle CQL 1 queries at runtime through conversion by the caGrid Data Services infrastructure. For information specific to CQL 1 query processors, please refer to the caGrid 1.3 documentation.

The CQL 2 Query Processor is a pluggable implementation which handles the details of processing CQL 2 against some backend data source and produces a CQLQueryResults instance. The particular implementation used is determined by a value in the service's deployment properties, and an instance of the processor is loaded at runtime via reflection. The query processor may optionally supply a set of properties via the getRequiredParameters(). These properties may be configured prior to deployment of the service, and are passed into the query processor when it is first instantiated via the initialize() method. Additionally, the query processor may implement the method getParametersFromEtc(). This method returns a java.collections.Set<String> containing a subset of keys from the getRequiredParameters() method whose values should be returned as file system paths relative to the etc directory of the deployed grid service.

When a query is issued to the data service, the query will be passed along to the CQL 2 Query Processor instance's processQuery() method. This method may throw both a QueryProcessingException in the case of an error in handling the query and a MalformedQueryException in cases where the query was found to be invalid for any reason.

Implementation

All query processor implementations are required to extend the abstract base class gov.nih.nci.cagrid.data.cql2.CQL2QueryProcessor. This base class declares several methods which are meant to be overridden, however the only method a query processor is required to implement is the processQuery() method. This method takes a CQL 2 query and returns a CQLQueryResults instance. This method is declared abstract in the base class, which enforces this implementation requirement. Generally, this method should be able to translate CQL 2 into whatever native query language is required by the back end data resource, and translate the result set into a CQLQueryResults instance.

The base class also provides the processQueryAndIterate() method, which takes CQL 2 and returns an Iterator over CQLResult instances. A default implementation of this method is provided, however developers may wish to override it to obtain better performance or interact more efficiently with a lazy-loaded result set.

CQL Query Processors are designed to be configurable at runtime by a set of properties. These properties are modifiable via the data service extension to the Introduce toolkit, or manually by editing a configuration file once a service has been built. The base CQL 2 query processor class provides a method to retrieve required configuration parameters and their associated default values:

public Properties getRequiredParameters()
- This method is provided by default and returns an empty java.util.Properties instance. CQL implementers who require properties to be configured should override this method to return a populated Properties instance. If a property is optional, its value should be set to an empty string. All property keys must be valid Java identifiers meaning that there cannot be any spaces or punctuation in the key.

Additionally, a method is provided to specify a subset of those properties are meant to be file locations:

getParametersFromEtc()
- This method returns a java.util.Set<String> containing a subset of keys from the getRequiredParameters() method whose values should be returned as file system paths relative to the etc directory of the deployed grid service.

The query processor base class has two protected methods which provide access to any user configured parameters and an input stream to the server side wsdd configuration file. The method getConfiguredParameters() returns a java.util.Properties instance containing all the keys defined in the properties returned by getRequiredParameters(), but with either the default or a developer configured value associated with each. The method getConfiguredWsddStream() returns an InputStream instance which will read in the contents of the server side wsdd configuration file. The call to the query processor's initialize method, and in turn the population of these values, occurs when the data service is first instantiated, typically when the container is started. Calls to these methods before this time will return null. For this reason, the constructor of the CQL 2 Query Processor implementation must be fairly simple, and any initialization should take place in the overridable initialize() method.

    /**
     * The primary query processing method.
     * 
     * @param query
     * @return
     * @throws QueryProcessingException
     *      Thrown when an error occurs while handling the query
     * @throws MalformedQueryException
     *      Thrown when the query is found to be defective
     */
    public abstract CQLQueryResults processQuery(CQLQuery query) throws
        QueryProcessingException, MalformedQueryException;

The only method which is absolutely required to be implemented by CQL 2 query processors is the processQuery() method. This is the method which executes the CQL 2 query against its data source and generates an appropriate set of results. There are utilities (discussed in the CQL 2 documentation) to make generation of this result set a relatively simple process. At the time this method is called by the data service infrastructure, the return values of getConfiguredParameters() and getConfiguredWsddStream() will be non-null.

The processQuery() method throws both a MalformedQueryException and a QueryProcessingException. Malformed query exceptions should be thrown under conditions where the query is somehow incorrect syntactically, or uses features of the CQL 2 language which are not yet supported in the query processor implementation. If query syntax validation is enabled in the data service infrastructure, then it may be assumed that all queries reaching the processQuery() method are at least well formed CQL 2. Query processing exceptions should be thrown when some error occurs which prevents successful resolution of the query request. These conditions may include database errors, file system problems, or misconfiguration of properties.