GT 3.9.5 Java WS Core : System Administrator's Guide

Introduction
Building and Installing
Configuring
Deploying
Testing
Security Considerations
Troubleshooting
Usage statistics collection by the Globus Alliance

Introduction

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

This information is in addition to the basic installation instructions in the GT 3.9.5 System Administrator's Guide.

Building and Installing

Java WS Core is built and installed as part of a default GT 3.9.5 installation. For basic installation instructions, see the GT 3.9.5 System Administrator's Guide. No extra installation steps are required for this component.

The following are optional instructions for more advanced types of installations. These are for those advanced users who want to build the latest code from CVS or are just interested in the Java WS Core.

Building from source
Installing Core-only binary distribution

Building from source

Obtain the source code for Java WS Core:

From CVS

To get the latest source from cvs execute:

 cvs -d :pserver:anonymous@cvs.globus.org:/home/globdev/CVS/globus-packages \
     checkout wsrf

Change into the wsrf directory.
```
 cd wsrf
```

From Core-only source distribution

Untar or unzip the distribution archive.
```
 tar xvfz ws-core-XXX-src.tar.gz
```
Change into the unpacked distribution directory.
```
 cd ws-core-XXX
```

Set the GLOBUS_LOCATION environment variable to the absolute path of the target directory of your installation.

On Windows:

 set GLOBUS_LOCATION=c:\gt4

On Unix/Linux:

 setenv GLOBUS_LOCATION /soft/gt4/

 export GLOBUS_LOCATION=/soft/gt4/

If GLOBUS_LOCATION is not set, an install directory will be created under the current directory.

Run:

 ant all

On Unix/Linux add -DwindowsOnly=false to generate launch scripts for standard Globus tools such as grid-proxy-init, etc.

Installing Core-only binary distribution

Untar or unzip the distribution archive.

 tar xvfz ws-core-XXX-bin.tar.gz

Change into the unpacked distribution directory.

 cd ws-core-XXX

Set the GLOBUS_LOCATION environment variable to the unpacked distribution directory.

On Windows:

 set GLOBUS_LOCATION=c:\gt4

On Unix/Linux:

 setenv GLOBUS_LOCATION /soft/gt4/

 export GLOBUS_LOCATION=/soft/gt4/

Note: Please make sure to have the JAAS library installed if running with J2SE 1.3.1.

Configuring

Configuration overview

Java WS Core provides per- gar configuration and supports configuration profiles. The configuration information of a service is mainly encapsulated in two separate configuration files:

server-config.wsdd (Web Service Deployment Descriptor) - contains information about the web service.
jndi-config.xml (JNDI configuration file) - contains information about the resource management.

A service that support security might also have the security-config.xml (security deployment descriptor) file. Please see the Security Descriptor page in the GT4 WS Authorization Framework documentation for details.

All these configuration files are dropped into the $GLOBUS_LOCATION/etc/<gar.id>/ directory during the deployment process.

Global Configuration

The global properties are specified in the <globalConfiguration> section of *server-config.wsdd files in the $GLOBUS_LOCATION/etc/globus_wsrf_core/ directory. The configuration item name corresponds to the "name" attribute in a <parameter> sub element, and the value is put as a "value" attribute within the same parameter element.

General configuration parameters:

Name	Value	Description	Comments
logicalHost	<hostname>	This parameter specifies the hostname to use instead of the default local host. It is equivalent to setting the `GLOBUS_HOSTNAME` environment property. Can be FQDN or just hostname.	Optional
disableDNS	<boolean>	This parameter specifies whether to perform DNS lookup on the `logicalHost` parameter. By default `"false"` is assumed (DNS lookup is performed).	Optional
domainName	<domanin name>	This parameter specifies the domain name to append to the host name if the host name is not qualified by a domain.	Optional
publishHostName	<boolean>	This parameter specifies whether to publish the hostname or the ip address. It is only used when DNS lookups are enabled (`disableDNS` is false).	Optional

Standalone/embedded container-specific configuration parameters:

Name	Value	Description	Comments
containerThreads	<int>	This parameter controls the initial thread pool size for the container. By default it is set to 5.	Optional
containerThreadsMax	<int>	This parameter sets the maximum number of threads for the container. By default it is set to 4 * the `containerThread` setting.	Optional
containerThreadsHighWaterMark	<int>	This parameter controls when the thread pool of the container should start shrinking (if the number of idle threads exceeds this number). By default it is set to 2 * the `containerThread` setting.	Optional

Service Configuration

WSDD

An example of a deployment descriptor for a CounterService:

<service name="CounterService" provider="Handler"
         use="literal" style="document">
 <parameter name="className"
            value="org.globus.wsrf.samples.counter.CounterService"/>
 <parameter name="handlerClass"
            value="org.globus.axis.providers.RPCProvider"/>
 <parameter name="scope"
            value="Application"/>
 <wsdlFile>share/schema/core/samples/counter/counter_service.wsdl</wsdlFile>
 <parameter name="allowedMethodsClass"
            value="com.counter.CounterPortType"/>
 <parameter name="providers" value="
            DestroyProvider SetTerminationTimeProvider GetRPProvider 
            SubscribeProvider GetCurrentMessageProvider"/>
</service>

Services are defined in a <service> element. The "name" attribute of the <service> element defines the remotely accessible name of the service. The service handle will have the form of <hosting environment URL>/foo, where:

the hosting environment URL typically is http://<host>:<port>/wsrf/services.
foo is the name of the service (<service name="foo" ...>).

The use attribute should be set to literal and the style attribute to document for all WSRF/WSN based services.
The configuration information for a service is defined by various <parameter> sub-elements within a <service> element. The configuration item name corresponds to the "name" attribute in a <parameter> sub element, and the value is put as a "value" attribute within the same parameter element.

Axis Standard Parameters

Name	Value	Description	Comments
className	<class>	This parameter specifies a class that implements the web service methods.	Required
handlerClass	<class>	This parameter specifies what dispatcher to use, to dispatch a request to a service method. This parameter is required if the provider attribute of the service is set to `Provider`. The default dispatcher we provide is called org.globus.axis.providers.RPCProvider. It enables special features such as operation providers or security support.	Recommended in our environment
scope	<value>	Scope value can be one of: Request (the default), Application, or Session. If Request scope is used, a new service object is created for each SOAP request that comes in for the service. If Application scope is used, only a single instance of the service object is created and used for all SOAP requests that come in for the service. If Session scope is used, a new service object is created for each session-enabled client who accesses the service. Note: Only Request and Application scope is supported when used with org.globus.axis.providers.RPCProvider handlerClass.	Application scope is recommended
wsdlFile	<path>	This parameter points to a wsdl file for the service. The wsdl file must contain the wsdl:service entry. The file location can be relative or absolute. A relative file location is recommended.	Required in our environment
allowedMethods	<list of methods>	This parameter specifies a space or comma separated list of method names that can be called via SOAP. `"*"` indicates that all methods of the service class can be invoked via SOAP.	Optional. By default all methods are allowed.

Java WS Core Parameters

Name	Value	Description	Comments
loadOnStartup	<boolean>	This parameter will cause if set to true the web service, the corresponding ResourceHome (if any) to be initialized (with proper security settings if configured) at container startup. This is useful for restarting some tasks, etc. at container startup without calling the service. Please the Lifecycle and activation section for details.	Optional
allowedMethodsClass	<class>	This parameter is similar to the allowedMethods standard Axis property but it specifies a Java class or an interface that is introspected to come up with a list of allowed methods that can be called remotely on the service. To is useful to easily restrict the SOAP-accessible methods of the service. Usually the class specified in this parameter would be the remote interface class generated for the service. This parameter only has effect if used with org.globus.axis.providers.RPCProvider handlerClass.	Optional
providers	<list of providers>	This parameter specifies a space separated list of provider names or class names. Please see operation provider support section for details. This parameter only has effect if used with org.globus.axis.providers.RPCProvider handlerClass.	Optional

Please see Custom Deployment for details on Axis Web Services Deployment Descriptor.

JNDI

An example of a JNDI configuration bit for a CounterService:

 <service name="CounterService">
   <resource 
            name="home"
            type="org.globus.wsrf.samples.counter.CounterHome">
     <resourceParams>
        <parameter>
           <name>factory</name>
           <value>org.globus.wsrf.jndi.BeanFactory</value>
        </parameter>
        <parameter>
           <name>resourceClass</name>
           <value>org.globus.wsrf.samples.counter.PersistentCounter</value>
        </parameter>
        <parameter>
           <name>resourceKeyName</name>
           <value>{http://counter.com}CounterKey</value>
        </parameter>
        <parameter>
           <name>resourceKeyType</name>
           <value>java.lang.Integer</value>
        </parameter>
     </resourceParams>
   </resource>
 </service>

Each service in WSDD should have a matching entry in the JNDI configuration file with the same name. Under each service entry in JNDI different resource objects or entries might be defined. Please see the JNDI Details section for details.
Each service entry in JNDI should have a resource defined called "home". That resource is the ResourceHome implementation for the service (as specified by the type attribute). Depending on the ResourceHome implementation different options can be configured for the ResourceHome. Currently we have two main base ResourceHome implementations: org.globus.wsrf.impl.ResourceHomeImpl and org.globus.wsrf.impl.ServiceResourceHome.

Note: All "home" resources must specify a factory parameter with org.globus.wsrf.jndi.BeanFactory value.

ResourceHomeImpl

This implementation is a generic ResourceHome implementation. It supports persistent resources, resource caching, resource sweeper, etc.

Name	Value	Description	Comments
resourceKeyName	<qname>	This parameter specifies a QName of the resource key. The namespace is specified in the `{}`. For example, this QName will be used to discover the SOAP header that contains the key of the resource in the request.	Required
resourceKeyType	<class>	This parameter specifies the type of the resource key as a Java class. The key XML element is deserialized into this Java type. The Java type can be for any simple Java type, Axis generated bean, or a class with a type mapping.	Optional. Defaults to `java.lang.String`
resourceClass	<class>	This parameter specifies the classname of the resource object. This is used to ensure that right type of resource object is added to resource home and to instantiate the right object if resource supports persistence.	Required
sweeperDelay	<long>	This parameter specifies how often the resource sweeper runs in milliseconds.	Optional. Defaults to 1 minute
cacheLocation	<jndi path>	This parameter specifies the JNDI location of the resource cache for this resource home. Please see Configuring Resource Cache below for details.	Optional

Configuring Resource Cache

If ResourceHomeImpl is configured with resource class that implements the PersistenceCallback interface it will store the resource objects wrapped in Java SoftReference. That allows the JVM to automatically reclaim these resource objects thus reducing the memory usage. Since the JVM can decide to reclaim these objects at any point sometimes a resource object can be reclaimed between two subsequent invocations on the same resource. This for example can cause the state of the resource to be reloaded from disk on each call.
To prevent the JVM from reclaiming the resource objects so quickly a cache can be setup up to hold direct references to these objects. A basic LRU (least recently used) cache implementation is provided. Other cache implementations can be used as long as they implement the org.globus.wsrf.utils.cache.Cache interface.

To configure a cache for ResourceHomeImpl first define a cache resource entry in JNDI:

<resource name="cache" 
             type="org.globus.wsrf.utils.cache.LRUCache">
  <resourceParams>
     <parameter>
        <name>factory</name>
        <value>org.globus.wsrf.jndi.BeanFactory</value>
     </parameter>
     <parameter>
        <name>timeout</name>
        <value>120000</value>
     </parameter>
  </resourceParams>
</resource>

In this case a LRU cache is configured. The "timeout" parameter (in ms) is used to specify the idle time of the resource object before it is removed from the cache.
The same cache resource can be reused in different services but usually once cache per service will be configured.

Once the cache resource entry is defined add the "cacheLocation" parameter to the service home resource. The "cacheLocation" parameter value is the JNDI name of the cache resource:

<service name="CounterService">
   <resource name="home" type="...">
      <resourceParams>
         ...
         <parameter>
            <name>cacheLocation</name>
            <value>java:comp/env/CounterService/cache</value>
         </parameter>
         ...
      </resourceParams>
   </resource>
   ...
   <resource name="cache" 
             type="org.globus.wsrf.utils.cache.LRUCache">
   ...
   </resource>
</service>

Please note that once the object is removed from the cache it is still up to the JVM to actually reclaim the object.

ServiceResourceHome

This implementation does not accept any special parameters.

Usage Statistics Configuration

Java WS Core container and other GT services are configured to send out usage statistics. Please see the usage statistics section for more information.

The targets to which the usage statistics are sent to are configured via the usageStatisticsTargets parameter defined in the <globalConfiguration> section of the $GLOBUS_LOCATION/etc/globus_wsrf_core/server-config.wsdd file. The usageStatisticsTargets parameter specifies a space separated list of targets to which the usage statistics of various components will be sent to. Each target is of form: host[:port] (port is optional, if not specified a default port will be assumed). By default usage statistics are sent to usage-stats.globus.org:4810.

To disable sending of the usage statistics remove this parameter, comment it out, or remove all of its values.

Configuration Profiles

Configuration profiles allow for the same Java WS Core installation to have multiple configurations. That is, the same installation can be used to run different containers each with different configuration.

When a gar file is deployed, a -Dprofile option can be specified to deploy the configuration files under a specific profile name. If the profile name is specified, the deploy operation will drop the configuration file as $GLOBUS_LOCATION/etc/<gar.id>/<profile.name>-server-config.wsdd and/or $GLOBUS_LOCATION/etc/<gar.id>/<profile.name>-jndi-config.xml.
The configuration profiles can also be created by hand simply by copying and/or renaming the configuration files appropriately. Each configuration profile should duplicate the contents of $GLOBUS_LOCATION/etc/globus_wsrf_core/server-config.wsdd and $GLOBUS_LOCATION/etc/globus_wsrf_core/jndir-config.xml in order to make the basic functionality to work properly.

Once a configuration profile is created, the standalone container can be started with a -profile option to load configuration files in a specific profile.

Deploying

Recommended JVM settings for the container

It is recommended to increase the maximum heap size of the JVM when running the container. By default on Sun JVMs a 64MB maximum heap size is used. The maximum heap size can be set using the -Xmx JVM option. Example:

 $ setenv GLOBUS_OPTIONS -Xmx512M
 $ $GLOBUS_LOCATION/bin/globus-start-container

The above example will make the container start with maximum heap size set to 512MB.

It is also recommended to experiment with other JVM settings to improve performance. For example, the -server option on Sun JVMs enables a server VM which can deliver better performance for server applications.

Deploying Java WS Core into Tomcat

Please note that Tomcat 4.1.x and 5.0.x versions are supported. We recommend running Tomcat with Java 1.4.2+. Some GT services might not work properly in Tomcat.

To deploy Java WS Core installation into Tomcat run:

 $ cd $GLOBUS_LOCATION
 $ ant -f share/globus_wsrf_common/tomcat/tomcat.xml deploySecureTomcat -Dtomcat.dir=<tomcat.dir>

Where <tomcat.dir> is an absolute path to the Tomcat installation directory.

Please see the Tomcat & Transport Security documentation for other Tomcat configuration steps.

Enabling local invocations

To enable local invocations in Tomcat you must add axis-url.jar to the CLASSPATH before starting Tomcat.

For example on Windows:

 > cd <tomcat.dir>
 > set CLASSPATH=<tomcat.dir>\common\lib\axis-url.jar
 > bin\startup

On Unix/Linux (csh/tcsh):

 $ cd <tomcat.dir>
 $ setenv CLASSPATH <tomcat.dir>/common/lib/axis-url.jar
 $ bin/startup

Creating WAR file

To create a .war of Java WS Core installation do:

 $ cd $GLOBUS_LOCATION
 $ ant -f share/globus_wsrf_common/tomcat/tomcat.xml war -Dwar.file=<war.file>

Where <war.file> specifies an absolute path of the war file.

Please note that deploying a war file might not be enough to have a working Java WS Core deployment. For example, in some cases the xalan.jar must be placed in the endorsed directory of the container.

Testing

To execute Java WS Core tests first ensure Ant is configured with JUnit.

To execute the test do the following:

Start the standalone container with -nosec argument:

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

Run the interoperability tests:

 $ ant -f share/globus_wsrf_test/runtests.xml runServer \
       -Dtests.jar=$GLOBUS_LOCATION/lib/wsrf_test_interop.jar

Run the unit tests:

 $ ant -f share/globus_wsrf_test/runtests.xml runServer \
       -Dtests.jar=$GLOBUS_LOCATION/lib/wsrf_test_unit.jar -DbasicTestsOnly=true

Please see the Developer's Guide for more information on running the tests and the testing infrastructure.

Security Considerations

Permissions of service configuration files

The service configuration files such as jndi-config.xml or server-config.wsdd (located under $GLOBUS_LOCATION/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:

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

Troubleshooting

globus-stop-container fails with an authorization error
globus-start-container hangs during startup
Programs fail with java.lang.NoClassDefFoundError: javax/security/... errors
General troubleshooting information

`globus-stop-container` fails with an authorization error

By default globus-stop-container must be executed with the same credentials as the container is running with. If the ShutdownService or the container is configured with separate private key and certificate files (usually /etc/grid-security/containercert.pem and /etc/grid-security/containerkey.pem) do the following to stop the container:

 $ grid-proxy-init -cert /etc/grid-security/containercert.pem \
                   -key /etc/grid-security/containerkey.pem \
                   -out containerproxy.pem
 $ setenv X509_USER_PROXY containerproxy.pem
 $ globus-stop-container
 $ unsetenv X509_USER_PROXY
 $ rm containerproxy.pem

Alternatively, the ShutdownService can be configured with a separate gridmap file to allow a set of users to stop the container. Please see the WS Authentication & Authorization section for details.

`globus-start-container` hangs during startup

By default Sun 1.4.x+ JVMs are configured to use /dev/random device as an entropy source. Sometimes the machine can run out of entropy and applications (such as the container) using the /dev/random device will block until more entropy is available. One workaround for this issue is to configure the JVM to use /dev/urandom (non-blocking) device instead. For Sun JVMs a java.security.egd system property can be set to configure a different entropy source. To set the system property and pass it to globus-start-container script do the following:

 export GLOBUS_LOCATION=-Djava.security.egd=file:/dev/urandom

 setenv GLOBUS_LOCATION -Djava.security.egd=file:/dev/urandom

Note: This does not apply to Windows machines.

Programs fail with `java.lang.NoClassDefFoundError: javax/security/...` errors

These errors might occur when running with J2SE 1.3.1 and the JAAS library is not installed. Either install the JAAS library or upgrade to J2SE 1.4.x or higher.

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.

Usage statistics collection by the Globus Alliance

The following usage statistics are sent by Java WS Core by default in a UDP packet (in addition to the Java WS Core component code, packet version, timestamp, and the source IP address):

On container startup:
- container id - random number
- container type - standalone, servlet, or unknown
- event type - container startup
- list of services - service names only
On container shutdown:
- container id - random number
- container type - standalone, servlet, or unknown
- event type - container shutdown

If you wish to disable this feature, please see the Java WS Core System Administrator's Guide section on Usage Statistics Configuration for instructions.

Also, please see our policy statement on the collection of usage statistics.