GIPSE (formerly AMDS) BioSense

Note: Although this service was developed for BioSense, it is designed to be usable by any JDBC data source that can create rather simple views to represent GIPSE data. Please see the gipse-store project for example data structures in MS SQLServer and PostgreSQL.

GIPSE Service Instruction Set

Prerequisites:

Java: Jdk 1.5 or greater

Ant: apache 1.7 or greater

Globus: ws-core 4.0.5 or greater

Databases

• SQL Server
• Postgresql
• Other databases will require that the jdbc jar files to be downloaded and installed. The package includes the above mentioned jars. The service does not have db-specific functionality, but NCPHI has only tested using the above database servers.

Software used in developing service:

Introduce 1.3 was used to develop the service. Although you can modify using the ant scripts generated by Introduce, you can also use Introduce to graphically modify. Introduce was a massive timesaver. We used the latest version of Introduce which is really leaps and bounds improvement over 1.2. Great thanks to the Introduce team for the work they are doing on making sure Introduce works with non-caBIG/cagrid Globus platforms.

Dependencies:

GIPSE Schema for 8/31/2009 (included in deployment) - note that this schema is in draft so future versions of this service will support future versions of the GIPSE/AMDS schema.

iBatis (included in deployment)

cagrid security components (included in deployment)

Configuring, Building, Deploying Source:

1. Download service package (source)

Create a temporary directory and use the subversion command

svn co http://phgrid.googlecode.com/svn/GIPSEService/trunk

(note, the alpha release was stored under AMDSCore. While this project is still in SVN for reference please do not use this project any longer)

2. Set environment variables

Set the following environment variables:

Set GLOBUS_LOCATION

Set JAVA_HOME

Set ANT_HOME

3. Configure gipse.properties

Rename the gipse.properties.template file to gipse.properties. Using your preferred text editor, modify the following properties with the values appropriate for your environment:

db.jdbc.url=jdbc:postgresql://localhost:5432/postgres

db.jdbc.driver=org.postgresql.Driver

db.jdbc.user=postgres

db.jdbc.password=postgres

db.gipse.table=gipse_view

There are other properties to configure, but they are less likely that you will need to modify their default values.

4. Build GIPSEService (optional)

Type "ant all" to build the GIPSE jar files

This will create many files necessary to run the service. Specifically:

./build/lib/GIPSEService-client.jar (Java classes for running the client)

./build/lib/GIPSEService-common.jar (Java classes common to both client and service classes)

./build/lib/GIPSEService-service.jar (Java classes for running the service)

./build/lib/GIPSEService-stubs.jar (Java classes for representing XML structures)

./build/lib/GIPSEService-test.jar (Java classes for testing service)

If you are building other Java applications and wish to use access the client, you will need GIPSEService-client.jar, GIPSEService-stubs.jar, and GIPSEService-common.jar

5. Deploy service

You can deploy the service using:

"ant deployGlobus" (to a plain Globus container)

"ant deployTomcat" (to Globus inside Tomcat)

"ant deployJBoss" (to Globus inside JBoss)

"ant createDeploymentGar" (create a plain gar and you manually deploy it)

This will build the source. In the Service directory you will see the produced gar:

gipse_GIPSEService.gar

6. Configure metadata

The GIPSEService uses the metadata operation to describe what indicators are supported, what dates, etc. etc. The example metadata file will need to be changed based on your service configuration. Use your preferred XML editor to edit $GLOBUS_LOCATION/etc/gipse_GIPSEService/MetadataResponseExample.xml

If Globus is running, restart it after changing the file.

7. Test Deployment (optional)

Run the JUnit tests to test database access and service access using:

"ant test:

You should get something written to the console like this:

[junit] Running test.gov.cdc.ncphi.phgrid.gipse.services.TestGIPSEService

[junit] Tests run: 7, Failures: 0, Errors: 0, Time elapsed: 3.058 sec

Running and Connecting to the Service

Testing your deployed service via a default grid client:

Once you have started the Globus container, you can test your newly deployed service by using the packaged default client. To run the test, follow these instructions:

ant runClient

This command will call the QueryMetadata and QueryGIPSE operations on the service deployed to your local Globus. Note, you can edit the query that is sent by editing GIPSEQueryRequest-ForClient.xml

Globus Client:

If you would like to use the service client within your application, include the following jars in your classpath:

./build/lib/GIPSEService-client.jar

/build/lib/GIPSEService-stubs.jar

$GLOBUS_LOCATION/lib

Get a handle to the client like so:

GIPSEServiceClient client = new GIPSEServiceClient(urlToService);

And call the appropriate methods to access service (queryMetadata and queryGIPSE).

If you would like examples of building the Axis Transfer Objects, refer to the client source code as well as the JUnit source code.

Troubleshooting:

If you get this error "SET AUTOCOMMIT TO OFF is no longer supported" while calling the service, please refer to http://phgrid.blogspot.com/2009/06/conflicting-postgresql-drivers.html for help. This bug is sometimes seen with Linux PHGrid nodes using the service.

Note on WSDL:

Since both the Training Node and the Production node are running in secure mode, the WSDL file is not directly available unless you have a valid client cert. So the WSDL file and the WSDL schema include are provided below for reference. The SOAP endpoint location for the training node is: https://ncphi.phgrid.net:8443/wsrf/services/gipse/GIPSEService and for the production node will be:https://phgrid.cdc.gov/wsrf/services/gipse/GIPSEService