GT 3.9.4 Java WS Core: User's Guide

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

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

globus-start-container

Tool description

Starts a standalone container. By default a secure container is started on port 8433 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]
-help

Displays help information about the command.
-p <port>

Sets the port number for the container.
-quiet

Does not show a list of services at startup.
-nosec

Starts a non secure (HTTP) container.
-containerDesc <file>

Specifies a container security descriptor file.
-profile <name>

Specifies a configuration profile name for the container.

globus-stop-container

Tool description

Stops a standalone container. By default this command will attempt to stop a container running on localhost:8433 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

Tool description

Destroys a resource.

Command syntax

wsrf-destroy [options]

Example:

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

wsrf-set-termination-time

Tool description

Sets a termination time of a resource.

Command syntax

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

Tool description

Queries resource property document of a resource. By default, a simple XPath query is assumed that returns the entire resource property document.

Command syntax

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

Example:

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

wsrf-get-property

Tool description

Gets a single resource property from a resource.

Command syntax

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

Tool description

Gets multiple resource properties from a resource.

Command syntax

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

Tool description

Inserts a property into the resource property document of a resource.

Command syntax

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

Tool description

Updates property value in the resource property document of a resource.

Command syntax

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

Tool description

Deletes a resource property from the resource property document of a resource.

Command syntax

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

Tool description

Gets the current message associated with the specified topic.

Command syntax

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

Tool description

Pauses a subscription (notifications on that subscription will not be sent out until it is resumed)

Command syntax

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

Tool description

Resumes a subscription (notifications on that subscription will be sent out again)

Command syntax

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

Tool description

Subscribes to a topic.

Command syntax

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:

-r, --resDescFile <file>

Specifies a file containing a resource security descriptor for the notification consumer resource.
-b, --subEpr <file>

Specifies a file to which the subscription resource EPR will be saved.

Example:

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

ant deployGar

Tool description

Deploys a GAR file (Ant task).

Command syntax

ant -f $GLOBUS_LOCATION/share/globus_wsrf_common/build-packages.xml deployGar \
    -Dgar.name=<gar.name> [-Dprofile=<profile>]

The <gar.name> is an absolute path to the GAR file to be deployed. The optional -Dprofile argument specifies the profile name under which the configuration files in the GAR will be deployed. Please see Configuration Profiles for details.

Example:

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

ant undeployGar

Tool description

Undeploys a GAR file (Ant task).

Command syntax

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

The <gar.id> is the base name of the GAR file without the .gar extension to undeploy. For example if the GAR file is "foo.gar", then the GAR id is "foo".
The directory names under the $GLOBUS_LOCATION/etc/globus_packages/ are the GAR ids of the undeployable items.

Example:

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

Common Command syntax

Some clients share the same command line options:

-h, --help

Displays help information about the command.
-d, --debug

Enables debug mode. For example, full stack traces of errors will be displayed.
-e, --eprFile <file>

Specifies an XML file that contains the endpoint reference
-s, --service <url>

Specifies the service URL.
-k, --key <name value>

Specifies the resource key. The name is the QName of the resource key in the string form: {namespaceURI}localPart, while the value is the simple value of the key. For complex keys, use the --eprFile option. Example: 

-k {http://www.globus.org}MyKey 123
-f, --descriptor <file>

Specifies a client security descriptor. Overrides all other security settings.
-a, --anonymous

Enables anonymous authentication. Only supported with transport security or GSI Secure Conversation authentication mechanism.
-g, --delegation <mode>

Enables delegation. mode can be either 'limited' or 'full'. Only supported with GSI Secure Conversation authentication mechanism.
-l, --contextLifetime <value>

Sets the lifetime of the client security context. value is in milliseconds. Only supported with GSI Secure Conversation authentication mechanism.
-m, --securityMech <type>

Specifies the authentication mechanism. type can be 'msg' for GSI Secure Message, or 'conv' for GSI Secure Conversation.
-c, --serverCertificate <file>

Specifies the server's certificate file used for encryption. Only needed for GSI Secure Message authentication mechanism.
-p, --protection <type>

Specifies the protection level. type can be 'sig' for signature or 'enc' for encryption.
-z, --authorization <type>

Specifies authorization type. type can be 'self', 'host', or 'none'.

Graphical user interfaces

Overview of the purpose and functionality of the GUI

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

Troubleshooting

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.