Performing Queries

A data service's perform operation accepts requests which are composed of activities. These requests are forwarded by the data service to the target data service resource where they are processed. Activities are the base tasks that the data service resource can perform on your behalf. An activity may expose a capability of the underlying data resource, such as the ability to perform an SQL query on a relational database, or may perform any other kind of operation, such as transforming data from one structure to another using an XSL Transform. Activities can be pipelined so that the output of one activity can be connected to the input of another activity, and in this way chains of two or more activities can be formed. A particular data service resource supports a particular set of activities specified in a configuration file.

The client toolkit provides a client activity class corresponding to each activity provided with OGSA-DAI. The responsibilities of a client activity class are twofold. Firstly, to generate the XML fragment required to run the corresponding activity at the data service resource, and secondly, to provide convenient methods for accessing the results of the activity. All client activity classes implement the abstract uk.org.ogsadai.client.toolkit.activity.Activity class which provides common functionality for connecting activities into pipelines and accessing result data. An ActivityRequest object is used to collect together a number of activities into a single request ready for submission.

This page shows you how to run simple SQL and XPath queries against a database using client activities.

Performing a Basic SQL Query

In this example you will run a simple SQL query across a MySQL database and print out the results. For example, select * from littleblackbook where id='3475' will select a single row from the table littleblackbook.

Locate a data service as was described on a previous page.
Construct a new SQLQuery object from your SQL query string. SQLQuery extends the Activity class.
```
SQLQuery query = new SQLQuery("select * from littleblackbook where id='3475'");
```
Connect the output of the SQLQuery activity to a WebRowSet activity to encode it as an XML document which can be delivered in the response.
```
WebRowSet rowset = new WebRowSet( query.getOutput() );
```

Now construct an ActivityRequest object and add the two activities.

ActivityRequest request = new ActivityRequest();
request.add( query );
request.add( rowset );

Now call the perform method which will then call the Perform operation of the data service and run the activities contained in the request. This will execute the query and return the results in a Response object.
```
Response response = service.perform( request );
```
Have a look at the results. You can convert the Response object to a string as follows:
```
String responseString = response.getAsString();
```
The response is an XML document which contains a result element for each activity. Each result describes the status of its activity (COMPLETED, ERROR, UNSTARTED) and holds data that the activity may have produced. In this example, these are the results of the SQL query in WebRowSet format.

See OGSA-DAI/examples/src/uk/org/ogsadai/examples/clienttoolkit/SimpleSQLQueryExample.java for an example solution.

Performing a Sequence of Queries

When you have more than one query, you can wrap a number of operations into one request.

First, construct two SQL queries from strings as shown above.

SQLQuery query1  = 
  new SQLQuery("select * from littleblackbook where name like '%Krause'");
WebRowSet rowset1 = new WebRowSet( query1.getOutput() );
SQLQuery query2  = 
  new SQLQuery("select * from littleblackbook where name like '%Sugden'");
WebRowSet rowset2 = new WebRowSet( query2.getOutput() );

Now construct a Request object. The Request constructor takes an array of Activity objects as an argument, such as SQLQuery.
```
Request request = new ActivityRequest( 
		new RequestComponent[] { query1, rowset1, query2, rowset2 }  );
```

Alternatively, you can create an empty request and add activities to it one by one. This enables you to add a number of activities using a loop, for example.

ActivityRequest request = new ActivityRequest();
SQLQuery query = new SQLQuery("select * from littleblackbook where id = '2359'");
request.add( query );
WebRowSet rowset = new WebRowSet( query.getOutput() );
request.add( rowset );

When the request is sent to the data service resource it will perform the sequence of queries and return the results in one response document.
```
Response response = service.perform( request );
```

See OGSA-DAI/examples/src/uk/org/ogsadai/examples/clienttoolkit/SQLQuerySequence.java for an example solution.

Performing a Parameterised SQL Query Repeatedly

This example demonstrates how to evaluate a parameterised SQL query repeatedly against the same data resource, changing the parameter values for each iteration.

Construct a new ActivityRequest.

ActivityRequest request =  new ActivityRequest();

You have to create a new SQLQuery object for each iteration:
```
SQLQuery query = new SQLQuery("select * from littleblackbook where id>? and id<?");
```
The "?" represent SQL parameters placeholders as per usual.
You can add parameter values to your query as follows:
```
query.setParameter(1, String.valueOf(i));
query.setParameter(2, String.valueOf(i + 20));
```
The first argument is the position of the parameter in the SQL string (starting with 1) and the second argument is the value of the parameter.
When your query is ready, add it to the request:
```
request.add( query );
```

You will also need a WebRowSet activity for each iteration:

WebRowSet rowset = new WebRowSet( query.getOutput() );
request.add( rowset );

Write a request which retrieves blocks of rows with IDs between 100 and 120, 1100 and 1120, ..., 9100 and 9120.

See OGSA-DAI/examples/src/uk/org/ogsadai/examples/clienttoolkit/ParameterisedSQLQuery.java for an example solution.

Performing an XPath Query on an XML Database

If you have access to an XML database, you can perform XPath queries using the XPathQuery object. The request is performed as before. For example, the XPath expression /entry[@id<10] selects all entry elements with an attribute id whose value is less than 10.

XPathQuery query = new XPathQuery( "/entry[@id<10]" );

See OGSA-DAI/examples/src/uk/org/ogsadai/examples/clienttoolkit/SimpleXPathQueryExample.java for an example.