Developing applications using OGSA-DQP client toolkit classes

As described in the OGSA-DAI user doc, OGSA-DAI provides a set of Java classes that serve as a client toolkit for client applications developers. This allows them to construct OGSA-DAI workflows using Java objects and get data back as useful objects.

OGSA-DQP supplies two client toolkit classes which extend the OGSA-DAI client toolkit allowing you to write applications that interact with the DQP coordinator and so create DQP resources and run queries. Both the DQP command-line client and GUI client were written using these.

Naturally, this section assumes you are familiar with writing OGSA-DAI clients using the OGSA-DAI client toolkit.

DQP client toolkit classes

The DQP client toolkit classes are as follows:

uk.org.ogsadai.dqp.client.DQPFactory

Client-side proxy for the DQPFactory activity. This is used to build workflows that request a DQP factory resource be used to create a new DQP resource.

uk.org.ogsadai.dqp.client.DQPQuery

Client-side proxy for the DQPQueryStatement activity. This is used to build workflows that request a DQP resource execute an SQL query.

The DQP command-line client

uk.org.ogsadai.dqp.client.Client

which is in the directory:

ogsadqp-3.2.1-od30port/client/src

gives an example of how these classes can be used.

What needs to be in the `CLASSPATH`?

The OGSA-DAI client toolkit and other classes need to be in the CLASSPATH. See the following pages in the OGSA-DAI user doc:

For OGSA-DAI Axis 1.2.1 see OGSA-DAI Axis - set the CLASSPATH
For OGSA-DAI GT 4.0.5 see OGSA-DAI GT - set the CLASSPATH
Note that though these links take you to the OGSA-DAI 3.1 user guide the instructins are equally valid for OGSA-DAI 3.0.

You also need to ensure you have built the OGSA-DQP command-line client. If you have not already done so, this can be done as follows:

Change into the OGSA-DQP client directory:
```
$ cd ogsadqp-3.2.1-od30port/client
```
Build the client:
- If you are using OGSA-DAI Axis 1.2.1 then run:
```
$ ant compile.axis121 -Dogsadai.dir=$OGSADAI_HOME
```
- If you are using OGSA-DAI GT 4.0.5 then run:
```
$ ant compile.gt4 -Dogsadai.dir=$OGSADAI_HOME
```

You now need to add the OGSA-DQP client JAR to the CLASSPATH:

If using Linux/Unix run:

$ export CLASSPATH=ogsadqp-3.2.1-od30port/client/lib/client.jar:$CLASSPATH

If using Windows run:

$ set CLASSPATH=ogsadqp-3.2.1-od30port/client/lib/client.jar;%CLASSPATH%

How to contact a coordinator and use a DQP factory resource create a DQP resource

Firstly the required OGSA-DQP and OGSA-DAI classes must be imported:

import java.io.File;
import java.net.URL;

import uk.org.ogsadai.client.toolkit.DataRequestExecutionResource;
import uk.org.ogsadai.client.toolkit.PipelineWorkflow;
import uk.org.ogsadai.client.toolkit.RequestExecutionType;
import uk.org.ogsadai.client.toolkit.RequestResource;
import uk.org.ogsadai.client.toolkit.Server;
import uk.org.ogsadai.client.toolkit.ServerProxy;
import uk.org.ogsadai.client.toolkit.activities.delivery.DeliverToRequestStatus;
import uk.org.ogsadai.dqp.client.DQPFactory;
import uk.org.ogsadai.resource.ResourceID;

Now, create a server proxy for contacting the DQP coordinator and get a client side proxy for the OGSA-DAI data request execution resource that executes OGSA-DAI workflows:

URL baseURL = new URL("http://localhost:8080/dai/services/");

Server server = new ServerProxy();
server.setDefaultBaseServicesURL(baseURL);
ResourceID drerID = new ResourceID("DataRequestExecutionResource");
DataRequestExecutionResource drer =
	server.getDataRequestExecutionResource(drerID);

Create an instance of a client-side proxy for the DQPFactory activity, configure it with the DQP factory resource ID and the location of a DQP factory configuration document:

// DQP factory resource ID.
String resourceID = "DQPFactoryResource";
// DQP factory configuration document.
File dqpConfigFile = new File("dqpConfiguration.xml");

// DQPFactory activity
DQPFactory factory = new DQPFactory();
factory.setResourceID(resourceID);
factory.addDqpConfiguration(dqpConfigFile);

Note that addDqpConfiguration() method is overloaded and can accept either a File object or a org.w3c.dom.Document object.

This activity will be executed on the DQP factory resource identified by resourceID and configured according to a configuration held in dqpConfigFile.

Now, complete the workflow and execute the request:

DeliverToRequestStatus deliverToRequestStatus =
	new DeliverToRequestStatus();
deliverToRequestStatus.connectInput(factory.getResultOutput());

PipelineWorkflow pipeline = new PipelineWorkflow();
pipeline.add(factory);
pipeline.add(deliverToRequestStatus);

RequestResource requestResource =
	drer.execute(pipeline, RequestExecutionType.SYNCHRONOUS);
String dqpDataResID = factory.nextResult().toString();

The request will return a ID of the newly-created DQP resource. This ID is stored in the dqpDataResID and can be used in subsequent interactions.

Get the imported schemas resource property

Your client can be extended get the imported schemas resource property of a DQP resource as follows:

Import additional classes:

import uk.org.ogsadai.client.toolkit.Resource;
import uk.org.ogsadai.client.toolkit.ResourceProperty;
import uk.org.ogsadai.resource.ResourcePropertyName;
import uk.org.ogsadai.resource.ResourceType;

Ask the service to return the property:

String propertyNameStr =
    "http://ogsadai.org.uk/namespaces/2005/10/properties.importedSchemas";

Resource resource = server.getResource(
    new ResourceID(dqpDataResID), ResourceType.DATA_RESOURCE);

ResourceProperty resourceProperty = resource.getResourceProperty(
    new ResourcePropertyName(propertyNameStr));

String propertyString = resourceProperty.toString();

The imported schemas resource property value associated with DQP resource identified by dqpDataResID will be stored in the propertyString variable.

Execute a query

Your client can be extended to execute an SQL query using a DQP resource as follows:

Import additional classes:

import java.util.Vector;
import java.sql.ResultSet;
import java.sql.ResultSetMetaData;
import uk.org.ogsadai.client.toolkit.DataSourceResource;
import uk.org.ogsadai.client.toolkit.activities.delivery.WriteToDataSource;
import uk.org.ogsadai.client.toolkit.activities.transform.TupleToWebRowSetCharArrays;
import uk.org.ogsadai.dqp.client.DQPQuery;

Create an instance of a client-side proxy for the DQPQueryStatement activity, configure it with the DQP resource ID and the SQL query:

String query = 
    "SELECT ORF FROM proteinproperty_protein_property WHERE ORF LIKE 'YBL03%';";

DQPQuery dqpQuery = new DQPQuery();
dqpQuery.setResourceID(dqpDataResID);
dqpQuery.addExpression(query);

Create client-side proxies for activities to transform the data into WebRowSet XML format:

TupleToWebRowSetCharArrays tuplesToWRS =
    new TupleToWebRowSetCharArrays();
tuplesToWRS.connectDataInput(dqpQuery.getDataOutput());

Request that the OGSA-DAI service create an OGSA-DAI data source then create client-side-proxies to populate that data source with the WebRowSet XML data:

DataSourceResource dataSource = drer.createDataSourceResource();

WriteToDataSource writeToDataSource = new WriteToDataSource();
writeToDataSource.setResourceID(dataSource.getResourceID());
writeToDataSource.connectInput(tuplesToWRS.getResultOutput());

Assemble the workflow and submit it to the OGSA-DAI service (DQP coordinator):

pipeline = new PipelineWorkflow();
pipeline.add(dqpQuery);
pipeline.add(tuplesToWRS);
pipeline.add(writeToDataSource);

requestResource =
    drer.execute(pipeline, RequestExecutionType.ASYNCHRONOUS);

Stream the results back from the data source via an OGSA-DAI data source service on the server:

tuplesToWRS.getResultOutput().setDataSourceResource(dataSource);

Iterate through ResultSet to get the query rows.

ResultSet rs = null;
if (tuplesToWRS.hasNextResult())
{
    rs = tuplesToWRS.nextResultAsResultSet();
    ResultSetMetaData md = rs.getMetaData();
    // Get column names and initial column widths.
    int numColumns = md.getColumnCount();
    String[] columns = new String[numColumns];
    int[] widths = new int[numColumns];
    for (int i = 0; i < numColumns; i++)
    {
        String column = md.getColumnLabel(i + 1);
        columns[i] = column;
        widths[i] = column.length();
    }
    // Get ResultSet rows and update column widths also.
    Vector rows = new Vector();
    while (rs.next())
    {
        String[] fields = new String[numColumns];
        for (int i = 0; i < numColumns; i++)
        {
            Object field = rs.getObject(i + 1);
            if (field == null)
            {
                fields[i] = "null";
            }
            else
            {
                fields[i] = field.toString();
            }
            widths[i] = Math.max(widths[i], fields[i].length());
        }
        rows.add(fields);
    }
    rs.close();
    // Print column names.
    String tableHeading = "| ";
    for (int i = 0; i < numColumns; i++)
    {
        tableHeading += (pad(columns[i], widths[i]) + " | ");
    }
    System.out.println(tableHeading);
    // Print rows.
    int numRows = rows.size();
    for (int j = 0; j < numRows; j++)
    {
        String[] row = (String[]) rows.get(j);
        String rowString = "| ";
        for (int i = 0; i < numColumns; i++)
        {
            rowString += (pad(row[i], widths[i]) + " | ");
        }
        System.out.println(rowString);
    }
}

Previous: Use the OGSA-DQP GUI client