How to Implement CQL Query Processors

The CQL Query Processor is a component of caGrid Data Services which handles the process of querying a data resource and returning appropriate results. The query processor should support all parts of the CQL specification, including query modifiers.

Requirements

All query processor implementations are required to extend the abstract base class gov.nih.nci.cagrid.data.cql.CQLQueryProcessor. 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 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 into whatever native query language is required by the back end data resource, and translate the result set into a CQLQueryResults instance.

Optional Functionality

The query processor base class gov.nih.nci.cagrid.data.cql.CQLQueryProcessor declares several additional public methods which may be overridden to add functionality and configurability to a query processor:

• getRequiredParameters()
  • This method returns a java.util.Properties instance, containing keys and default values used in configuration of a query processor. A query processor implementation may, for example, require a database username and password, both of which could be defined here.
  • When a query processor is selected in the Introduce Toolkit, these properties are displayed and the service developer is given the opportunity to edit them. During this process, the query processor class is instantiated and the getRequiredParameters() method is invoked. For this reason, the query processor's constructor and getRequiredParameters() method should not perform any operations other than returning this required properties set.
• getPropertiesFromEtc()
  • This method returns a java.util.Set 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.
• getConfigurationUiClassname()
  • This method returns a string identifying the class name of the query processor's configuration UI. This UI must extend from the base class gov.nih.nci.cagrid.data.cql.ui.CQLQueryProcessorConfigUI. This UI may be used to perform more sophisticated configuration of a query processor than can be provided with a simple set of property keys and values.
• initialize()
  • This method takes a java.util.Properties instance and a java.io.InputStream. The properties contain the configured version of the properties specified by the return value of getRequiredParameters(), and the input stream loads the server-config.wsdd file. This may be useful for serializing or deserializing object instances, and is required by some of the query results utilities.
  • If this method is overriden, be sure to call super.initialize() first, as this will both validate and store the properties and wsdd input streams.
  • This method is called once per query processor instance, and there is only one instance of the query processor in each data service.
  • Only after this method has been called will getConfiguredParameters() return value be non-null. The same rule applies to the getConfiguredWsddStream() method.

Utilities

The data service infrastructure provides a few utilities which may prove helpful when implementing a CQL Query Processor. These utilities are discussed in more detail in the Utility APIs section of the data services documentation:

• gov.nih.nci.cagrid.data.utilities.CQLResultsCreationUtil
  • This class provides methods for creating object, attribute, and count results given a list of objects, attributes, or a result count. The return value from each of its static methods is a CQLQueryResults object, which may be returned by the processQuery() method without any further implementation required.
• gov.nih.nci.cagrid.data.utilities.DomainModelUtils
  • This class provides methods for navigating and extracting information from a Data Service's domain model, such as all superclasses of a given class. This information may be useful for navigating object hierarchies.

Using the Query Processor

All CQL Query Processors are expected to be packaged into a jar file, which can be selected with the Introduce Data Extension GUI. This packaging allows for portability and containment of the implementation in a single file. There is no need to place the jar file in the service's library path manually, as the extension copies it in when the jar is selected.