GT 3.9.5 Java WS Core : User's Guide

• Introduction
• Command-line tools
• Graphical user interfaces
• Troubleshooting
• Miscellaneous information
  • Running Java Programs From Command Line
• Usage statistics collection by the Globus Alliance

Introduction

[End user-friendly introduction AND references to the Toolkit-level User's Guide where they can find general end user-oriented information]

Command-line tools

• globus-start-container
• globus-stop-container
• wsrf-destroy
• wsrf-set-termination-time
• wsrf-query
• wsrf-get-property
• wsrf-get-properties
• wsrf-insert-property
• wsrf-delete-property
• wsrf-update-property
• wsn-get-current-message
• wsn-pause-subscription
• wsn-resume-subscription
• wsn-subscribe
• globus-deploy-gar
• globus-undeploy-gar

The above command line tools are available on Unix and Windows platforms and will work in the same way (of course within the platform rules - the path syntax, variable definitions, etc.).

The wsrf-* and wsn-* clients should work against any service that supports the given WSRF or WSN operations.

globus-start-container

Tool description

Starts a standalone container. By default a secure container is started on port 8443 and is accessible via HTTPS. On successful startup a list of services will be displayed on the console. By default the non secure (HTTP) container is started on port 8080.

Command syntax

globus-start-container [options]

globus-stop-container

Tool description

Stops a standalone container. By default this command will attempt to stop a container running on localhost:8443 and perform a soft shutdown.

The globus-stop-container command invokes a ShutdownService running in the container. By default that service is configured to perform self authorization and therefore the globus-stop-container must be executed with the same credentials as the container is running with. Alternatively, the service can be configured with a gridmap file to allow a subset of users (with their own credentials) to invoke the service (please see the service security deployment descriptor for details).

Command syntax

globus-stop-container [options] ['soft' | 'hard']

Where:

'soft'

This option lets the threads die naturally

'hard'

This option forces an immediate JVM shutdown.

Example:

$ globus-stop-container soft

wsrf-destroy

wsrf-destroy [options]

Example:

$ wsrf-destroy -s http://localhost:8080/wsrf/services/CounterService \
   -k "{http://counter.com}CounterKey" 123

wsrf-set-termination-time

wsrf-set-termination-time [options] <seconds> | 'infinity' 

Example:

$ wsrf-set-termination-time -s http://localhost:8080/wsrf/services/CounterService \
   -k "{http://counter.com}CounterKey" 123 30

wsrf-query

wsrf-query [options] [query expression] [dialect]

Example:

$ wsrf-query -s http://localhost:8080/wsrf/services/ContainerRegistryService \
   "/*/*/*/*[local-name()='Address']"

wsrf-get-property

wsrf-get-property [options] <property>

The <property> is a QName of the resource property in the string form: {namespaceURI}localPart.

Example:

$ wsrf-get-property -s http://localhost:8080/wsrf/services/CounterService \
   -k "{http://counter.com}CounterKey" 123 \
  "{http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceLifetime-1.2-draft-01.xsd}CurrentTime"

wsrf-get-properties

wsrf-get-properties [options] <property1> [<property2>... <propertyN>]

Each <propertyN> is a QName of the resource property in the string form: {namespaceURI}localPart.

Example:

$ wsrf-get-properties -s http://localhost:8080/wsrf/services/CounterService \
  -k "{http://counter.com}CounterKey" 123 \ 
  "{http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceLifetime-1.2-draft-01.xsd}CurrentTime" \
  "{http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceLifetime-1.2-draft-01.xsd}TerminationTime"

wsrf-insert-property

wsrf-insert-property [options] <propertyValueFile>

The <propertyValueFile> is an XML file that contains the value of the resource property. The QName of the property is the outer most element.

Example:

Contents of in.xml:

 <doc>
   <ns1:foo xmlns:ns1="http://widgets.com">
     Value1
   </ns1:foo>
   <ns1:foo xmlns:ns1="http://widgets.com">
     Value2
   </ns1:foo>
 </doc>

$ wsrf-insert-property -s http://localhost:8080/wsrf/services/WidgetService \
   -k "{http://www.globus.org/namespaces/2004/06/core}WidgetKey" 123 \
   in.xml

wsrf-update-property

wsrf-update-property [options] <propertyValueFile>

The <propertyValueFile> is an XML file that contains the value of the resource property. The QName of the property is the outermost element.

Example:

Contents of in.xml:

 <doc>
   <ns1:foo xmlns:ns1="http://widgets.com">
     Value
   </ns1:foo>
 </doc>

$ wsrf-update-property -s http://localhost:8080/wsrf/services/WidgetService \
   -k "{http://www.globus.org/namespaces/2004/06/core}WidgetKey" 123 \
   in.xml

wsrf-delete-property

wsrf-delete-property [options] <property>

The <property> is a QName of the resource property in the string form: {namespaceURI}localPart.

Example:

$ wsrf-delete-property -s http://localhost:8080/wsrf/services/WidgetService \
   -k "{http://www.globus.org/namespaces/2004/06/core}WidgetKey" 123 \
   "{http://widgets.com}foo"

wsn-get-current-message

wsn-get-current-message [options] <topic>

The <topic> is a QName of the resource property in the string form: {namespaceURI}localPart.

Example:

$ wsn-get-current-message -s http://localhost:8080/wsrf/services/CounterService \
   -k "{http://counter.com}CounterKey" 123 \ 
   "{http://counter.com}Value"

wsn-pause-subscription

wsn-pause-subscription [options]

Example:

$ wsn-pause-subscription -s http://localhost:8080/wsrf/services/SubscriptionManagerService \
   -k "{http://www.globus.org/namespaces/2004/06/core}acc271c0-4df9-11d9-ab19-87da3bc7cf28"

wsn-resume-subscription

wsn-resume-subscription [options]

Example:

$ wsn-resume-subscription -s http://localhost:8080/wsrf/services/SubscriptionManagerService \
   -k "{http://www.globus.org/namespaces/2004/06/core}acc271c0-4df9-11d9-ab19-87da3bc7cf28"

wsn-subscribe

wsn-subscribe [options] <topic>

The <topic> is a QName of the resource property in the string form: {namespaceURI}localPart.

The following are subscribe-specific options in addition to the common options:

Example:

$ wsn-subscribe -s http://localhost:8080/wsrf/services/CounterService \
   -k "{http://counter.com}CounterKey" 123 \ 
   "{http://counter.com}Value"

globus-deploy-gar

globus-deploy-gar <gar.file> [options]

The <gar.file> is an path to the GAR file to be deployed. The -profile option can be used to specify the profile name under which the configuration files in the GAR will be deployed. Please see Configuration Profiles for details.

Example:

$ globus-deploy-gar /tmp/gars/globus_wsrf_core_samples_counter.gar

The globus-deploy-gar invokes Ant task. The above example is equivalent to running:

$ ant -f $GLOBUS_LOCATION/share/globus_wsrf_common/build-packages.xml deployGar \
      -Dgar.name=/tmp/gars/globus_wsrf_core_samples_counter.gar

The profile name can be passed using -Dprofile Ant option. Make sure to use absolute path name for the gar file when using Ant directly.

globus-undeploy-gar

globus-undeploy-gar <gar.id>

$ globus-undeploy-gar globus_wsrf_core_samples_counter

$ ant -f $GLOBUS_LOCATION/share/globus_wsrf_common/build-packages.xml undeployGar \
      -Dgar.id=globus_wsrf_core_samples_counter

Common Command syntax

-k "{http://www.globus.org}MyKey" 123

Graphical user interfaces

There is no support for this type of interface for Java WS Core.

Troubleshooting

• Running clients from any directory
• General troubleshooting information

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 directory pass a GLOBUS_LOCATION system property on the java command line set to the appropriate GLOBUS_LOCATION directory.
For example on Unix/Linux:

 $ java -DGLOBUS_LOCATION=$GLOBUS_LOCATION foo.MyClass

 > java -DGLOBUS_LOCATION=%GLOBUS_LOCATION% foo.MyClass

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.

Miscellaneous information

Running Java Programs From Command Line

Sometimes it might be necessary to run a Java program directly using the java executable. There are two recommended ways of doing so (the GLOBUS_LOCATION environment variable must first be set in both cases):

With globus-devel-env script help

The globus-devel-env script can be used to set the proper CLASSPATH environment variable.
To set the CLASSPATH on Windows execute:

 > %GLOBUS_LOCATION%\etc\globus-devel-env.bat

On Unix/Linux machines execute (for bash/sh):

 $ . $GLOBUS_LOCATION/etc/globus-devel-env.sh

 $ source $GLOBUS_LOCATION/etc/globus-devel-env.csh

Once the globus-devel-env is executed successfully run the Java program, for example:

On Windows:

 > java -DGLOBUS_LOCATION=%GLOBUS_LOCATION% foo.MyClass

On Unix/Linux:

 $ java -DGLOBUS_LOCATION=$GLOBUS_LOCATION foo.MyClass

Note: Passing -DGLOBUS_LOCATION is not necessary but will enable the client to execute from any directory.

Using bootstrap

Sometimes the above method might fail if the CLASSPATH environment variable is too long for the OS to handle. With the bootstrap method, a bootstrap code is executed first which sets the classpath programatically and then invokes the specified Java program.
To invoke a Java program on Windows through bootstrap execute:

 > java -cp %GLOBUS_LOCATION%\lib\bootstrap.jar -DGLOBUS_LOCATION=%GLOBUS_LOCATION% \
       org.globus.bootstrap.Bootstrap foo.MyClass

On Unix/Linux machines execute:

 $ java -cp $GLOBUS_LOCATION/lib/bootstrap.jar -DGLOBUS_LOCATION=$GLOBUS_LOCATION \
       org.globus.bootstrap.Bootstrap foo.MyClass

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.