The Client Toolkit Tutorial

Introduction

These pages introduce the OGSA-DAI Client Toolkit, a Java API that provides the basic building blocks for OGSA-DAI client development. Using these APIs, a developer can construct anything from a basic query client to a complex distributed data integration client with relative ease. The Client Toolkit minimises the specialist knowledge required to interact with OGSA-DAI services and provides some protection from future changes to the data service interfaces. It also operates transparently with OGSA-DAI data services compliant with both WS-I and WSRF.

The main concept of the Client Toolkit is that of an activity. An activity dictates an action that is to be performed by a data service resource. OGSA-DAI provides many different types of activity to perform operations such as SQL queries, XSL transformations and FTP data delivery. The Client Toolkit provides a simple mechanism for assembling requests describing multiple activities, then submitting the request to data service resources for processing. The steps involved in a typical interaction are summarised below:

1. Locate a data service resource
2. Construct a number of activities
3. Chain them together and assemble an activity request
4. Send the activity request to the data service resource for processing
5. Interpret the results of the activities

The remainder of these pages consists of practical examples with sample code. Starting with a basic query, the examples become progressively more complex, ending up with a distributed query data integration scenario. Examples for using security on OGSA-DAI WSRF are contained in the section WSRF (GT4) examples at the bottom of this page. A list of prerequisites that should be satisfied before following the examples is below.

Prerequisites

1. We assume that OGSA-DAI services are running on http://localhost:8080/.
2. MySQL and eXist test databases have been set up with the OGSA-DAI example data - how to set up these databases is described on these pages.
3. The MySQL database can be accessed via:
   • An OGSA-DAI WSRF service located at http://localhost:8080/wsrf/services/ogsadai/DataService and resource ID MySQLResource or
   • An OGSA-DAI WSI service located at http://localhost:8080/axis/services/ogsadai/DataService with resource ID MySQLResource.
4. The eXist database can be accessed via:
   • An OGSA-DAI WSRF service located at http://localhost:8080/wsrf/services/ogsadai/DataService and resource ID ExistResource or
   • An OGSA-DAI WSI service located at http://localhost:8080/axis/services/ogsadai/DataService with resource ID ExistResource.

How to Compile and Run the Examples

We provide an ANT file build-examples.xml which allows you to build and run the examples:

• Running the following compiles all the classes within OGSA-DAI/examples/src to OGSA-DAI/build/examples:

  $ ant -f build-examples.xml compileExamples
  

• Running the following compiles all the classes within OGSA-DAI/examples/src and JARs these into OGSA-DAI/lib/ogsadai-examples.jar:

  $ ant -f build-examples.xml jarExamples
  

• Running the following runs an example:

  $ ant -f build-examples.xml runClient -Ddai.class=your.Class
  

  So, for example to run the simple example you'd use:

  ant -f build-examples.xml runClient \
    -Ddai.class=uk.org.ogsadai.examples.clienttoolkit.SimpleExample
  

For Advanced Users - the CLASSPATH

If you are an advanced user and like using the CLASSPATH then you need to ensure you have the following in your CLASSPATH:

• OGSA-DAI/build/examples
• Every JAR in OGSA-DAI/lib/
• Every JAR in OGSA-DAI/thirdparty/
• CLASSPATH
• If communicating with OGSA-DAI WSRF services (whether using OGSA-DAI WSRF or OGSA-DAI WSI) you will also need to ensure that the file client-config.wsdd is in a directory that is in the CLASSPATH:
  • In OGSA-DAI WSRF this file is in OGSA-DAI (the root directory of the distribution).
  • In OGSA-DAI WSI this file is in OGSA-DAI/skeletons.

Examples

The following pages contain:

• A Simple Example
• The Basics
  1. Locating a data service
  2. Listing data resources and setting the resource ID
• Performing Queries
  1. Performing a basic SQL query
  2. Performing a sequence of queries
  3. Performing a parameterised SQL query repeatedly
  4. Performing an XPath Query on a XML database
• Processing Results
  1. Obtaining activity output from an SQL Query
  2. Obtaining activity output from an XPath Query
• Updates and Bulk Load
  1. Updating an XML Database
  2. Updating a Relational Database
  3. Bulk loading Data into a Table
• Control Flow
  1. Request Components
  2. Flow Control
  3. Sequence Control
• Obtaining Meta Data
  1. The Version of a Service
  2. Listing Data Resources
  3. Supported Activities and Activity Meta Data
  4. Product Information of a Data Resource
  5. Accessing Data Service and Resource Properties
• Transforming Data
  1. XSL Transformations
  2. ZIP and GZIP Compression
• Using Sessions
  1. Joining an implicit session
  2. Creating a new session
  3. Joining an existing session
  4. Terminating a session
• Asynchronous Requests
  1. Processing an asynchronous request
  2. Monitoring the request status
  3. Polling the request status
• Asynchronous Delivery
  1. Delivering data to and from a URL
  2. Delivering data to and from a File
  3. Delivering data to and from a GridFTP location
  4. Pulling data from a session stream to a client
  5. Pushing data from a client to a session stream
  6. Pulling data between data service resources
  7. Pushing data between data service resources
• Data Integration

See the full list of Client Toolkit Examples.

WSRF (GT4) Platform-Specific Examples

These are examples that are only applicable for the WSRF (GT4) version of OGSA-DAI.

• Secure Services: Using Message-Level and Transport-Level Security
  1. Securing messages with transport-level security
  2. Message-level security