OGSA-DAI WSRF Distribution

OGSA-DAI WSRF Distribution (DAI-WSRF-0.9.5)

Contents

Prerequisites

The deployment and use of the OGSA-DAI WSRF distribution will be easier if you are already familiar with:

Prerequisite Software

To use OGSA-DAI WSRF you will need the following software:

Prerequisite Jars

To use OGSA-DAI WSRF you will need the following Jars:

Data Resource Drivers

You will need to download database drivers for any data resources you wish to expose using the OGSA-DAI WSRF distribution. Data resources and drivers that have been tested against OGSA-DAI are:

  • MySQL
    • MySQL Connector J/2. Available from: http://www.mysql.com.
    • Required JAR: mysql-connector-java-XXX.jar where XXX is the version of the driver.
  • DB2
  • Oracle
    • Oracle JDBC Drivers for Java 1.2+. Available from http://www.oracle.com.
    • Required JAR:classes12.zip - rename as classes12.jar.
  • Xindice 1.0
  • Microsoft SQL Server
    • MS SQL Server JDBC driver. Available from http://www.microsoft.com.
    • Required JARs: mssqlserver.jar, msbase.jar, msutil.jar.
  • Postgres
    • Postgres JDBC driver. Available from http://www.postgresql.org.
    • Required JAR: pgXXXX.jar where XXXX is the version of the driver.

Overview

This OGSA-DAI distribution provides a WSRF based service interface, using the Globus Toolkit WSRF implementation. Features include:

  • Access to data is provided via an OGSA-DAI data service. For those already familiar with the OGSI version of OGSA-DAI this service amalgamates the capabilities of the GDSF and GDS services (the metadata and configuration roles of the GDSF and the metadata and perform document processing aspects of the GDS).
  • Allows multiple data resources to be accessed through a single service. Data resource identifiers, available from the data service's WS-Addressing endpoint reference, allows a client to target a specific data resource.
  • A listResources() operation is provided at a data service to list all the data resource identifiers available to that data service.
  • The data resource identifiers returned by a data service can subsequently be used by a client to obtain metadata, etc, about the data resources corresponding to that identifier.
  • Access to service metadata (such as database schemas, request status, etc) is provided by an implementation of the WS-ResourceProperties specification. In particular support for using the QueryResourceProperties, GetResourceProperties, and GetMultipleResourceProperties portTypes is provided.
  • Access to version information about the OGSA-DAI Data Service is available through the getVersion() operation.
  • A WSRF version of the OGSA-DAI GridDataTransport portType supports asynchronous data delivery between data services.

Caveats

  • Use of GT3.9.5 security has not been tested on the OGSA-DAI WSRF distribution.
  • A WS-RF version of the client toolkit is not provided with this release.
  • This documentation has been generated from the OGSI version of the OGSA-DAI documentation. There may still be some OGSI material lurking in here or mention features that are not yet supported by the WS-RF release. If you find any such discrepencies please do let us know.

We would welcome any feedback you might have about this release of the OGSA-DAI WSRF distribution. If you have any comments please send these to support@ogsadai.org.uk.

Installation and Deployment

This section describes how to set up an OGSA-DAI WSRF data service to expose a number of data resources and how to then deploy DAI WSRF onto Globus Toolkit.

Initial Installation

  • Download and compile Globus Toolkit.
  • Unzip ogsadai-wsrf.zip. You should now have the following directory structure: 
    • build.xml               - ANT build script.
build-tools-cli.xml     - ANT build script for installation tools.
client-config.wsdd      - Globus Toolkit client configuration file.
deploy-jndi-config.xml  - Resource configuration file.
deploy-server.wsdd      - Data resource deployment descriptor.
doc                     - Documentation.
etc                     - Location for configuration files.
lib                     - Directory for jar files and other libraries.
NStoPkg.properties      - Mappings from namespaces to Java packages.
schema                  - DAI XML Schema and WSDL.
skeletons               - Skeleton data resource and data service 
                          configuration files. 
src                     - Java source code.
  • Set a GLOBUS_LOCATION environment variable to point to the location of your Globus Toolkit distribution: 
    • $ export GLOBUS_LOCATION=path/to/Globus/directory
  • Place the prerequisite JAR files ( xindice.jar, xmldb.jar and junit.jar) into the lib directory.
  • Set a DAI_WSRF environment variable to point to the location of your OGSA-DAI WSRF distribution directory. For the bash or bourne shell use: 
    $ export DAI_WSRF=/path/to/DAI/WSRF/directory
    for cshell use: 
    % setenv DAI_WSRF /path/to/DAI/WSRF/directory
    and for a windows system: 
    $ set DAI_WSRF=C:\path\to\DAI\WSRF\directory
    From this point onwards only examples for the bash/bourne shell are shown. Be sure to use the correct alternative for your platform.

Create Service Deployment Descriptors

To prepare a new data service.

  • Enter the following command: 
    $ cd $DAI_WSRF
$ ant -buildfile build-tools-cli.xml createDataServiceDeployment
  • You will be prompted for a name for your service. This will determine the URL of your service. 
         [echo] Create a new Data Service deployment.
     [echo] Enter the relative service path e.g. sample/DataService:
    [input] (Press RETURN to select 'DataService')
    For example, entering my/DataService means that your service will have URL http://localhost:8080/wsrf/services/my/DataService.

    Accepting the default means your service will have a URL of http://localhost:8080/wsrf/services/DataService.

  • Two deployment descriptors will then be created for your service within deploy-server.wsdd and deploy-jndi-config.xml.

Add Data Resources

You can now configure the service deployment descriptors so that your service exposes data resources. For each data resource you want your service to expose, do the following:

  • Enter the following command: 
    $ cd $DAI_WSRF
$ ant -buildfile build-tools-cli.xml addDataResource
  • You will now be asked to select the type of data resource you want to expose. In the following example the user selects a MySQL data resource: 
         [echo] Add a data resource to the current Data Service.
    [input] Enter data resource name (this will determine the names of the data resource configuration files also):
DataResourceSQL

     [echo] The following types of data resource are compatible with OGSA-DAI. Select the one you wish to deploy.
     [echo] 1-Relational - MySQL
     [echo] 2-Relational - IBM DB2
     [echo] 3-Relational - Microsoft SQL Server
     [echo] 4-Relational - PostgreSQL
     [echo] 5-XML        - Apache Xindice
     [echo] 6-Files      - Files and directories
    [input] Enter data resource type (1,2,3,4,5,6)
1
  • You will then be asked to enter information about the data resource. You can press RETURN if you are happy with any default selections that are offered. 
         [echo] Enter data resource product vendor:
    [input] (Press RETURN to select 'MySQL')

     [echo] Enter data resource product version:
    [input] (Press RETURN to select '1.0')

    [input] Enter data resource URL:
jdbc:mysql://host.epcc.ed.ac.uk:3306/ogsadai

     [echo] Enter data resource driver class name:
    [input] (Press RETURN to select 'org.gjt.mm.mysql.Driver')

    [input] Enter database user ID:
ogsadai

    [input] Enter database password:
ogsadai
  • Data resource configuration files will then be created within the etc directory, using a directory named after the name you used for your data resource, for example DataResourceSQL.
  • The service deployment descriptor you created will be updated to point to these configuration files.
  • You should now copy any JAR files containing your data resource drivers to the lib directory.

As another example, here the user selects a Xindice data resource: 

$ cd $DAI_WSRF
$ ant -buildfile build-tools-cli.xml addDataResource

. . .

     [echo] Add a data resource to the current Data Service.
    [input] Enter data resource name (this will determine the names of the data resource configuration files also):
DataResourceXML

     [echo] The following types of data resource are compatible with OGSA-DAI. Select the one you wish to deploy.
     [echo] 1-Relational - MySQL
     [echo] 2-Relational - IBM DB2
     [echo] 3-Relational - Microsoft SQL Server
     [echo] 4-Relational - PostgreSQL
     [echo] 5-XML        - Apache Xindice
     [echo] 6-Files      - Files and directories
    [input] Enter data resource type (1,2,3,4,5,6)
5

     [echo] Enter data resource product vendor:
    [input] (Press RETURN to select '1.0')

     [echo] Enter data resource product version:
    [input] (Press RETURN to select '1.0')

    [input] Enter data resource URL:
xmldb:xindice://host.epcc.ed.ac.uk:4080/db/littleblackbook

     [echo] Enter data resource driver class name:
    [input] (Press RETURN to select 'org.apache.xindice.client.xmldb.DatabaseImpl')

    [input] Enter database user ID:
       
    [input] Enter database password:

...

Deploy Data Service Under Globus Toolkit

To compile and deploy OGSA-DAI WSRF distribution and your data service under Globus Toolkit enter: 

$ cd $DAI_WSRF
$ ant deploy

The data resource configuration files created for each of the data resources exposed by your service and the service deployment descriptor you created will be copied into the Globus Toolkit directory structure and all pathnames rewritten appropriately.

Deploy Data Service Under Tomcat

To deploy the Globus Toolkit WS core and OGSA-DAI services under Tomcat enter: 

$ cd $GLOBUS_LOCATION
$ ant -f share/globus_wsrf_common/tomcat/tomcat.xml deployTomcat -Dtomcat.dir=$CATALINA_HOME

Usage - Querying Meta Data

To query a data service:

  • Create a new console window and start your WSRF service container (Globus toolkit container or Tomcat).
  • Now, in another window, invoke the Globus GetProperty Client: 
    $ cd $GLOBUS_LOCATION
$ ./bin/wsrf-get-property -s DATA-SERVICE-URI 
    -k {http://ogsadai.org.uk}DataResourceKey DATA-RESOURCE-NAME 
    PROPERTY-NAME
    For example: 
    $ cd $GLOBUS_LOCATION
$ ./bin/wsrf-get-property -s http://localhost:8080/wsrf/services/DataService 
    -k {http://ogsadai.org.uk}DataResourceKey DataResourceSQL 
    {http://ogsadai.org.uk/namespaces/2004/06}databaseSchema
  • The value of the property will then be displayed.
  • Properties can include:
    • {http://ogsadai.org.uk/namespaces/2004/06}productInformation
    • {http://ogsadai.org.uk/namespaces/2004/06}requestStatus
    • For relational data resources: {http://ogsadai.org.uk/namespaces/2004/06}databaseSchema.
    • For XML data resources: {http://ogsadai.org.uk/namespaces/2004/06}collectionSchema.

Usage - Submitting Perform Documents

To use OGSA-DAI WSRF to run Perform documents on a data resource:

  • Create a new console window and start your WSRF service container (Globus toolkit container or Tomcat).
  • Now, in another window, invoke the DAI WSRF Client: 
    $ cd $GLOBUS_LOCATION
$ ./bin/dai-wsrf-client [-u DATA-SERVICE-URI] [-k DATA-RESOURCE-NAME] 
                        PERFORM-DOCUMENT-FILE
    For example: 
    $ cd $GLOBUS_LOCATION
$ ./bin/dai-wsrf-client -u
  http://localhost:8080/wsrf/services/DataService 
  -k DataResourceSQL etc/globus_wsrf_ogsadai/select1Row.xml
  • If you omit a data resource name then a list of those will be shown and you will be asked to select one. For example 
    Contacting ... http://localhost:8080/wsrf/services/DataService
Data service version: WSRF 4.0
Number of resources: 2
Resource: DataResourceSQL
Resource: DataResourceXML
Enter a data resource name:
DataResourceSQL
Data Resource: DataResourceSQL
  • If you omit a service URL then a default of http://localhost:8080/wsrf/services/DataService will be used.

We provide example perform documents for a relational and XML data resource in the etc directory.

If you have a full OGSA-DAI release version 4.0 or higher then the OGSA-DAI test database tables are suitable for use with these example perform documents.

If you do not have OGSA-DAI 4.0 or 5.0 then you can edit the perform documents in the etc directory:

  • If your service exposes a relational data resource then:
    • Edit the etc/select1Row.xml file.
    • Replace the SQL query within the expression element: 
      <expression>select * from littleblackbook where id=10</expression>
      with an SQL expression compatible with your relational database.
  • If your service exposes an XML data resource then:
    • Edit the etc/queryCollection1.xml file.
    • Replace the XPath query within the expression element: 
      <expression>/entry[@id<100]</expression>
      with an XPath expression compatible with your XML database.

To convert existing OGSA-DAI Perform documents to be compatible with OGSA-DAI WSRF see the next section.

Usage - Converting OGSA-DAI Perform Documents

In OGSA-DAI, Perform documents are specified in a gds related namespace. In OGSA-DAI WSRF we have removed from Perform document namespaces information related to the specification (OGSI, WSI, WSRF) implemented at the service level.

To convert Perform documents provided in the main OGSA-DAI distribution (within examples), or your own existing Perform documents, into this generic format:

  • Execute the ConvertPerform target within the OGSA-DAI WSRF ANT script: 
    $ cd $DAI_WSRF
$ ant ConvertPerform -Dperform.dir=PATH-TO-PERFORM-DIRECTORY
    where PATH-TO-PERFORM-DIRECTORY contains files, all of which are assumed to be XML Perform documents. For example: 
    $ cd $DAI_WSRF
$ ant ConvertPerform -Dperform.dir=examples/GDSPerform/JDBC/query
  • Do not worry if you make a mistake, the ANT target will make backups (with extension .bak) prior to converting the documents.
Up: OGSA-DAI User Guide
© International Business Machines Corporation, 2005. © The University of Edinburgh, 2005.