GT 4.0 OGSA-DAI (Tech Preview): System Administrator's Guide

Home -> Toolkit -> Docs -> 4.0 -> Techpreview -> Ogsadai	Website Email Lists Search:

Table of Contents

1. Introduction

2. Building and installing

2.1. Prerequisites

3. Building OGSA-DAI WSRF

3.1. Insert the Prerequisite JAR Files
3.2. Compile GT4 core
3.3. Build OGSA-DAI WSRF

4. Configuring

5. Deploying

5.1. Deploying OGSA-DAI WSRF via the Command-line
5.2. Deploying OGSA-DAI WSRF using a GUI
5.3. Exposing Data Resources using OGSA-DAI WSRF
5.4. Deploying Data Services
5.5. Checking the OGSA-DAI Data Service Deployment
5.6. ListResources Client
5.7. Deploying Data Service Resources
5.8. Adding Data Service Resources to Data Services
5.9. Dynamically Add a Data Service Resource using the Command-line
5.10. Removing Data Service Resources from Data Services
5.11. Updating Data Service Resource Role Maps
5.12. End-to-end Client
5.13. Configurable Data Services
5.14. Undeploying OGSA-DAI WSRF
5.15. Where Does Stuff Go?

6. Testing

7. Security considerations

8. Troubleshooting

8.1. I am using MySQL and keep on getting a java.sql.SQLException: Cannot connect to MySQL server on localhost:3306 exception - what is the problem?
8.2. Is there a MySQL server running on the machine/port you are trying to connect to? (java.lang.NumberFormatException)
8.3. Why do I get Exception in thread "main" java.lang.IllegalAccessError: tried to access field...?

1. Introduction

This guide contains advanced configuration information for system administrators working with OGSA-DAI. It provides references to information on procedures typically performed by system administrators, including installing, configuring, deploying, and testing the installation.

	Important
	This information is in addition to the basic Globus Toolkit prerequisite, overview, installation, security configuration instructions in the GT 4.0 System Administrator's Guide. Read through this guide before continuing!

2. Building and installing

OGSA-DAI is not built and installed as part of the standard Globus Toolkit installation. You will find the installation bundle in the contributions directory. You may find a binary and/or a source distribution of the OGSA-DAI software. This documentation will outline how to build a binary distribution from the source. You will need to install the Java WS-Core from the Globus distribution.

2.1. Prerequisites

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

OGSA-DAI concepts and terms. Reading the user's guide included in the OGSA-DAI distribution should provide you with this information.
WS-Addressing concepts and terms. An introduction to WS-Addressing is available at http://www-106.ibm.com/developerworks/library/specification/ws-add.
Web Services Resource Framework (WSRF) concepts and terms. The WSRF specifications can be found at http://www.globus.org/wsrf.

2.1.1. Prerequisite Software

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

Java 1.4.0: OGSA-DAI WSRF has been tested on this version of Java though may work with other Java 1.4.x flavours.
Jakarta ANT 1.5: See http://ant.apache.org.
Globus Toolkit Java WS Core
- This provides a Java-based implementation of WSRF and is available at: http://www.globus.org/toolkit/downloads/4.0/.
- Information on Globus Toolkit 4.0 can also be found at: http://www.globus.org/toolkit/docs/4.0/GT4Facts.

3. Building OGSA-DAI WSRF

This section describes how to build OGSA-DAI WSRF. If you are using the binary distribution then you can move to the deploying OGSA-DAI WSRF section.

3.1. Insert the Prerequisite JAR Files

First, download the prerequisite JAR files (listed above):

jakarta-oro-2.0.7.jar
lucene-1.4-final.jar
xmldb.jar

and put these into the OGSA-DAI distribution's lib directory.

3.2. Compile GT4 core

Now, you need to compile Globus Toolkit 4 Web Services Core. The GT4 instructions tell you how to do this.

3.3. Build OGSA-DAI WSRF

To build OGSA-DAI WSRF:

Set a GLOBUS_LOCATION environment variable to point to the location of your GT4 distribution. For example, under UNIX, enter:
```
 $ export GLOBUS_LOCATION=/path/to/Globus/directory
```
Run the following from within the OGSA-DAI distribution directory:
```
  $ ant createBinaryDistribution
```
Progress messages will appear and if there are any problems - for example missing JARs - then you will be notified.
When complete, you will have a ZIPped, TARred binary distribution within your OGSA-DAI source distribution directory. You will also have a binary directory containing the binary release.

OGSA-DAI WSRF will then be built. You should now change into the binary directory. Note that before you can use OGSA-DAI you must configure it. This is covered in the deployment section.

4. Configuring

This information is in addition to the basic configuration instructions in the GT4.0 System Administrator's Guide.

Please consult the Section 5, “Deploying” section in the Admin Guide for information on configuring OGSA-DAI services.

5. Deploying

This section describes how to install OGSA-DAI WSRF onto the GT4 container or Apache Tomcat.

This section assumes that you have built the WSRF version of OGSA-DAI from source or are using a binary distribution. Distributions of OGSA-DAI are bundled with the Globus Toolkit or are available from the project website www.ogsadai.org.uk. Please consult the bundled documentation in any of these distributions for more details about OGSA-DAI.

The OGSA-DAI WSRF binary distribution can be deployed onto the GT4 container or Apache Tomcat:

Either via the Command-line
Or using a GUI

5.1. Deploying OGSA-DAI WSRF via the Command-line

5.1.1. Insert the Prerequisite JAR Files

First, download the prerequisite JAR files (listed in the building section):

jakarta-oro-2.0.7.jar
lucene-1.4-final.jar
xmldb.jar

and put these into the OGSA-DAI binary distribution lib directory. (IF you build your binary from a source distribution you will already have these JARs and they will have been inserted into the binary lib directory as part of the build).

5.1.2. Deploying OGSA-DAI WSRF onto GT4

If you wish to deploy OGSA-DAI WSRF onto the GT4 Web services container then keep reading. If however you want to deploy OGSA-DAI WSRF onto Apache Tomcat then skip to the next section.

To deploy OGSA-DAI WSRF onto GT4:

Set a GLOBUS_LOCATION environment variable to point to the location of your GT4 distribution. For example, under UNIX, enter:
```
 $ export GLOBUS_LOCATION=/path/to/Globus/directory
```
Run the following from within the OGSA-DAI binary distribution directory:
```
 $ ant deployGT4
```

OGSA-DAI WSRF will then be deployed.

5.1.3. Deploying OGSA-DAI WSRF onto Tomcat

Before you can deploy OGSA-DAI WSRF onto Tomcat you will need to deploy GT4 onto Tomcat. You can do this as follows, if you have not already done so:

Set a GLOBUS_LOCATION environment variable to point to the location of your GT4 distribution. For example, under UNIX, enter:
```
 $ export GLOBUS_LOCATION=/path/to/Globus/directory
```
Set a CATALINA_HOME environment variable to point to the location of Tomcat. For example, under UNIX, enter:
```
$ export CATALINA_HOME=/path/to/Tomcat/directory
```

Run the following commands:

 $ cd path/to/Globus/directory
 $ ant -f share/globus_wsrf_common/tomcat/tomcat.xml deployTomcat 
 -Dtomcat.dir=/path/to/Tomcat
 $ cd path/to/OGSA-DAI/binary/directory

For more information see the GT4 installation instructions.

Now, to deploy OGSA-DAI WSRF onto Tomcat, run the following from within the OGSA-DAI binary distribution directory:

$ ant deployTomcat

OGSA-DAI WSRF will then be deployed to Tomcat.

Note

As an alternative to setting CATALINA_HOME you can specify the Tomcat location at the command-line as follows:

 $ ant deployTomcat -Dtomcat.dir=/path/to/Tomcat/directory

5.2. Deploying OGSA-DAI WSRF using a GUI

5.2.1. Deploying OGSA-DAI WSRF onto GT4

If you wish to deploy OGSA-DAI WSRF onto the GT4 Web services container then keep reading. If however you want to deploy OGSA-DAI WSRF onto Apache Tomcat then skip to the next section.

To deploy OGSA-DAI WSRF onto GT4:

Run the following from within the OGSA-DAI binary distribution directory:
```
  $ ant guiDeployGT4
```
A GUI will appear and you can select your GT4 distribution by pressing the Select... button. If GLOBUS_LOCATION is set then this will be offered as the default selection.
When you are happy with the Path, press Next.
You now have to select the prerequisite JAR files (listed in the building section):
- jakarta-oro-2.0.7.jar
- lucene-1.4-final.jar
- xmldb.jar
Using the file browser on the left select a JAR file. Press Add to add it to the list of current JARs on the right.
If you make a mistake then select the JAR on the right and press Remove to remove it from the list.
When you are happy with your selections, press Next.
You will now be requested to press Next so that the tool can deploy OGSA-DAI WSRF. If any problems occur then the tool will notify you of these.
When the deployment has completed a completion window will be displayed. Press Finish to exit the tool.

5.2.2. Deploying OGSA-DAI WSRF onto Tomcat

Before you can deploy OGSA-DAI WSRF onto Tomcat you will need to deploy GT4 onto Tomcat. You can do this as follows, if you have not already done so:

Set a GLOBUS_LOCATION environment variable to point to the location of your GT4 distribution. For example, under UNIX, enter:
```
  $ export GLOBUS_LOCATION=/path/to/Globus/directory
```
Set a CATALINA_HOME environment variable to point to the location of Tomcat. For example, under UNIX, enter:
```
 $ export CATALINA_HOME=/path/to/Tomcat/directory
```

Run the following commands:

  $ cd path/to/Globus/directory
  $ ant -f share/globus_wsrf_common/tomcat/tomcat.xml deployTomcat 
  -Dtomcat.dir=$CATALINA_HOME
  $ cd path/to/OGSA-DAI/binary/directory

For more information see the GT4 installation instructions.

Now, to deploy OGSA-DAI WSRF onto Tomcat:

Run the following from within the OGSA-DAI binary distribution directory:
```
  $ ant guiDeployTomcat
```
A GUI will appear and you can select your Tomcat distribution by pressing the Select... button. If CATALINA_HOME is set then this will be offered as the default selection.
When you are happy with the Path press Next.
You now have to select the prerequisite JAR files (listed in admin building section):
- jakarta-oro-2.0.7.jar
- lucene-1.4-final.jar
- xmldb.jar
Using the file browser on the left select a JAR file. Press Add to add it to the list of current JARs on the right.
If you make a mistake then select the JAR on the right and press Remove to remove it from the list.
When you are happy with your selections, press Next.
You will now be requested to press Next so that the tool can deploy OGSA-DAI WSRF. If any problems occur then the tool will notify you of these.
When the deployment has completed a completion window will be displayed. Press Finish to exit the tool.

5.3. Exposing Data Resources using OGSA-DAI WSRF

To expose a data resource via an OGSA-DAI WSRF data service is a three-step process:

Deploy an OGSA-DAI data service. This data service initially exposes 0 data service resources.
Deploy a data service resource. The data service resource contains information about a data resource and the activities clients can perform on that data resource via a data service.
Add the data service resource to a data service. This instructs the data service to expose the data service resource and so allows clients to interact with the data service resource - thereby interacting with a data resource.

For those who want a quick introduction to OGSA-DAI WSRF we recommend:

Deploy a new data service as described here.
Startup your Web services container.
Test the data service resource using the ListResources client and ensuring that the service is available and exposes 0 data service resources. The ListResources client is described here.
Shutdown your Web services container.
Deploy a new data data service resource as described here.
Add the data service resource to the data service as described here.
Startup your Web services container.
Submit a perform document to the data service resource exposed by your data service using the End-to-end client. The End-to-end client is described here.

5.4. Deploying Data Services

This section describes how to deploy an OGSA-DAI data service which initially will expose 0 data service resources.

You can:

Deploy data services using the command-line.
Deploy data services using a GUI.
Check that a data service deployed correctly.

If you have already deployed some data service resources (as described in the next section) you can add these to the data service as described on a following section.

5.4.1. Deploying Data Services Using the Command-line

To deploy a data service under Tomcat:

Run the following command from within the OGSA-DAI WSRF binary distribution directory:
```
 $ ant deployDataServiceTomcat -Dtomcat.dir=/path/to/Tomcat/directory
 -Ddai.service.path=service/path
```
- dai.service.path specifies the local URL of the service. For example -Ddai.service.path=ogsadai/DataService specifies a data service whose URL will be http://HOST:PORT/wsrf/services/ogsadai/DataService.
- tomcat.dir specifies the location of Tomcat. If this argument is omitted then the Tomcat location specified within CATALINA_HOME is used.
- Providing the flag -Ddai.service.config=y requests that the data service support dynamic service configuration. See the sections on configurable data services, adding data service resources to data services and updating role maps for more information.
The data service will be deployed onto Tomcat. You will need to shutdown and restart Tomcat before clients are able to access the new data service.

To deploy a data service under GT4 requires execution of the deployDataServiceGT4 target. This takes the same arguments as deployDataServiceTomcat. The exception is the tomcat.dir argument - this target instead accepts gt.dir which specifies the location of GT4. If this argument is omitted then the GT4 location specified within GLOBUS_LOCATION is used.

5.4.2. Deploying Data Services Using a GUI

To deploy a data service under Tomcat:

Run the following command from within the OGSA-DAI WSRF binary distribution directory:
```
 $ ant guiDeployDataServiceTomcat
```
A GUI will appear and you can select your Tomcat distribution by pressing the Select... button. If CATALINA_HOME is set then this will be offered as the default selection.
When you are happy with the Path press Next.
Now you will be asked to enter:
- The local URL of the data service, for example ogsadai/DataService, in the Service Path field. For example ogsadai/DataService specifies a data service whose URL will be http://HOST:PORT/wsrf/services/ogsadai/DataService.
- Clicking on the Dynamically configurable? box requests that the data service support dynamic service configuration. See the sections on configurable data services, adding data service resources to data services and updating role maps for more information.
Press Next when you have entered this information.
You will now be requested to press Next so that the tool can deploy the data service. If any problems occur then the tool will notify you of these.
When the deployment has completed a completion window will be displayed. Press Finish to exit the tool.
You will need to shutdown and restart Tomcat before clients are able to access the new data service.

To deploy data services under GT4 requires execution of the guiDeployDataServiceGT4 target.

5.5. Checking the OGSA-DAI Data Service Deployment

To check that a service has deployed under Tomcat:

Restart Tomcat.

Using a Web browser, visit the following URL:

 http://TOMCAT.HOST:TOMCAT.PORT/wsrf/services

Eventually a list of service URLs will be displayed. You should see one corresponding to your service. For example:
```
 ogsadai/DataService (wsdl)
```

Click on the (wsdl) link and the WSDL describing the service should appear. For example:

 <?xml version="1.0" encoding="UTF-8" ?> 
 <wsdl:definitions name="DataService" 
 ...

To check that a service has deployed under GT4:

Start the GT4 container:

  $ cd $GLOBUS_LOCATION
  $ ./bin/globus-start-container -nosec

Eventually a list of service URLs will be displayed. You should see one corresponding to your service. For example:
```
  [22]: http://129.215.56.6:8080/wsrf/services/ogsadai/DataService
```

An alternative is to test the service using the OGSA-DAI WSRF listResourcesClient client. We describe how to use this client in the next section.

5.6. ListResources Client

OGSA-DAI comes with a client that allows you to list the data service resources exposed by an OGSA-DAI WSRF data service.

To list the data service resources exposed by a data service:

Ensure that your Web services container is running.
Ensure that the GLOBUS_LOCATION environment variable is set.
Run the following command from within the OGSA-DAI WSRF binary distribution directory:
```
 $ ant listResourcesClient -Ddai.url=SERVICE-URL
```
where -Ddai.url= specifies the URL of the data service. If omitted then a default URL of http://localhost:8080/wsrf/services/ogsadai/DataService is used.
For example:
```
$ ant listResourcesClient 
 -Ddai.url=http://localhost:8080/wsrf/services/ogsadai/MyDataService
```

The data service resources exposed by your service will be displayed. For example:

 [java] Contacting ... http://localhost:8080/wsrf/services/ogsadai/DataService
 [java] Service version: OGSA-DAI WSRF 1.0
 [java] This service exposes no resources!

For example:

 [java] Contacting ... http://localhost:8080/wsrf/services/ogsadai/DataService
 [java] Service version: OGSA-DAI WSRF 1.0
 [java] Number of resources: 2
 [java] Resource: MySQLResource
 [java] Resource: AnotherResource

	Note
	As an alternative to setting CATALINA_HOME or GLOBUS_LOCATION you can specify the Tomcat or GT4 locations using the -Dtomcat.dir=/path/to/Tomcat/directory or -Dgt.dir=/path/to/Globus/directory flags respectively.

5.7. Deploying Data Service Resources

This section describes how to deploy a data service resource. Once deployed the data service resource can then be added to the set of those exposed by a data service as described in the next section.

The characteristics of a data service resources are specified in a data services resource file. We describe these below.

There are a number of ways to create a data service resource file and deploy a data service resource. You can:

Write or edit a data service resource file using an editor then deploy the data service resource using the command-line.
Create new data service resource files and (optionally) deploy the data service resources using a GUI
Load and edit existing data service resource files and (optionally) deploy the data service resources using a GUI

5.7.1. Data Service Resource Files

A data service resource file is used specify the properties of your data service resource. This is a simple properties file consisting of argument=value values. You can reuse the same file to deploy the same data service resource under different names or to customise a specific configuration in small or major ways. Alternatively you can just write a new file each time.

Within the OGSA-DAI WSRF distribution directory we provide an example - data.service.resource.properties. The file is fully commented.

The properties are as follows:

dai.resource.id= - name for the data service resource.
dai.data.resource.type=[Relational | XML | Files] - the type of data resource to which the data service resource provides access.
dai.product.name= - data resource product name (optional).
dai.product.vendor= - data resource product vendor (optional).
dai.product.version= - data resource product version (optional).
dai.data.resource.uri= - data resource URI. This must be compatible with the driver class specified next.
dai.driver.class= - data resource driver class name. This is optional only if dai.data.resource.type=Files.
dai.credential= - Grid certificate credentials of a user permitted to access the data resource. If omitted then any user will be allowed access.
dai.user.name= - data resource user name. Optional only if there is no user name required for a database.
dai.password= - corresponding data resource password. Optional if there is no user name required, or if the password is null.

5.7.2. Deploying Data Service Resources Using the Command-line

To deploy a data service resource under Tomcat:

Take a copy of data.service.resource.properties within the OGSA-DAI WSRF distribution directory.
Load the file into an editor and provide values specifying your data service resource - the comments in the file should help you.
When done, save the file.
Put all the JARs implementing the data resource driver within the drivers directory within the OGSA-DAI WSRF binary distribution directory.
Run the following command from within the OGSA-DAI WSRF binary distribution directory:
```
 $ ant deployResourceTomcat -Dtomcat.dir=/path/to/Tomcat/directory
 -Ddai.service.resource.file=DAI-SERVICE-RESOURCE-FILE
```
- tomcat.dir specifies the location of Tomcat. If this argument is omitted then the Tomcat location specified within CATALINA_HOME is used.
- dai.service.resource.file specifies the location of a data service resource properties file. If no argument is given then a default location of data.service.resource.properties (within the OGSA-DAI WSRF distribution directory) is assumed.

The data service resource will be deployed. For example:

 $ ant deployResourceTomcat -Ddai.service.resource.file=my.config
 ...
 [echo] Reading properties file my.config
 [echo] Data service resource ID: MySQLResource
 [echo] Data resource type: Relational
 [echo] Data resource product: MySQL
 [echo] Data resource vendor: MySQL
 [echo] Data resource version: 1.0
 [echo] Data resource URI: jdbc:mysql://myhost.example.com:3306/ogsadai/DATABASE
 [echo] Data resource credential: 
 [echo] Data resource user name: ogsadai
 [echo] Data resource password: ogsadai
 [echo] Data driver class: org.gjt.mm.mysql.Driver
 [echo] Deploying data service resource MySQLResource...
 ...
 [echo] Data service resource deployed!

Values in the same data service resource file can be overridden at the command line via the use of -Dproperty=value flags.
- For example to deploy another data service resource with the same configuration as held within my.config you can execute:
```
 $ ant deployResourceTomcat -Ddai.service.resource.file=my.config
 -Ddata.resource.id=AnotherResource
```
- As another example, consider deploying a data service resource with the same configuration but with a different location:
```
 $ ant deployResourceTomcat -Ddai.service.resource.file=my.config
 -Ddata.resource.id=YetAnotherResource
 -Ddai.data.resource.uri=jdbc:mysql://myhost:8080/some/other/DB
```
- Alternatively, you can just edit your data service resource file.

To deploy data service resources under GT4 requires execution of the deployResourceGT4 target. This takes the same arguments as deployResourceTomcat. The exception is the tomcat.dir argument - this target instead accepts gt.dir which specifies the location of GT4. If this argument is omitted then the GT4 location specified within GLOBUS_LOCATION is used.

5.7.3. Creating new Data Service Resource Files and Deployment

To create a new data service resource file and (optionally) deploy the data service resource under Tomcat:

Run the following command from within the OGSA-DAI WSRF binary distribution directory:
```
 $ ant guiCreateResourceTomcat
```

A GUI will appear and you can select your database product from those offered.

When you are happy with your selection, press Next.

You will now have to enter information about the data service resource and your database product. This information includes:
- Data Resource URI - data resource URI(required). This must be compatible with the driver class specified next.
- Data Resource Driver Class - data resource driver class name. This is optional only if you selected a Files and directories product on the previous window.
- Vendor - data resource product vendor (optional).
- Version - data resource product version (optional).
- Database access credential - Grid certificate credentials of a user permitted to access the data resource. If omitted then any user will be allowed access.
- Database user ID - data resource user name. Optional only if there is no user name required for a database.
- Database password - corresponding data resource password. Optional if there is no user name required, or if the password is null.
- Data Service Resource ID - name for the data service resource (required).
When you are happy with your values, press Next.
You now have to select the JARs that implement your database driver if these have not already been installed on the server.
- Using the file browser on the left select a JAR file. Press Add to add it to the list of current driver JARs on the right.
- If you make a mistake then select the JAR on the right and press Remove to remove it from the list.
When you are happy with your selections, press Next.
You should now enter a file name in which to save your values. These will be saved in a new data service resource file. Press the Select... button, enter a new file name in the File name field then press Select
When you are happy with the Path press Next.
You will now be given the choice of pressing Cancel to exit, or Next to proceed to deploy your data service resource.
- If you press Cancel you can always deploy your resource later using via the command-line as described above or a GUI as described below.
You can select your Tomcat distribution by pressing the Select... button. If CATALINA_HOME is set then this will be offered as the default selection.
When you are happy with the Path press Next.
You will now be requested to press Next so that the tool can deploy the data service resource. If any problems occur then the tool will notify you of these.
When the deployment has completed a completion window will be displayed. Press Finish to exit the tool.

To create and deploy data service resources under GT4 requires execution of the guiCreateResourceGT4 target.

5.7.4. Editing Existing Data Service Resource Files and Deployment

To edit an existing data service resource file and (optionally) deploy the data service resource under Tomcat:

Run the following command from within the OGSA-DAI WSRF binary distribution directory:
```
$ ant guiDeployResourceTomcat
```
A GUI will appear and you can select your data service resource file by pressing the Select... button.
When you are happy with the Path press Next.
You can now edit the information about the data service resource and your database product.
When you are happy with your values, press Next.
You can now change the current selection of the JARs that implement your database driver.
- Using the file browser on the left select a JAR file. Press Add to add it to the list of current driver JARs on the right.
- If you make a mistake or if some of the JARs are no longer valid or required then select the JAR on the right and press Remove to remove it from the list.
When you are happy with your selections, press Next.
You should now enter a file name in which to save your values. These will be saved in a new data service resource file. Press the Select... button, enter a new file name in the File name field then press Select
When you are happy with the Path press Next.
You can now select your Tomcat distribution by pressing the Select... button. If CATALINA_HOME is set then this will be offered as the default selection.
When you are happy with the Path press Next.
You will now be requested to press Next so that the tool can deploy the data service resource. If any problems occur then the tool will notify you of these.
When the deployment has completed a completion window will be displayed. Press Finish to exit the tool.

To edit existing data service resource files and deploy data service resources under GT4 requires execution of the guiDeployResourceGT4 target.

5.8. Adding Data Service Resources to Data Services

This section describes how to add a data service resource to a data service, thereby allowing clients to access and interact with the data service resource. It assumes that both the data service and data service resource have been deployed.

You can:

Add data service resources using the command-line.
Add data service resources using a GUI.
Dynamically add a data service resource using the command-line.

5.8.1. Adding Data Service Resources Using the Command-line

To add data service resources to data services under Tomcat:

Run the following command from within the OGSA-DAI WSRF binary distribution directory:
```
 $ ant addResourceTomcat -Ddai.service.path=service/path 
 -Ddai.resource.id=ResourceID -Dtomcat.dir=/path/to/Tomcat/directory
```
- dai.service.path specifies the local URL of the service. For example -Ddai.service.path=ogsadai/DataService specifies a data service whose URL will be http://HOST:PORT/wsrf/services/ogsadai/DataService.
- -Ddai.resource.id= is the ID of the data service resource that the data service is to expose. This must be the name of a data service resource which you have already deployed as described in the previous section. For example -Ddai.service.resource=MySQLResource.
- tomcat.dir specifies the location of Tomcat. If this argument is omitted then the Tomcat location specified within CATALINA_HOME is used.
You will need to shutdown and restart Tomcat before clients are able to access the new data service resource via the data service.

To add data service resources under GT4 requires execution of the addResourceGT4 target. This takes the same arguments as addResourceTomcat. The exception is the tomcat.dir argument - this target instead accepts gt.dir which specifies the location of GT4. If this argument is omitted then the GT4 location specified within GLOBUS_LOCATION is used.

After restarting your container, you can test whether the new data service resource was successfully added using the OGSA-DAI WSRF listResourcesClient client. We describe how to use this client in this section.

5.8.2. Adding Data Service Resources Using a GUI

To add data service resources to data services under Tomcat:

Run the following command from within the OGSA-DAI WSRF binary distribution directory:
```
 $ ant guiAddResourceTomcat
```
A GUI will appear and you can select your Tomcat distribution by pressing the Select... button. If CATALINA_HOME is set then this will be offered as the default selection.
When you are happy with the Path press Next.
Now you will be asked to enter:
- The local URL of the data service, for example ogsadai/DataService, in the Service Path field.
- The ID of the data service resource, for example MyRelationalResource in the Data Service Resource ID field.
Press Next when you have entered this information.
You will now be requested to press Next so that the tool can add the data service resource to the data service. If any problems occur then the tool will notify you of these.
When the addition has completed a completion window will be displayed. Press Finish to exit the tool.
You will need to shutdown and restart Tomcat before clients are able to access the new data service resource via the data service.

To add data service resources from data services under GT4 requires execution of the guiAddResourceGT4 target.

5.9. Dynamically Add a Data Service Resource using the Command-line

If your data service is configurable then you can request that the data service immediately expose the data service resource, without having to restart your Web services container. This is done as follows:

Ensure that the GLOBUS_LOCATION environment variable is set.
Run the following command from within the OGSA-DAI WSRF binary distribution directory:
```
  $ ant dataServiceClient -Ddai.url=SERVICE-URL
  -Ddai.resource.id=RESOURCE-ID -Ddai.action=deploy
```
where
- dai.url specifies the URL of the data service. If omitted then a default URL of http://localhost:8080/wsrf/services/ogsadai/DataService is used.
- dai.resource.id specifies the name of the data service resource.
For example:
```
   $ ant dataServiceClient 
   -Ddai.url=http://localhost:8080/wsrf/services/ogsadai/MyDataService
   -Ddai.resource.id=MyNewResource -Ddai.action=deploy
```

The request will be forwarded to the data service. For example:

  [echo] Deploying resource  MyNewResource...
  [java] Contacting ... http://localhost:8080/wsrf/services/ogsadai/DataService
  [java] Service version: OGSA-DAI WSRF 1.0
  [java] Number of resources: 1
  [java] Resource: MySQLResource
  [java] Data Service Resource: MyNewResource
  [java] About to invoke Deploy...
  [java] Deploy completed!

You can now use the listResourcesClient client (described in this section) to check if the deployment was successful.

During a deployment the service will attempt to update a data service resources file on the server. If this fails then a ConfigurationFaultType will occur with a corresponding message. The new data service resource will still be available via the data service but not if the container is shutdown and restarted. If such a failure occurs you can always add the data service resource to the data service using the first two approaches above.

5.10. Removing Data Service Resources from Data Services

This section describes how to remove a data service resource from a data service - the data service will no longer expose the data service resource. It assumes that both the data service and data service resource have been deployed and that the data service resource has been added to the data service (as described on the previously.

You can:

Remove data service resources using the command-line
Remove data service resources using a GUI

5.10.1. Removing Data Service Resources Using the Command-line

To remove data service resources from data services under Tomcat:

Run the following command from within the OGSA-DAI WSRF binary distribution directory:
```
  $ ant removeResourceTomcat -Dtomcat.dir=/path/to/Tomcat/directory
  -Ddai.service.path=service/path -Ddai.resource.id=ResourceID
```
- tomcat.dir specifies the location of Tomcat. If this argument is omitted then the Tomcat location specified within CATALINA_HOME is used.
- dai.service.path specifies the local URL of the service. For example -Ddai.service.path=ogsadai/DataService specifies a data service whose URL will be http://HOST:PORT/wsrf/services/ogsadai/DataService.
- dai.resource.id is the ID of the data service resource that the data service is no longer to expose. For example -Ddai.service.resource=MyRelationalResource
You will need to shutdown and restart Tomcat before the changes take effect.

To remove data service resources from data services under GT4 requires execution of the removeResourceGT4 target. This takes the same arguments as removeResourceTomcat. The exception is the tomcat.dir argument - this target instead accepts gt.dir which specifies the location of GT4. If this argument is omitted then the GT4 location specified within GLOBUS_LOCATION is used.

5.10.2. Removing Data Service Resources Using a GUI

To remove data service resources from data services under Tomcat:

Run the following command from within the OGSA-DAI WSRF binary distribution directory:
```
$ ant guiRemoveResourceTomcat
```
The tool will appear and you can select your Tomcat distribution by pressing the Select... button. If CATALINA_HOME is set then this will be offered as the default selection.
When you are happy with the Path press Next.
Now you will be asked to enter:
- The local URL of the data service, for example ogsadai/DataService, in the Service Path field.
- The ID of the data service resource, for example MyRelationalResource in the Data Service Resource ID field.
Press Next when you have entered this information.
You will now be requested to press Next so that the tool can remove the data service resource from the data service. If any problems occur then the tool will notify you of these.
When the removal has completed a completion window will be displayed. Press Finish to exit the tool.
You will need to shutdown and restart Tomcat before the changes take effect.

To remove data service resources from data services under GT4 requires execution of the guiRemoveResourceGT4

5.11. Updating Data Service Resource Role Maps

If you have deployed a configurable data service then you can make changes to the role maps file of any data service resources exposed by that data service. You can then request that the data service resource exposed by the service read in and use the updated role maps.

To update the role maps that a data service resource exposed by a specific data service uses:

Make the changes to the role maps document for the specific data service resource of interest:
- Within the GT4 container the role maps for a specific data service resource can be found in:
```
 etc/ogsadai_wsrf/ResourceID/DatabaseRoles.xml
```
  where ResourceID is the ID of the data service resource.
- Within Tomcat container the role maps for a specific data service resource can be found in:
```
 webapps/wsrf/WEB-INF/etc/ogsadai_wsrf/ResourceID/DatabaseRoles.xml
```
  where ResourceID is the ID of the data service resource.
Ensure that the GLOBUS_LOCATION environment variable is set.
Run the following command from within the OGSA-DAI WSRF binary distribution directory:
```
 $ ant dataServiceClient -Ddai.url=SERVICE-URL
                    -Ddai.resource.id=RESOURCE-ID -Ddai.action=updateRoleMaps
```
where
- dai.url specifies the URL of the data service. If omitted then a default URL of http://localhost:8080/wsrf/services/ogsadai/DataService is used.
- dai.resource.id specifies the data service resource at which the request is targeted.
For example:
```
 $ ant dataServiceClient 
                    -Ddai.url=http://localhost:8080/wsrf/services/ogsadai/MyDataService
                    -Ddai.resource.id=MySQLResource -Ddai.action=updateRoleMaps
```

The request will be forwarded to the data service. For example:

 [echo] Updating roleMaps for resource MySQLResource...
                    [java] Contacting ... http://localhost:8080/wsrf/services/ogsadai/DataService
                    [java] Service version: OGSA-DAI WSRF 1.0
                    [java] Number of resources: 1
                    [java] Resource: MySQLResource
                    [java] Data Service Resource: MySQLResource
                    [java] About to invoke UpdateRoleMaps...
                    [java] UpdateRoleMaps completed!

If you see the following message:

 [echo] Updating roleMaps for resource MySQLResource...
                    ...
                    [java] About to invoke UpdateRoleMaps...
                    [java] This service does not support the updateRoleMaps operation!

Then the data service is not configurable i.e. it does not allow data service resources to dynamically update their role maps.

5.12. End-to-end Client

OGSA-DAI comes with a client that allows you to:

Contact a data service and get a list of the data service resources it exposes.
Submit a Perform document to the data service and print the resulting Response document.

To submit a Perform document to a data service resource exposed by a data service and so perform some data resource-related activities (e.g. query a database):

Ensure that your Web services container is running.
Ensure that the GLOBUS_LOCATION environment variable is set.
Run the following command from within the OGSA-DAI WSRF binary distribution directory:
```
 $ ant dataServiceClient -Ddai.url=SERVICE-URL
                    -Ddai.resource.id=RESOURCE-ID
                    -Ddai.action=PERFORM-DOC-LOCATION
```
where
- -Ddai.url= specifies the URL of the data service. If omitted then a default URL of http://localhost:8080/wsrf/services/ogsadai/DataService is used.
- -Ddai.resource.id= specifies the data service resource at which the Perform document is targeted.
- -Ddai.action= specifies the location of an OGSA-DAI Perform document.
For example:
```
 $ ant dataServiceClient 
                    -Ddai.url=http://localhost:8080/wsrf/services/ogsadai/MyDataService
                    -Ddai.resource.id=MySQLResource
                    -Ddai.action=examples/GDSPerform/JDBC/query/select1Row.xml 
```

The Perform document will be forwarded to the data service and executed by the specified data service resource. For example:

 [echo] Executing Perform document on resource One...
                    [java] Contacting ... http://localhost:8080/wsrf/services/ogsadai/MyDataService
                    [java] Service version: OGSA-DAI WSRF 1.0
                    [java] Number of resources: 2
                    [java] Resource: MySQLResource
                    [java] Resource: AnotherResource
                    [java] Data Service Resource: MySQLResource
                    [java] About to invoke Perform...
                    [java] Perform completed!
                    [java] Response: 
                    [java] <?xml version="1.0" encoding="UTF-8"?>
                    [java] <ns1:response xmlns:ns1="http://ogsadai.org.uk/namespaces/2005/03/types">
                    [java] <request status="COMPLETED"
                    xmlns="http://ogsadai.org.uk/namespaces/2005/03/service/types"/>
                    ...

	Note
	As an alternative to setting CATALINA_HOME or GLOBUS_LOCATION you can specify the Tomcat or GT4 locations using the -Dtomcat.dir=/path/to/Tomcat/directory or -Dgt.dir=/path/to/Globus/directory flags respectively.

5.13. Configurable Data Services

Configurable data services are a special type of data service. Asides from all the operations and capabilities offered by services a configurable data service provides operations allowing the state of the service or the data service resources it exposes to be updated while the service is running.

These operations are intended for use by service deployers rather than clients of the service.

5.13.1. Configuration Operations

5.13.1.1. The Deploy Operation

This operation is not directed at a specific data service resource. Instead it contains the name of a data service resource which the data service is to expose. Upon completion of the operation clients will be able to access the named data service resource via the service.

It is the responsibility of the service deployer to ensure that the information required to configure the data service resource is available within the Web service container hosting the service.

5.13.1.2. The UpdateRoleMaps Operation

This operation is directed at a specific data service resource - (specified within the WS-Addressing Endpoint Reference). The operation requests that a data service resource re-read its role maps file which resides on the server.

This operation allows service deployers to change the list of clients authorised to access a data resource known to a data service resource and then to ensure that these changes take force immediately.

5.14. Undeploying OGSA-DAI WSRF

The OGSA-DAI WSRF binary distribution can be undeployed from the GT4 container or Apache Tomcat:

Either via the Command-line
Or using a GUI

Undeployment erases all OGSA-DAI XML Schema, OGSA-DAI-specific JAR files and configuration files from the destination.

5.14.1. Undeploying OGSA-DAI WSRF via the Command-line

5.14.1.1. Undeploying OGSA-DAI WSRF from GT4

To undeploy OGSA-DAI WSRF from GT4:

Set a GLOBUS_LOCATION environment variable to point to the location of your GT4 distribution. For example, under UNIX, enter:
```
 $ export GLOBUS_LOCATION=/path/to/Globus/directory
```
Run the following from within the OGSA-DAI binary distribution directory:
```
 $ ant undeployGT4
```

OGSA-DAI WSRF will then be undeployed.

5.14.1.2. Undeploying OGSA-DAI WSRF from Tomcat

To undeploy OGSA-DAI WSRF from Tomcat:

Set a CATALINA_HOME environment variable to point to the location of Tomcat. For example, under UNIX, enter:
```
 $ export CATALINA_HOME=/path/to/Tomcat/directory
```
Run the following from within the OGSA-DAI binary distribution directory:
```
 $ ant undeployTomcat
```

OGSA-DAI WSRF will then be undeployed from Tomcat.

Note

As an alternative to setting CATALINA_HOME you can specify the Tomcat location at the command-line as follows:

 $ ant undeployTomcat -Dtomcat.dir=/path/to/Tomcat/directory

5.14.2. Undeploying OGSA-DAI WSRF using a GUI

5.14.2.1. Undeploying OGSA-DAI WSRF from GT4

To undeploy OGSA-DAI WSRF from GT4:

Run the following from within the OGSA-DAI binary distribution directory:
```
 $ ant guiUndeployGT4
```
A GUI will appear and you can select your GT4 distribution by pressing the Select... button. If GLOBUS_LOCATION is set then this will be offered as the default selection.
When you are happy with the Path press Next.
You will now be requested to press Next so that the tool can deploy OGSA-DAI WSRF. If any problems occur then the tool will notify you of these.
When the undeployment has completed a completion window will be displayed. Press Finish to exit the tool.

5.14.2.2. Undeploying OGSA-DAI WSRF from Tomcat

To undeploy OGSA-DAI WSRF from Tomcat:

Run the following from within the OGSA-DAI binary distribution directory:
```
$ ant guiUndeployTomcat
```
A GUI will appear and you can select your Tomcat distribution by pressing the Select... button. If CATALINA_HOME is set then this will be offered as the default selection.
When you are happy with the Path press Next.
You will now be requested to press Next so that the tool can deploy OGSA-DAI WSRF. If any problems occur then the tool will notify you of these.
When the undeployment has completed a completion window will be displayed. Press Finish to exit the tool.

5.15. Where Does Stuff Go?

This section describes the locations of OGSA-DAI related files after deployment on Tomcat or GT4.

Under GT4, OGSA-DAI resides in the following places:

share/schema/ogsadai/ - OGSA-DAI XML Schema and WSDL.
lib/ - OGSA-DAI JAR files.
etc/ogsadai_wsrf/ - OGSA-DAI configuration files - see below.

Under Tomcat, OGSA-DAI resides in the following places:

webapps/wsrf/share/schema/ogsadai/ - OGSA-DAI XML Schema and WSDL.
webapps/wsrf/WEB-INF/lib/ - OGSA-DAI JAR files.
webapps/wsrf/WEB-INF/etc/ogsadai_wsrf/ - OGSA-DAI configuration files - see below.

The OGSA-DAI WSRF configuration files residing in the etc/ogsadai_wsrf directories are as follows:

server-config.wsdd - deployment descriptors for the current OGSA-DAI services.
jndi-config.xml - JNDI deployment descriptors for the current OGSA-DAI services (see the GT4 documentation for more information).
Data service resource files for each current data service. There will be one of these XML files for each current OGSA-DA service. These files maintain a list of the current data service resources for each data service. The file name is derived from the service path e.g. a service with relative service path ogsadai/DataService has a file _ogsadai_DataService.dsr.xml.
Data service resource directories. There is one such directory for each deployed data service resource - the directory shares the name of the data service resource e.g. MyRelationalResource Each directory contains:
- dataResourceConfig.xml - data resource configuration file for the data service resource.
- activityConfig.xml - activity configuration file for the data service resource.
- DatabaseRoles.xml - roleMaps file for the data service resource.

6. Testing

Please see the deployment section for information on testing and configuring OGSA-DAI.

7. Security considerations

OGSA-DAI does not provide any security over and above that already provided by the Globus Toolkit. However, consideration must be given to the role mapping which converts a grid credential to a database username/password. OGSA-DAI comes with two basic role mappers: a simple role mapper which accesses a plain text file with this information and one which encrypts the username/password information. More details can be found in the documentation bundled with the documentation. If neither of these schemes are secure enough then it is possible to replace it by implementing a new role mapper interface.

8. Troubleshooting

Generating verbose log output is a critical aid in troubleshooting of the DRS and is useful when communicating problems to Globus support lists. To increase logging detail, add the following line to the $GLOBUS_LOCATION/container-log4j.properties file.

        ...
        log4j.category.org.globus.replica=DEBUG
        ...

8.1. I am using MySQL and keep on getting a java.sql.SQLException: Cannot connect to MySQL server on localhost:3306 exception - what is the problem?

The MySQL JDBC driver recommended in the OGSA-DAI documentation is not compatible with the latest versions of MySQL. This is the case for MySQL 4.1.6 and 4.1.7 and may be the case for other versions. This problem usually causes the following error message to be logged:

java.sql.SQLException: Cannot connect to MySQL server on localhost:3306.

8.2. Is there a MySQL server running on the machine/port you are trying to connect to? (java.lang.NumberFormatException)

To address this problem all you need to do is use a newer version of the MySQL JDBC driver JAR which can be downloaded from:

http://www.mysql.com/products/connector/j/

If you have already deployed services using the incompatible JAR, follow these steps:

Stop your container.
Replace the JAR file in the lib directory in the container. See Where Does Stuff Go? above.
Restart the container.

8.3. Why do I get Exception in thread "main" java.lang.IllegalAccessError: tried to access field...?

This error can arise due to clashes of Xalan shipped with certain versions of Java and that shipped with the Globus Toolkit. Please see the OGSA-DAI FAQ at http://www.ogsadai.org.uk/docs/R6.0/doc/misc/FAQ.html#IllegalAccessError for more information.

Please check up the OGSA-DAI website (www.ogsadai.org.uk) for any updates. In particular the OGSA-DAI FAQ although note that this also caters for the non-WSRF distributions of OGSA-DAI.