Chapter 9. Java WS Core Admin Guide

1. Building and Installing

Java WS Core is built and installed as part of a default GT 4.0 installation. For basic installation instructions, see the GT 4.0 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.

1.1. Building from source

  1. Obtain the source code for Java WS Core:

    From CVS. 

    1. To get the latest source from cvs execute:

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

    2. Change into the wsrf directory.

       cd wsrf

    From Core-only source distribution. 

    1. Untar or unzip the distribution archive.

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

    2. Change into the unpacked distribution directory.

       cd ws-core-XXX

  2. 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/

    or

     export GLOBUS_LOCATION=/soft/gt4/

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

  3. Run:

     ant all

    Additional arguments can be specified on the ant command line to customize the build:

    • -DwindowsOnly=false - generate launch scripts for standard Globus tools such as grid-proxy-init, etc. (Unix/Linux only)
    • -Dall.scripts=true - generate Windows and Unix launch scripts
    • -Denable.container.desc=true - create and configure the container with a global security descriptor

1.2. Installing Core-only binary distribution

  1. Untar or unzip the distribution archive.

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

  2. Change into the unpacked distribution directory.

     cd ws-core-XXX

  3. 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/

    or

     export GLOBUS_LOCATION=/soft/gt4/

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

2. Configuring

2.1. 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:

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.

2.2. Syntax of the interface:

2.2.1. 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.

Table 9.1. General configuration parameters

NameValueDescriptionComments
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<domain 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
server.id<string> This parameter specifies the server id. The server id is used to uniquely identify each container instance. For example, each container gets its own persistent directory based on the server id. By default, the standalone container server id is "<ip>-<containerPort>". In Tomcat, the server id will default to "<ip>-<webApplicationName>". Optional (since GT 4.0.1)

Table 9.2. Standalone/embedded container-specific configuration parameters

NameValueDescriptionComments
containerThreads<int> This parameter controls the initial thread pool size for the container. If not set, it defaults to 2. In GT 4.0.3+ it defaults to 1. 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
containerTimeout<int> This parameter controls the container timeout. That is, the maximum amount of time the container will wait to receive a message from the client. By default it is set to 3 minutes. Optional (since GT 4.0.2)
webContext<name> This parameter specifies the context name under which the services are published under: http://<host>:<port>/<webContext>/services/MyService. By default "wsrf" name is used. In Tomcat, this parameter is always set to the web application's name. Optional (since GT 4.0.1)

Table 9.3. Default container thread pool settings

TypeMin. threadsMax. threads
standalone28
embedded28

Table 9.4. Default container thread pool settings (GT 4.0.3+ only)

TypeMin. threadsMax. threads
standalone220
embedded13

2.2.2. Service Configuration

2.2.2.1. 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.

Table 9.5. Axis Standard Parameters

NameValueDescriptionComments
className<class>This parameter specifies a class that implements the web service methods.Required
handlerClass<class> This parameter specifies what dispatcher to use to send 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 scopes are 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.

Table 9.6. Java WS Core Parameters

NameValueDescriptionComments
loadOnStartup<boolean> If set to true this parameter will cause the web service and 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 having to call the service. Please check 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. It is useful for easily restricting 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.

2.2.2.2. 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 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.

2.2.2.2.1. ResourceHomeImpl

The ResourceHomeImpl is a generic and reusable ResourceHome implementation. It supports persistent resources, resource caching, resource sweeper, etc.

Table 9.7. ResourceHomeImpl parameters

NameValueDescriptionComments
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 the 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
2.2.2.2.1.1. 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 one 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/services/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.

2.2.2.2.2. ServiceResourceHome

This implementation does not accept any special parameters.

2.2.3. 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.

2.2.4. 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 have the basic functionality 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.

3. Deploying

The Globus services can be run either in the standalone Java WS Core container that is installed with GT, or deployed into Tomcat.

3.1. Java WS Core container

The standalone Java WS Core container can be started and stopped with the provided globus-start-container and globus-stop-container programs. There are also helper programs (available only with the full GT installation) to start and stop the container detached from the controlling terminal (globus-start-container-detached and globus-stop-container-detached). These commands are documented in the Java WS Core Command Reference.

3.1.1. Deploying and undeploying services

To deploy a service into Java WS Core container use the globus-deploy-gar tool. To undeploy a service use globus-undeploy-gar. These commands are documented in the Java WS Core Command Reference.

3.1.2. Recommended JVM settings for the Java WS Core 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.

3.2. Deploying into Tomcat

To deploy a 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. Also, -Dwebapp.name=<name> can be specified to set the name of the web application under which the installation will be deployed. By default "wsrf" web application name is used.

The deploySecureTomcat task will update an existing Tomcat deployment if Java WS Core was already deployed under the specified web application name. The redeploySecureTomcat task can be used instead to overwrite the existing deployment.

[Note]Note

Please note that during deployment a subset of the files from Java WS Core installation is copied into Tomcat. Also, the copied files in Tomcat might have different permissions then the originals.

In addition to the above deployment step you will also need to modify the Tomcat <tomcat_root>/conf/server.xml configuration file. In particular you will need to add the following configuration entries:

  • Tomcat 4.1.x

    1. Add a HTTPS Connector in the <Service name="Tomcat-Standalone"> section and update the parameters appropriately with your local configuration:

      <Connector
        className="org.apache.catalina.connector.http.HttpConnector"
        port="8443" minProcessors="5" maxProcessors="75"
        authenticate="true" secure="true" scheme="https"
        enableLookups="true" acceptCount="10" debug="0">
          <Factory
             className="org.globus.tomcat.catalina.net.HTTPSServerSocketFactory"
              proxy="/path/to/proxy/file"
              cert="/path/to/certificate/file"
              key="/path/to/private/key/file"
              cacertdir="/path/to/ca/certificates/directory"/>
      </Connector>

      In the above the proxy, cert, key and cacertdir attributes are optional. Furthermore, the proxy and the combination of cert and key attributes are mutually exclusive.

      [Important]Important

      The credentials and certificate configuration is used only by the connector and is not used by the rest of the web services stack in Globus Toolkit. To configure credentials for use in the toolkit, refer Security Descriptor.

    2. Add a HTTPS Valve in the <Engine name="Standalone" ... > section:

      <Valve className="org.globus.tomcat.catalina.valves.HTTPSValve"/>
  • Tomcat 5.0.x

    1. Add a HTTPS Connector in the <Service name="Catalina"> section and update the parameters appropriately with your local configuration:

      <Connector
        className="org.globus.tomcat.coyote.net.HTTPSConnector"
        port="8443" maxThreads="150" minSpareThreads="25" maxSpareThreads="75" 
        autoFlush="true"
        disableUploadTimeout="true" scheme="https"
        enableLookups="true" acceptCount="10" debug="0" 
         proxy="/path/to/proxy/file"
         cert="/path/to/certificate/file"
         key="/path/to/private/key/file"
         cacertdir="/path/to/ca/certificates/directory"/>

      In the above the proxy, cert, key and cacertdir attributes are optional. Furthermore, the proxy and the combination of cert and key attributes are mutually exclusive.

      [Important]Important

      The credentials and certificate configuration is used only by the connector and is not used by the rest of the web services stack in Globus Toolkit. To configure credentials for use in the toolkit, refer Security Descriptor.

    2. Add a HTTPS Valve in the <Engine name="Catalina" ... > section:

      <Valve className="org.globus.tomcat.coyote.valves.HTTPSValve"/>
  • Tomcat 5.5.x

    1. Add a HTTPS Connector in the <Service name="Catalina"> section and update the parameters appropriately with your local configuration:

      <Connector
        className="org.globus.tomcat.coyote.net.HTTPSConnector"
        port="8443" maxThreads="150" minSpareThreads="25" maxSpareThreads="75" 
        autoFlush="true"
        disableUploadTimeout="true" scheme="https"
        enableLookups="true" acceptCount="10" debug="0" 
        protocolHandlerClassName="org.apache.coyote.http11.Http11Protocol"
        socketFactory="org.globus.tomcat.catalina.net.BaseHTTPSServerSocketFactory"
         proxy="/path/to/proxy/file"
         cert="/path/to/certificate/file"
         key="/path/to/private/key/file"
         cacertdir="/path/to/ca/certificates/directory"/>

      In the above the proxy, cert, key and cacertdir attributes are optional. Furthermore, the proxy and the combination of cert and key attributes are mutually exclusive.

      [Important]Important

      The credentials and certificate configuration is used only by the connector and is not used by the rest of the web services stack in Globus Toolkit. To configure credentials for use in the toolkit, refer Security Descriptor.

    2. Add a HTTPS Valve in the <Engine name="Catalina" ... > section:

      <Valve className="org.globus.tomcat.coyote.valves.HTTPSValve55"/>

Also, you may have to edit <tomcat.dir>/webapps/wsrf/WEB-INF/web.xml if you are running Tomcat on a non-default port, i.e. not using port 8443 (HTTPS). For example, if you run Tomcat on port 443 using HTTPS then the WSRF servlet entry should be modified as follows:

<web-app>
...
    <servlet>
        <servlet-name>WSRFServlet</servlet-name>
        <display-name>WSRF Container Servlet</display-name>
        <servlet-class>
            org.globus.wsrf.container.AxisServlet
        </servlet-class>
        <init-param>
            <param-name>defaultProtocol</param-name>
            <param-value>https</param-value>
        </init-param> 
        <init-param>
            <param-name>defaultPort</param-name>
            <param-value>443</param-value>
        </init-param>   
        <load-on-startup>true</load-on-startup> 
    </servlet>
...
</web-app>
[Note]Note

We recommend running Tomcat with Java 1.4.2+.

3.2.1. Enabling local invocations

To enable local invocation 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

3.2.2. Debugging

3.2.2.1. Tomcat log files

Please always check the Tomcat log files under the <tomcat.dir>/logs directory for any errors or exceptions.

3.2.2.2. Enabling Log4J debugging
  • Tomcat 4.1.x

    Copy $GLOBUS_LOCATION/lib/commons-logging.jar files to <tomcat.dir>/common/lib directory. Also, copy <tomcat.dir>/webapps/wsrf/WEB-INF/classes/log4j.properties file to <tomcat.dir>/common/classes/ directory. Then configure the Log4j configuration file in <tomcat.dir>/common/classes/ directory appropriately. The debugging settings will affect all the code in all web applications.

  • Tomcat 5.0.x, 5.5.x

    Copy $GLOBUS_LOCATION/lib/log4j-1.2.8.jar and $GLOBUS_LOCATION/lib/commons-logging.jar files to <tomcat.dir>/webapps/wsrf/WEB-INF/lib/ directory. Then configure the Log4j configuration file in <tomcat.dir>/webapps/wsrf/WEB-INF/classes/ directory appropriately. The debugging settings will only affect the web application code.

3.2.3. Creating WAR file

To create a .war of a 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 the 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.

3.2.4. Deploying and undeploying services

To deploy a service into Tomcat, first deploy the service into a regular GT installation using the globus-deploy-gar tool and then deploy the GT installation into Tomcat (as described in Section 3, “Deploying”). Similarly, to undeploy a service, first undeploy the service from a regular GT installation using globus-undeploy-gar tool and then deploy the GT installation into Tomcat.

[Note]Note

Some GT services may not work properly in Tomcat.

4. Testing

To execute Java WS Core tests first ensure Ant is configured with JUnit (To install JUnit with Ant copy the junit.jar found in the JUnit distribution to the $ANT_HOME/lib directory).

To execute the test do the following:

  1. Start the standalone container with -nosec argument:

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

  2. Run the interoperability tests:

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

  3. Run the unit tests:

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

  4. If some tests failed examine the test results in the $GLOBUS_LOCATION/share/globus_wsrf_test/tests/test-reports/ directory.

Please see the developer guide for more information on running the tests and the testing infrastructure.

5. Security Considerations

5.1. 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 the 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.

5.2. 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.

5.3. 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 Java WS Core Configuration for details).

6. Troubleshooting

6.1. globus-stop-container fails with an authorization error

By default globus-stop-container must be executed with the same credentials as the container it 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.

6.2. 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_OPTIONS=-Djava.security.egd=file:/dev/urandom

or

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

The same issue can also affect client programs. If you are running a client program with a GT generated script, you can set the GLOBUS_OPTIONS environment property as described above. However, if you are using a custom script or directly launching a program using the java command line, make sure to set the java.security.egd system property explicitly on the java command line. For example:

 java -classpath $CLASSPATH -Djava.security.egd=file:/dev/urandom my.package.FooProgram

Note: This does not apply to Windows machines.

6.3. 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.

6.4. ConcurrentModificationException in Tomcat 5.0.x

If the following exception is visible in the Tomcat logs at startup it might cause the HTTPSValve to fail:

java.util.ConcurrentModificationException
	at java.util.HashMap$HashIterator.nextEntry(HashMap.java:782)
	at java.util.HashMap$EntryIterator.next(HashMap.java:824)
	at java.util.HashMap.putAllForCreate(HashMap.java:424)
	at java.util.HashMap.clone(HashMap.java:656)
	at mx4j.server.DefaultMBeanRepository.clone(DefaultMBeanRepository.java:56)

The HTTPSValve might fail with the following exception:

java.lang.NullPointerException
	at org.apache.coyote.tomcat5.CoyoteRequest.setAttribute(CoyoteRequest.java:1472)
	at org.apache.coyote.tomcat5.CoyoteRequestFacade.setAttribute(CoyoteRequestFacade.java:351)
	at org.globus.tomcat.coyote.valves.HTTPSValve.expose(HTTPSValve.java:99)

These exceptions will prevent the transport security to work properly in Tomcat.

This is a Tomcat bug. Keep restarting Tomcat until it starts without the ConcurrentModificationException or switch to a different version of Tomcat.

6.5. java.net.SocketException: Invalid argument or cannot assign requested address

If you see the "java.net.SocketException: Invalid argument or cannot assign requested address" error in the container log or on the client side try setting the following property:

 $ export GLOBUS_OPTIONS="-Djava.net.preferIPv4Stack=true"

6.6. 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 a -debug option that will display more detailed error messages, including the error stack traces. Also, searching the mailing lists such as gt-user@globus.org or gt-dev@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.

7. 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
    • list of activated services - service names only (4.0.3+)
    • container uptime (4.0.3+)

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.