GT 3.9.4 Java WS Core: Developer's Guide

Introduction

[introduction to developers with reference to General Toolkit Developer's Guide for coding guidelines, porting guide, etc.]

Architecture and design overview

  • Java WS Core Design Document [doc | pdf ]
  • Java WS Core UML [vsd]

Public interface

The semantics and syntax of the APIs and WSDL for the component, along with descriptions of domain-specific structured interface data, can be found in the public interface guide.

Usage scenarios

[describe how to use the programatic interfaces of the component, provide examples]

Tutorials

[add links to any tutorials - if no tutorials, say "There are no tutorials available at this time"]

Feature summary

New Features in the GT 3.9.4 release

  • Implementation of the OASIS WSRF and WSN working drafts specifications (with minor fixes to the 1.2-draft-01 published schemas and with the March 2004 version of the WS-Addressing specification)
  • Basic HTTP/1.1 client & server support
  • JNDI based registry based on the JNDI service in Apache Tomcat
  • An implementation of the Work Manager and Timer specifications

Other Supported Features

  • A standalone and embeddable container
  • Tomcat 4.1 and 5.0 support
  • Basic API for resource persistence and recovery
  • Persistent subscriptions support
  • Automatic service and ResourceHome activation on startup
  • Operation providers

Deprecated Features

  • None

Tested platforms

Java WS Core should work on any platform that supports J2SE 1.3.1 or higher.

Tested Platforms for Java WS Core

  • Linux (Red Hat 7.3)
  • Windows 2000
  • Solaris 9

Backward compatibility summary

Protocol changes since GT version 3.2

  • HTTP/1.1 with 'chunked' transfer encoding is now used by default.
  • Wire messages follow the new schemas and therefore are completely different (see below.)

API changes since GT version 3.2

  • Majority of the API are new. Some API resembles GT 3.2 API, for example ServiceData is replaced by ResourceProperty and ServiceDataSet is replaced by ResourcePropertySet.

Schema changes since GT version 3.2

  • Schemas are completely new. The WS Java Core implements the OASIS WSRF and WSN working drafts specifications (with minor fixes to the 1.2-draft-01 published schemas and with the March 2004 version of the WS-Addressing specification.)

Technology dependencies

Java WS Core depends on the following GT components:

Java WS Core depends on the following 3rd party software:

Security Considerations

Permissions of service configuration files

The service configuration files such as jndi-config.xml or server-config.wsdd (located under etc/<gar>/ directory) may contain private information such as database passwords, etc. Ensure that these configuration files are only readable by the user that is running the container.
The deployment process automatically sets the permissions of jndi-config.xml and server-config.wsdd files as user readable only. However, this might not work correctly on all platforms and this does not apply to any other configuration files.

Permissions of persistent data

The services using subscription persistence API or other basic persistence helper API will store all or part of its persistent data under the ~/.globus/persisted directory. Ensure that the entire ~/.globus/persisted directory is only readable by the user running the container.

Invocation of non-public service functions

A client can potentially invoke a service function that is not formally defined in the WSDL but it is defined in the service implementation class. There are two ways to prevent this from happening:

  1. Define all service methods in your service class as either private or protected.
  2. Configure appropriate allowedMethods or allowedMethodsClass parameter in the service deployment descriptor (please see the configuration interface for details).

Troubleshooting

NullPointerException using transport security

A client using transport security might fail with the following exception: 

 java.lang.NullPointerException
   at org.apache.axis.transport.http.HTTPSender.getSocket(HTTPSender.java:131)
   at org.apache.axis.transport.http.HTTPSender.writeToSocket(HTTPSender.java:370)
   at org.apache.axis.transport.http.HTTPSender.invoke(HTTPSender.java:88)
To fix this, add the following to the client: 
 import org.globus.axis.util.Util;
 ...
 static {
     Util.registerTransport();
 }
 ...

Running clients from any directory

A client launched directly through the java executable might fail if ran from a directory other then the GLOBUS_LOCATION (It usually happens if the client receives notifications).
To ensure that a client can be started from any directly pass a GLOBUS_LOCATION system property on the java command line set to the real GLOBUS_LOCATION directory.
For example on Unix: 

 $ java -DGLOBUS_LOCATION=$GLOBUS_LOCATION my.class
or on Windows: 
 > java -DGLOBUS_LOCATION=%GLOBUS_LOCATION% my.class

General troubleshooting information

In general, if you want to investigate a problem on your own please see the Debugging and Logging section for details on how to turn on debugging. Also, please note that most of the command line clients have -debug option that will display more detailed error messages including the error stack traces. Also, searching the mailing lists such as discuss@globus.org or developer-discuss@globus.org (before posting a message) can also be very fruitful. Finally, if you think you have found a bug please report it in our Bugzilla system. Please include as much as detail about the problem as possible.

Related Documentation

[could link to pdfs and whitepapers about protocols, etc re: the component]

Miscellaneous information

Debugging and Logging

Logging in the Java WS Core is based on the Jakarta Commons Logging API. Commons Logging provides a consistent interface for instrumenting source code while at the same time allowing the user to plug-in a different logging implementation. Currently we use Log4j as a logging implementation. Log4j uses a separate configuration file to configure itself. Please see Log4j documentation for details on the configuration file format.

Java WS Core is deployed with two Log4j configuration files:

  • $GLOBUS_LOCATION/container-log4j.properties (configures logging for the standalone container)
  • $GLOBUS_LOCATION/log4j.properties (configures logging for everything else besides the standalone container)

Tracing SOAP messages

There are three methods for tracing SOAP messages:

Using TcpMonitor

To trace SOAP messages on the wire you can use TcpMon from Apache Axis. After setting the environment using $GLOBUS_LOCATION/etc/globus-dev-env.[sh|csh|bat] run: 

java org.apache.axis.utils.tcpmon [listenPort targetHost targetPort]

If no arguments are used, you have to fill out these values in the GUI. Make sure to also start the standalone container with the proxy server port option set to the listenPort value.

Using MessageLoggingHandler

Another method for logging SOAP messages is to add the org.globus.wsrf.handlers.MessageLoggingHandler to the request or response chain in the server-config.wsdd or client-config.wsdd files.

For example: 

<requestFlow>
  ...
  <handler type="java:org.globus.wsrf.handlers.MessageLoggingHandler"/>
  ...
<requestFlow>

Then you must enable logging for this handler class in the appropriate log4j.properties files and change the logging level to DEBUG: 

log4j.category.org.globus.wsrf.handlers.MessageLoggingHandler=DEBUG
Enabling logging for Axis classes

Another method for tracing SOAP messages is to enable logging for selected Axis classes. Add the following lines to the appropriate log4j.properties files: 

 log4j.category.org.apache.client.Call=DEBUG
 log4j.category.org.apache.axis.transport.http.HTTPSender=DEBUG
 # enable the following logger for HTTPS/HTTPG transport handlers
 log4j.category.org.globus.axis.axis.transport=DEBUG

This will log Axis client side calls and Axis HTTP messages.

Debugging Log4j

If you are having problems with configuring Log4j, you can enable internal Log4j debugging by adding -Dlog4j.debug=true option on the java command line or passing it via the GLOBUS_OPTIONS environment property.

Tests

Tests in the Java WS Core are based on the JUnit API. JUnit must first be installed with Ant. To install JUnit with Ant copy the junit.jar found in JUnit distribution to the $ANT_HOME/lib directory.

Writing Tests

Always make sure to group your tests under PackageTests.java and/or SecurityTests.java test suites. Put all tests that require any type of credentials in the SecurityTests.java test suite.

If you are writing basic unit tests that do not require a container to run, just use the regular JUnit classes to write such tests.

If you are writing tests that require a container to execute, use the org.globus.wsrf.test.GridTestCase class instead of junit.framework.TestCase as your base class for your tests. Also ensure your PackageTests.java or SecurityTests.java extends the org.globus.wsrf.test.GridTestSuite instead of junit.framework.TestSuite.

The org.globus.wsrf.test.GridTestSuite and org.globus.wsrf.test.GridTestCase must be used together. The org.globus.wsrf.test.GridTestCase class exposes a TEST_CONTAINER variable that can be used to obtain the URL of the container (TEST_CONTAINER.getBaseURL()). By default an embedded container will be started for all tests in the test suite. To specify an external container, pass -Dweb.server.url=<base.url> system property on the java command line.

Running Tests

To execute the tests on the Java WS Core install, run the following (assuming the tests have been deployed into that install): 

cd $GLOBUS_LOCATION
ant -f share/globus_wsrf_test/runtests.xml runServer -Dtests.jar=<test.jar>

Where <test.jar> is an absolute path to the jar file that contains the tests.

By default, the tests that use a container will try to access a container running at http://localhost:8080/wsrf/services/.

To specify a different container, use the -Dtest.server.url=<url> property.

To execute PackageTests only, specify -DbasicTestsOnly=true.

To execute SecurityTests only, specify -DsecurityTestsOnly=true.

The test reports will be put in $GLOBUS_LOCATION/share/globus_wsrf_test/test-reports directory by default. The different test reports directory can be specified by passing -Djunit.reports.dir=<directory>.

GAR

The GAR (Grid Archive) file is a single file which contains all the files and information that the container needs to deploy a service. The GAR files are deployed using deployGar and undeployed using undeployGar Ant tasks.

GAR file structure

docs/
This directory contains service documentation files.
share/
This directory contains files that can be accessed or used by all services.
schema/
This directory contains service WSDL and schema files.
etc/
This directory contains service configuration files and a post-deploy.xml Ant script.
bin/
This directory contains service executables such as command line tools, GUI, etc.
lib/
This directory contains service and third party library files and any LICENSE files.
server-deploy.wsdd
This file is the server side deployment descriptor.
client-deploy.wsdd
This file is the client side deployment descriptor.
jndi-config-deploy.xml
This file is the JNDI configuration file.

Creating a gar file through Ant

[FILL ME IN]

GAR file deployment

The contents of the GAR file are processed in the following way (all steps are performed only if necessary):

  • Any files in the docs/ directory in the GAR are copied into $GLOBUS_LOCATION/docs/<gar.id>/ directory.
  • Any files in the share/ directory in the GAR are copied into $GLOBUS_LOCATION/share/<gar.id>/ directory.
  • Any files in the schema/ directory in the GAR are copied into $GLOBUS_LOCATION/share/schema/ directory.
  • Any files in the etc/ directory in the GAR are copied into $GLOBUS_LOCATION/etc/<gar.id>/ directory.
  • Any files in the bin/ directory in the GAR are copied into $GLOBUS_LOCATION/bin/ directory.
  • Any .jar files in the lib/ directory of the GAR are copied into $GLOBUS_LOCATION/lib/ directory.
  • Any file that contains the word "LICENSE" in the name in the lib/ directory of the GAR is copied into $GLOBUS_LOCATION/share/licenses/ directory.
  • The server-deploy.wsdd in the GAR is copied to $GLOBUS_LOCATION/etc/<gar.id>/server-config.wsdd. If a profile name was specified during deployment, the server-deploy.wsdd will be copied to $GLOBUS_LOCATION/etc/<gar.id>/<profile.name>-server-config.wsdd. The server-config.wsdd file will be set with user-only access permissions.
  • The jndi-config-deploy.xml in the GAR is copied to $GLOBUS_LOCATION/etc/<gar.id>/jndi-config.xml. If a profile name was specified during deployment the jndi-config-deploy.xml will be copied to $GLOBUS_LOCATION/etc/<gar.id>/<profile.name>-jndi-config.xml. The jndi-config.xml file will be set with user only-access permissions.
  • The client-deploy.wsdd in the GAR is merged into a common $GLOBUS_LOCATION/client-config.wsdd file.
  • An undeploy script ($GLOBUS_LOCATION/etc/globus_packages/<gar.id>/undeploy.xml) is created.
  • A etc/post-deploy.xml Ant script is called if the GAR contains one.

Notes:

  • If post-deploy.xml script creates some files, they will not be removed by undeploy.
  • During deployment, filtering is done for contents of server-deploy.wsdd and jndi-config-deploy.xml files to replace the @config.dir@ token with the "etc/<gar.id>" value, and the @gar.id@ token with the "<gar.id>" value.