Access Keys:
Skip to content (Access Key - 0)

Data Services

CQL 2 Technology Preview

The CQL 2 technology preview process has concluded and the technology has been migrated into caGrid data services as of release 1.4. Please see the official CQL 2 documentation for the most current information.

The CQL 2.0 Technology Preview allows interested parties an opportunity to investigate its suitability to their needs. Comments on the technology are welcome, and may help shape the final version of CQL 2.

Contents


Prerequisites

The CQL 2 technology preview requires the following software environment:

  • JDK 5 (1.5) or newer from Sun
    • Tested with 1.5.0_09
  • Ant 1.6.5
    • May also work with newer versions
  • caCORE SDK 4.0 Installation
  • An open internet connection
    • Required for Ivy to retrieve caGrid 1.2 packages
    • Only required at build time, if SDK is installed locally
    • Probably needs to be non-proxied and non-firewalled for remote SDK installations
  • Globus WS Java Core v4.0.3 patched with WS-Enumeration
    • Available from the caGrid GForge
    • Unpack the zip
    • Set the environment variable GLOBUS_LOCATION to point to the unpacked directory
    • If you have installed caGrid with the graphical installer, this is not required since the installer will retrieve and configure this for you
  • A checkout of the cagrid incubation project trunk 
    • svn checkout https://gforge.nci.nih.gov/svnroot/grid-incubation/trunk/grid-incubation/incubator
    • The relevant project is under incubator/projects/cql2preview
      • Portions of the build for the CQL 2 project depend on other parts of the incubator
    • The current version of the CQL 2 Technology Preview implementation should be considered a second beta.
NOTE: Since 2008-05-08, the CQL 2 Technology Preview is part of the caGrid Incubator project, and all further updates and changes will take place within that project. It is available on the NCICB GForge site. An older version of the CQL 2 Technology Preview is Beta 1, and may be obtained as a pre-packaged zip file from its GForge project at Ohio State University. Unzip this file into its own directory. Other files related to this project can be obtained from the same repository

Building

Once all prerequisites have been met, the technology preview software can be compiled. Throughout this document, the base directory where the CQL 2 Technology Preview software resides will be referred to as "$CQL2_LOCATION".

To retrieve the artifacts from caGrid 1.2 which the preview requires, the build process makes use of a remote Ivy repository. To compile the technology preview code itself, a standard Ant build file is provided. To retrieve the dependencies using Ivy, however, an additional build script is required. Execute the following commands:

 %> cd $CQL2_LOCATION

 %> ant -f dependencies-build.xml resolve-dependencies

This step may take several minutes depending on the speed of your internet connection and load on the Ivy repository server. This step should only need to be done once; subsequent builds will already have the artifacts needed by the project.

 %> cd $CQL2_LOCATION

 %> ant all

This step compiles the technology preview and generates Java libraries and class files in the build directory.

Packaging

The CQL 2 technology preview includes a graphical tool that packages the CQL 2 APIs, configuration, and libraries for linking to a caCORE SDK 4 client. Using the packager simplifies use of the public API. To start the configuration packager, run the following command:

 %> cd $CQL2_LOCATION

 %> ant configurePackage

The packager UI will open, which allows the developer to specify several configuration values the query API will need at runtime.
This tool indicates if any of the fields are in an error state by placing a small red X in the corner of each, which has a mouse-over tooltip that describes the problem.

Begin by selecting the output directory from the caCORE SDK 4.0 build. For example, this might be C:\caCore4Release\output. Next, select the XMI model which was used to construct this caCORE SDK system. This can be generated from either Enterprise Architect, or Argo UML, provided the version of those tools supported by caCORE SDK 4.0 is used. For example, this model might be found at C:\caCore4Release\models\sdk.xmi. Once the model file is selected, choose the appropriate file type with the radio buttons. Fill in the project name and version which will be assigned to the model. Typically, the project name will match the SDK application name, but this is not a requirement. Enter the caCORE SDK system application name in the field provided. This must match the application name determined from the contents of the output directory, and is used for deriving the appropriate URL through which the backend caCORE SDK system will be contacted, as well as locating appropriate configuration files. Fill in the hostname of the server which is running the SDK generated system. Since this technology preview tool connects exclusively through the caCORE SDK's remote API, even if the service is running locally, this field must be entered. Also, enter the network port number on which connections to the service can be made. Typically this will be port 8080, but can be configured. Finally, click the Build Configuration button. Select the location and name of the configured archive file. A zip file will be created which contains the required libraries and configuration files for the query API. This process may take a few minutes while a domain model is generated, and metadata regarding the domain data types is gathered. When complete, a dialog will appear indicating the location the resulting zip file was saved to.
Click the Exit button to leave the package configuration tool.

Example Values

The following values may be used in conjunction with the caCORE 4.0 example zip file supplied in the prerequisites section:

SDK Output Dir: W:\Projects\cql2\cacore40\cacore\output
Domain Model File: W:\Projects\cql2\cacore40\cacore\models\sdk.xmi
XMI Type: Enterprise Architect
Project Name: example40
Project Version: 4.0
Application Name: example40
Remote Host Name: http://sdkexamples.bmi.ohio-state.edu
Network Port: 8040

Using the Configuration Package

The zip file created by the configuration and packager tool configures the CQL 2 query API to use a specific caCORE SDK 4.0 backend data source, and can be used in projects that wish to make use of CQL 2 facilities. The package contains a .classpath file intended to be used with an Eclipse project.

  • Copy the generated zip file to the location where you'll create the new Eclipse project for testing CQL 2.
  • Unpack the zip file in the new project's directory. The zip file contains the following:
    • A directory named lib, which contains jar files from the caCORE SDK system, as well as caGrid and the CQL 2 technology preview.
    • A directory named config, which contains information the query processing tool will use, as well as a wsdd and castor mapping files which can serialize and deserialize caCORE SDK domain objects.
    • A directory named queries, which contains CQL 2 test queries against the SDK 4 example domain model.
    • The project's .classpath file is extracted, and contains entries for the required libraries from $GLOBUS_LOCATION, the package's lib directory. Also extracted is an xml file containing a pre-built <path> element for use with Ant build scripts.

Creating the Eclipse Project

In the Eclipse IDE, create a new Java project, and name it CQL2Testing. Change the radio button selection under Contents to the Create project from existing source option. Browse to the location where you unpacked the CQL2 configuration package zip file from the previous section. Click the Next button. In this screen, you should see a list of the libraries the CQL 2 configuration package included int he .classpath file.

There are no images attached to this page.

Click the link to Create new source folder. This is where the code for testing CQL 2 will reside. Name it src and click Finish. Click the Finish button on the project creation wizard to finalize creation of the Eclipse project. When this is done, you should have a new project in your Eclipse workspace which looks similar to the diagram at the left.

The QueryRunner API

This technology preview provides a simple public API in the class org.cagrid.cql2.preview.tools.QueryRunner. This class has two static initializers which may be used to obtain an instance of the query API:

  • public static QueryRunner createConfiguredQueryRunner()
    • Creates a QueryRunner instance which will use the default configuration settings.
    • These settings are derived from values in the file ''config/configuration.properties'', which the configuration packager tool creates.
  • public static QueryRunner createQueryRunner()
    • Creates an "unconfigured" QueryRunner instance, which will attempt to use some default settings.
    • Generally this will not be useful to end users, and is used for internal testing of the project.

Once an instance of the query runner API has been obtained, it may be used to inspect the various configuration settings it uses:

  • public ApplicationService getApplicationService()
    • Returns the SDK ApplicationService instance which will be used by the query processor
  • public DomainTypesInformation getDomainTypesInfo()
    • Gets the metadata derived from the Java domain objects, describing the class hierarchy
  • public DomainModel getDomainModel()
    • Gets the domain model which the query API exposes
  • public QNameResolver getQNameResolver()
    • Gets the utility class which resolves QNames of each domain object for the query processor
  • public InputStream getWsddInputStream()
    • Gets an input stream which references the contents of the generated client-config.wsdd file
    • This may be used for serialization and deserialization of the domain objects

The query runner provides a single method which takes CQL 2 queries and returns results:

  • public CQLQueryResults executeQuery(CQLQuery query) throws QueryProcessingException
    • The query processing exception may be thrown when configuration issues arise, the query fails in the SDK system, or serialization of results fails.

Example

To make use of the Query Runner API, start by creating a new class in the CQL2Testing project we created earlier in Eclipse. Right-click on the src source directory we created, and choose New -> Class. Name the new class SimpleCql2Testing, and check the box to create a public static void main(String[] args) method stub. Click Finish to create the new class.

Inside the new class, add the following import statements:

import gov.nih.nci.cagrid.common.Utils;
import gov.nih.nci.cagrid.cql2.components.CQLQuery;
import gov.nih.nci.cagrid.cql2.results.CQLQueryResults;

import java.io.StringWriter;

import javax.xml.namespace.QName;

import org.cagrid.cql2.preview.tools.QueryRunner;

The following example uses a simple main method to obtain a QueryRunner instance, load a query, execute it, and finally print the results as XML to the console:

    public static void main(String[] args) {
        try {
            QName resultsQname = new QName("http://CQL.caBIG/2/gov.nih.nci.cagrid.cql.Results", "CQLQueryResults");
            QueryRunner runner = QueryRunner.createConfiguredQueryRunner();
            CQLQuery query = (CQLQuery) Utils.deserializeDocument(
                "queries/allPayments.xml", CQLQuery.class);
            CQLQueryResults results = runner.executeQuery(query);
            StringWriter writer = new StringWriter();
            Utils.serializeObject(
                results, resultsQname, writer, runner.getWsddInputStream());
            System.out.println(writer.getBuffer().toString());
        } catch (Exception ex) {
            ex.printStackTrace();
        }
    }

When this class is run, output similar to the following should be seen on the console:

Configuration from file 'W:\Projects\cql2\testProject\config\configuration.properties'
Query Processor initiailzed in 749 ms
Query Processed in 590 ms
<ns1:CQLQueryResults targetClassname="gov.nih.nci.cacoresdk.domain.inheritance.childwithassociation.Payment" xmlns:ns1="http://CQL.caBIG/2/gov.nih.nci.cagrid.cql.Results">
 <ns1:ObjectResult>
  <ns2:Payment amount="5" id="5" xmlns:ns2="gme://caCORE.caCORE/4.0/gov.nih.nci.cacoresdk.domain.inheritance.childwithassociation"/>
 </ns1:ObjectResult>
</ns1:CQLQueryResults>

Additional testing CQL 2 queries are available in the queries directory of the test project.
Last edited by
David Ervin (238 days ago) , ...
Adaptavist Theme Builder Powered by Atlassian Confluence