Installing the OGSA-DQP 3.1 GDQS (Coordinator)

Contents

• Overview
• Prerequisite software
• GDQS WSRF installation
  • Where does stuff go?
• GDQS WS-I installation
  • Where does stuff go?
• GDQS configuration files

Overview

The coordinator is implemented as a set of OGSA-DAI data service resources and activities. There are two data service resources:

• The GDQS factory data service resource: used by the client to create GDQS data service resources.
• The GDQS data service resource: used by the client to execute queries. Each GDQS data service resource is able to concurrently process multiple queries from clients.

OGSA-DQP adds two new activities to the those provided by OGSA-DAI:

• The DQPFactory activity: supported by the GDQS factory data service resources, this activity is used to create GDQS data service resources.
• The OQLQueryStatement activity, supported by GDQS data service resources, this activity is used to execute distributed queries.

The process of installing the coordinator therefore involves the following steps:

1. Installing the aforementioned data service resource implementations and activities.
2. Deploying a GDQS factory data service resource, which allows clients to create GDQS data service resources.

This process is simplified by the provision of an Apache Ant build file which contains targets which will automatically install the coordinator code and activities, and then deploy a GDQS factory data service resource. Installation differs slightly depending on whether the OGSA-DAI platform on which the GDQS is installed is based on WSRF or WS-I.

Prerequisites

• Java 1.4.x (tested with Java 1.4.2_07)
  • Required to compile and run OGSA-DQP; obtained from http://www.java.sun.com
• The Polar* query compiler.
  • See the installation instructions.
• An installation of OGSA-DAI WS-I 2.2 (Axis 1.2.1 version) or OGSA-DAI WSRF 2.2 deployed using Apache Tomcat 5.0.28. Note: although it should be possible to install the coordinator using a container other than Tomcat, the build file provided in the OGSA-DQP distribution works with Tomcat only. Installation on other containers has not been tested and is not recommended.
• Jakarta Ant 1.6.5
  • Required to execute targets in the OGSA-DQP build file; obtained from: http://ant.apache.org

OGSA-DQP WSRF Installation

1. The following environment variables should have been set during the installation of Tomcat:

• JAVA_HOME -- location of Java
• CATALINA_HOME -- location of Tomcat

Ensure that these environment variables have been set before proceeding.

2. Deploy an OGSA-DAI data service as described in the OGSA-DAI WSRF user guide. The data service initially exposes 0 data service resources.

3. Run the following from within the coordinator directory of the OGSA-DQP distribution:

$ ant deploy.tomcat.wsrf -Dresource.id=RESOURCE-ID
 -Dservice.path=SERVICE-PATH 
 -Dpolarstar=POLARSTAR-EXECUTABLE

Where:

• RESOURCE-ID is the resource ID of the GDQS factory data service resource. Typically this argument will take the value "dqp-factory".
• SERVICE-PATH is the path of the data service deployed in step (2), for example: ogsadai/service1.
• POLARSTAR-EXECUTABLE is the absolute path of the prerequisite Polar* executable (typically "qcomp" or "qcomp.exe").

[Warning: please be accurate when specifying the and polarstar argument. The consequences of a mistake made here will cause the coordinator to fail with a rather generic error message during query compilation or execution, however no error message will be given at the time that the above command is executed.]

4. Start-up Tomcat.

If these steps are performed successfully, the result is that the GDQS factory data service resource is added to the data service resources exposed by the specified data service.

Where does stuff go?

(Please read this section only if you are interested in where the Ant build file copies OGSA-DQP related files under Tomcat)

The following jar files are copied to the webapps/wsrf/WEB-INF/lib directory of the Tomcat installation for OGSA-DAI WSRF:

• gdqs.jar: contains the compiled coordinator Java code.
• dqp-evaluator.jar: contains the compiled evaluator code (required because the coordinator contains a root evaluator which compiles data received from other evaluators).
• castor-0.9.7.jar and castor-0.9.7-xml.jar: contain Castor libraries which are used by OGSA-DQP for Java-to-XML binding.
• xmlParserAPIs-2.6.2.jar: contains Apache Xerces libraries required by the coordinator.

The following files are copied to the webapps/wsrf/share/schema/ogsadai/xsd/activities directory of the Tomcat installation:

• oql_query_statement.xsd: the OQLQueryStatement activity XML Schema.
• gdqs_factory.xsd: the GDQSFactory activity XML Schema.

The following file is copied to the webapps/axis/WEB-INF/classes directory of the Tomcat installation:

• QueryEvaluator.properties: properties file for the root evaluator.

A directory will be created in the webapps/wsrf/WEB-INF/etc/ogsadai_wsrf directory of the Tomcat installation. The created directory will have the same name as the deployed GDQS factory data service resource ID (typically this name will be "dqp-factory"). The content of this directory, which contains various OGSA-DQP related configuration files, is described here.

OGSA-DQP WS-I Installation

1. The following environment variables should have been set during the installation of Tomcat:

• JAVA_HOME -- location of Java
• CATALINA_HOME -- location of Tomcat

Ensure that these environment variables have been set before proceeding.

2. Deploy an OGSA-DAI data service as described in the OGSA-DAI WS-I user guide. The data service initially exposes 0 data service resources.

3. Run the following from within the coordinator directory of the OGSA-DQP distribution:

$ ant deploy.tomcat.wsi
 -Dresource.id=RESOURCE-ID -Dservice.path=SERVICE-PATH
 -Dpolarstar=POLARSTAR-EXECUTABLE

Where:

• RESOURCE-ID is the resource ID of the GDQS factory data service resource. Typically this argument will take the value "dqp-factory".
• SERVICE-PATH is the path of the data service deployed in step (2), for example: ogsadai/service1.
• POLARSTAR-EXECUTABLE is the absolute path of the prerequisite Polar* executable (typically "qcomp" or "qcomp.exe").

[Warning: please be accurate when specifying the polarstar argument. The consequences of a mistake made here will cause the coordinator to fail with a rather generic error message during query compilation or execution, however no error message will be given at the time that the above command is executed.]

4. Start-up Tomcat.

If these steps are performed successfully, the result is that the GDQS factory data service resource is added to the data service resources exposed by the data service specified.

Where does stuff go?

(Please read this section only if you are interested in where the Ant build file copies OGSA-DQP related files under Tomcat for OGSA-DAI WS-I)

The following jar files are copied to the webapps/axis/WEB-INF/lib directory of the Tomcat installation:

• gdqs.jar: contains the compiled coordinator Java code.
• dqp-evaluator.jar: contains the compiled evaluator code (the coordinator contains a root evaluator which compiles data received from other evaluators).
• castor-0.9.7.jar and castor-0.9.7-xml.jar: contain Castor libraries which are used by OGSA-DQP for Java-to-XML binding.

• xmlParserAPIs-2.6.2.jar: contains Apache Xerces libraries required by the coordinator.

The following files are copied to the webapps/axis/schema/ogsadai/xsd/activities directory of the Tomcat installation:

• oql_query_statement.xsd: the OQLQueryStatement activity XML Schema.
• gdqs_factory.xsd: the GDQSFactory activity XML Schema.

The following files are copied to the webapps/axis/WEB-INF/classes directory of the Tomcat installation:

• client-config.wsdd: used to generate WS-Addressing headers when communicating with WSRF services.
• QueryEvaluator.properties: properties file for the root evaluator.

The following Jar files are copied to the webapps/axis/WEB-INF/lib directory of the Tomcat installation in order to enable communication with OGSA-DAI WSRF data services:

• cog-jglobus.jar
• jce-jdk13-125.jar
• addressing-1.0.jar
• wsrf_core.jar
• wsrf_core_stubs.jar
• wss4j.jar

A directory will be created in the webapps/axis/WEB-INF/etc/ogsadai_wsi directory of the Tomcat installation. The created directory will have the same name as the deployed GDQS factory data service resource ID (typically this name will be "dqp-factory"). The content of this directory, which contains various OGSA-DQP related configuration files, is described below.

Installed Configuration Files

This section describes the OGSA-DQP configuration files which are used by the coordinator.

• activityConfig.xml: the OGSA-DAI configuration file which specifies the list of activities supported by the GDQS factory data service resource.
• sessionConfig.xml: the OGSA-DAI session management configuration file for the GDQS factory data service resource.
• dataResourceClassConfig.xml: the OGSA-DAI data resource class configuration file which specifies the class name of the GDQS factory data resource accessor. OGSA-DAI data resource accessors are the extensibility points provided by OGSA-DAI which allow developers to add new resource types to those provided by OGSA-DAI. For details, see the OGSA-DAI documentation.
• instance/activityConfig.xml: the OGSA-DAI configuration file which specifies the list of activities supported by any GDQS data service resources.
• instance/sessionConfig.xml: the OGSA-DAI session management configuration file for GDQS data services resources.
• instance/dataResourceClassConfig.xml: the OGSA-DAI data resource class configuration file which specifies the class name of the GDQS data resource accessor.
• instance/config.xml: contains global installation configuration information for the coordinator, for example, the location of the Polar* executable.
• instance/dqp-factory-configuration.xml: contains default configuration parameters such as the locations of evaluators and the databases to be used by created GDQS data service resources. The specification of this information during installation is optional. Read more about this configuration file here.

© The University of Newcastle, 2006. © The University of Manchester, 2006.