GT 4.2 Guide to Public Interfaces: Java WS Core


Table of Contents

APIs
1. Programming Model Overview
2. Component API
Services and WSDL
Configuring
1. Configuration overview
2. Syntax of the interface:
3. Configuring an /etc/init.d entry for the standalone container
Environment variable interface
1. Environmental variables for Java WS Core
Java WS Core Commands
globus-start-container - Starts standalone container
globus-stop-container - Stops standalone container
globus-start-container-detached - Starts standalone container detached from controlling TTY
globus-stop-container-detached - Stops standalone container detached from controlling TTY
wsrf-destroy - Destroys a resource
wsrf-set-termination-time - Sets termination time of a resource
wsrf-query - Performs query on a resource property document
wsrf-get-property - Gets values of a single resource property
wsrf-get-properties - Gets values of multiple resource properties
wsrf-insert-property - Inserts values into a resource property
wsrf-update-property - Updates value of a resource property
wsrf-delete-property - Deletes a resource property
wsn-get-current-message - Gets a current message associated with a topic
wsn-pause-subscription - Pauses a subscription
wsn-resume-subscription - Resumes a subscription
wsn-subscribe - Subscribes to a topic
globus-deploy-gar - Deploys a GAR file (locally)
globus-undeploy-gar - Undeploys a GAR file (locally)
globus-check-environment - Displays component version information and validates JVM version.
globus-check-remote-environment - Displays remote component version information.
globus-update-client-config - Merges client-config.wsdd files from deployed modules into the global client-config.wsdd configuration file
globus-validate-descriptors - Validate configuration files of all services
globus-reload-container - Reinitializes standalone container
globus-remote-undeploy-gar - Undeploys a GAR file (remotely)
globus-remote-deploy-gar - Deploys a GAR file (remotely)
ws-enumerate-start - Starts an enumeration
ws-enumerate - Retrieves enumeration data
ws-enumerate-end - Stops an enumeration
globus-xpath-query - Performs XPath query on a resource property document
Common Java Client Options - list of common options across commands
A. Errors
Glossary

APIs

1. Programming Model Overview

There are two main parts to the Java WS Core programming model: the service and the resource. The service performs the business logic on the resource, and the resource represents the managed state.

The web service is just a stateless POJO (Plain Old Java Object) that discovers the resource associated with the request and then performs operations on that resource.

The resources are managed and discovered via ResourceHome implementations. The ResourceHome implementations can also be responsible for creating new resources, performing operations on a set of resources at a time, etc.

The ResourceHome implementations are configured in JNDI and are associated with a particular web service. JNDI is a central transient registry that is mainly used for discovery of ResourceHome implementations but it can be used to store and retrieve arbitrary information.

The web services are configured in the Web Services Deployment Descriptor (WSDD).

WSDL in document/literal style is assumed as a starting point for writing a service. A number of generic interfaces are defined so that custom implementations of these interfaces can be used instead of the default implementations included in the Java WS Core. No special base classes are required for a web service or resource implementation. However, the resource object at minimal must implement the org.globus.wsrf.Resource interface (it defines no operations; it is used just as a marker interface). The service developer can pick and choose which other resource interfaces the resource object should implement to tailor the implementation to his/her needs.

2. Component API

  • Stable API:

    • org.globus.wsrf.Resource
    • org.globus.wsrf.ResourceKey
    • org.globus.wsrf.ResourceProperty
    • org.globus.wsrf.ResourcePropertyMetaData
    • org.globus.wsrf.ResourcePropertySet
    • org.globus.wsrf.ResourceProperties
    • org.globus.wsrf.ResourceHome
    • org.globus.wsrf.ResourceLifetime
    • org.globus.wsrf.ResourceIdentifier
    • org.globus.wsrf.ResourceContext
    • org.globus.wsrf.RemoveCallback
    • org.globus.wsrf.PersistentCallback
    • org.globus.wsrf.Subscription
    • org.globus.wsrf.Topic
    • org.globus.wsrf.TopicList
    • org.globus.wsrf.TopicListMetaData
    • org.globus.wsrf.TopicAccessor
    • org.globus.wsrf.TopicListener
    • org.globus.wsrf.TopicListenerList
  • Less stable API:

    • org.globus.wsrf.NotificationConsumerCallbackManager
    • org.globus.wsrf.NotificationConsumerManager
    • org.globus.wsrf.NotifyCallback
    • org.globus.wsrf.encoding.ObjectSerializer
    • org.globus.wsrf.encoding.ObjectDeserializer
    • org.globus.wsrf.impl.SimpleResourceKey
    • org.globus.wsrf.impl.BaseResourceProperty
    • org.globus.wsrf.impl.ReflectionResourceProperty
    • org.globus.wsrf.impl.SimpleResourceProperty
    • org.globus.wsrf.impl.SimpleResourcePropertyMetaData
    • org.globus.wsrf.impl.SimpleResourcePropertySet
    • org.globus.wsrf.impl.ResourceContextImpl
    • org.globus.wsrf.impl.ResourceHomeImpl
    • org.globus.wsrf.impl.SingletonResourceHome
    • org.globus.wsrf.impl.ServiceResourceHome
    • org.globus.wsrf.impl.ResourcePropertyTopic
    • org.globus.wsrf.impl.SimpleTopic
    • org.globus.wsrf.impl.SimpleTopicList
    • org.globus.wsrf.impl.SimpleTopicListMetaData
    • org.globus.wsrf.query.QueryEngine
    • org.globus.wsrf.query.ExpressionEvaluator
    • org.globus.wsrf.topicexpression.TopicExpressionEngine
    • org.globus.wsrf.topicexpression.TopicExpressionEvaluator
    • org.globus.wsrf.utils.FaultHelper
    • org.globus.wsrf.utils.XmlUtils
    • org.globus.wsrf.utils.AddressingUtils
    • org.globus.wsrf.container.ServiceHost

The complete Java WS Core API.

Configuring

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 supports security might also have the security-config.xml (security deployment descriptor) file. Please see Java WS A&A Security Descriptor Framework for details.

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

2. Syntax of the interface:

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

Table 2. Standalone/embedded container-specific configuration parameters

NameValueDescriptionComments
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
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 set to the web application's name. Optional

2.2. Container Performance Tuning

While there aren't a large number of parameters which you can use to tune the container for performance, configuring your container in a manner appropriate to the needs of your application can yield significant benefits. Having said that, these are very general guidelines which may not apply to every situation. In addition, many commonly used services have configuration recommendations. It is strongly suggested that you check the performance tuning guide for your particular service before attempting to change these settings on your own.

2.2.1. JVM Parameters

The first major parameters you can adjust are not strictly container parameters, but tweaking the parameters of the JVM in which your container is running can provide significant performance benefits. Each implementation of the JVM has it's own set of parameters which can be modified, however, all JVM's have parameters to change the heap memory usage. By default, the JVM claims 64 MB from the operating system. This will be too small for any real deployment of the container. For a service such as GRAM, which expects to process large numbers of jobs which may exist for an extended period of time, we recommend specifying at least 1024 MB for the maximum heap memory. In addition, you should specify the minimum amount of heap memory your container will use. To set these values for the container, execute this command:

GLOBUS_OPTIONS="-Xms256M -Xmx1024M"
                    

This will tell the virtual machine to claim 256 MB as the minimum heap size and 1024 MB as the maximum heap size. As a general rule of thumb, if you specify more memory, your performance will improve. Of course, this is only the case if your machine has sufficient memory.

In addition, certain JVM implementations have additional parameters which can improve performance. The most notable is in the Sun JVM implementation. Specifying the process to be -server allows the JVM to run in "server" mode. The JVM will typically perform better on CPU intensive tasks (like most GT containers) when in "server" mode. To set this value, add -server to your GLOBUS_OPTIONS variable:

GLOBUS_OPTIONS="$GLOBUS_OPTIONS -server"
                    

2.2.2. Container Parameters

The Container parameters also play a significant role in the performance of your container. The main parameters relate to threads.

Setting up threads for a container is as much an art as a science, so here are some guidelines for configuring your container. The number of threads determines how many concurrent requests your container can service. However, just setting this number to a high value is not a good solution, because each thread takes resources. Ideally, you would want to set this number to be equal to the number of processors your machine has, because that would mean that each thread is being serviced all the time (of course, that is assuming that your computer isn't doing anything else, which is never. That's why this is "ideally"). However, unless you are getting only 1 or 2 requests at a time, this will prevent requests from being processed in a timely manner. So, when configuring this value, you will generally want to find a balance between the number of requests you expect to receive and the resources available on the machine. You should usually try to set this value as low as you can. Having said that, if you expect a large number of requests and those requests are either completed quickly or do the work in a separate thread, the default value of 20 maximum threads is usually sufficient. However, in that scenario, you will probably want to set the minimum number of threads to 20 as well. That way you won't take time starting and stopping threads.

So, as a basic rule of thumb, the default thread configuration will be sufficient unless, you a) expect to receive a large number of concurrent requests which can be processed quickly (in which case you should make the minimum and maximum number of threads equal) or b) you will have a low number of concurrent requests that can be processed quickly (in which case, you might consider reducing the maximum number of threads) or c) you have will receive a large number of concurrent requests which take a long time to process (in which case you should increase the maximum number of threads). The third situation listed is definitely not ideal, because it will put a heavy load on the server with no real way to balance it. In this scenario, you should consider passing the processing from your service to the WorkManager. The specific configuration parameters are listed below.

Table 3. Container Thread Parameters

NameValueDescriptionComments
containerThreads <int>This parameter controls the initial thread pool size for the container. If not set, 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

The default Thread settings are as follows:

Table 4. Default container thread pool settings

TypeMin. threadsMax. threads
standalone 220
embedded 13

2.2.3. Client Parameters

The connection timeout parameter in the client can also play a role in tuning performance. This is a new feature in the 4.2 release. It allows a client to keep the http connection open to the server across multiple requests. Setting this to a higher value will mean the same connection is used for longer. This can positively impact performance by eliminating some of the overhead involved in connecting to the server. However, this is not a magic bullet, so don't expect to see huge improvements from this parameter. If you have a long running task on the server, you will probably see modest improvement in the time required to actually submit the request to the server, but the latency in your request will likely make that mostly moot. Also, if you keep a connection open, you will be limiting the ability of other clients to connect. So this is a parameter that should be changed carefully, depending on your particular circumstances.

2.3. Service Configuration

2.3.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 5. 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 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 6. Java WS Core Parameters

Name Value Description Comments
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 Section 1.1, “How can I force my service to initialize when the container starts?” 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 the 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.3.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 Section 7, “JNDI, Resources and Objects” 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.3.2.1. ResourceHomeImpl

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

Table 7. ResourceHomeImpl parameters

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 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.3.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, for example:

<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>
        <parameter>
            <name>maxSize</name>
            <value>1000</value>
        </parameter>
    </resourceParams>
</resource>
                        

The "timeout" parameter (in ms) is used to specify the idle time of the resource object before it is removed from the cache. Also, the "maxSize" parameter can be used to specify the maximum size of the cache. By default the cache is configured without any size limit and 5 minutes timeout.

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. Also, the same cache resource can be reused in different services but usually one cache per service should be configured.

2.3.2.2. ServiceResourceHome

This implementation does not accept any special parameters.

2.4. Usage Statistics Configuration

Java WS Core container and other GT services are configured to send out usage statistics. Please see the Usage Statistics section in the Java WS Core Admin Guide 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.5. 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. Configuring an /etc/init.d entry for the standalone container

To create an /etc/init.d entry for the standalone container do the following steps:

  1. As root create /etc/init.d/gt4container script with the following contents:

    ACCOUNT=globus GLOBUS_LOCATION=<globusLocation>
    INIT=$GLOBUS_LOCATION/etc/init.d/globus-ws-java-container su $ACCOUNT -c "$INIT $*"
                    
  2. Set executable permissions on the /etc/init.d/gt4container script and register it with the init.d system:

    $ chmod +x /etc/init.d/gt4container $ /sbin/chkconfig -a gt4container

    After this step the container should start automatically after the next reboot. Make sure the container is configured with a global security descriptor that explicitly points to long term credentials.

To start the container by hand run:

$ /etc/init.d/gt4container start

To stop the container by hand run:

$ /etc/init.d/gt4container stop

Environment variable interface

1. Environmental variables for Java WS Core

Table 1. Globus standard environment variables

Name Value Description Comments
GLOBUS_LOCATION<path>The <path> is the root location of the Java WS Core installation. Must be an absolute path. Required
GLOBUS_TCP_PORT_RANGE<min,max>The <min,max> is the minimum and maximum port range for TCP server sockets (useful for systems behind firewalls). For example, if set, the notification sink on the client will be started within that port range. Optional
GLOBUS_TCP_SOURCE_PORT_RANGE<min,max>The <min,max> is the minimum and maximum port range for TCP outgoing sockets (useful for systems behind firewalls). Optional
GLOBUS_UDP_SOURCE_PORT_RANGE<min,max>The <min,max> is the minimum and maximum port range for UDP outgoing sockets (useful for systems behind firewalls). Optional
GLOBUS_HOSTNAME<host>The <host> is either a hostname or ip address. The host ip address under which the container and services will be exposed. Optional

Table 2. Launch script specific environment variables

Name Value Description Comments
GLOBUS_OPTIONS<arguments> The <arguments> are arbitrary arguments that can be passed to the JVM. See below for a detailed list of supported options.Optional
JAVA_HOME<path>The <path> is the root location of the JVM installation. If set, the JVM from that installation will be used. Otherwise, the first one found in path will be used. Optional
CLASSPATH<classpath>This environment property is ignored by launch scripts. Ignored

Table 3. Options supported by the GLOBUS_OPTIONS environment property

Name Value Description
-Dorg.globus.wsrf.proxy.portintThis property specifies the port number of the proxy server. The proxy server must run on the same machine as the container. This setting will cause the service address to have the port of the proxy instead of the container (only applies to code that uses the ServiceHost or AddressingUtils API.
-Dorg.globus.wsrf.container.server.idstringThis property 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 will store the persistent resources under the ~/.globus/persisted/<ip>-<containerPort> directory. While in Tomcat the ~/.globus/persisted/<ip>-<webApplicationName> directory will be used instead. This property overwrites the default server id and therefore indirectly controls which storage directory is used by the container. If set, the container will store the persisted resources under ~/.globus/persisted/<server.id>/ instead. Note, that if somehow multiple containers running as the same user on the same machine end up with the same server id / persistent directory they might overwrite each other's persistent data.
-Dorg.globus.wsrf.container.persistence.dirdirectoryThis property specifies the base directory that will be used for storing the persistent resources. This property overwrites the default (~/.globus/persisted/) base directory assumed by the container.

Any JVM options can also be passed using the GLOBUS_OPTIONS environment property.

Java WS Core Commands


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

Table of Contents

globus-start-container - Starts standalone container
globus-stop-container - Stops standalone container
globus-start-container-detached - Starts standalone container detached from controlling TTY
globus-stop-container-detached - Stops standalone container detached from controlling TTY
wsrf-destroy - Destroys a resource
wsrf-set-termination-time - Sets termination time of a resource
wsrf-query - Performs query on a resource property document
wsrf-get-property - Gets values of a single resource property
wsrf-get-properties - Gets values of multiple resource properties
wsrf-insert-property - Inserts values into a resource property
wsrf-update-property - Updates value of a resource property
wsrf-delete-property - Deletes a resource property
wsn-get-current-message - Gets a current message associated with a topic
wsn-pause-subscription - Pauses a subscription
wsn-resume-subscription - Resumes a subscription
wsn-subscribe - Subscribes to a topic
globus-deploy-gar - Deploys a GAR file (locally)
globus-undeploy-gar - Undeploys a GAR file (locally)
globus-check-environment - Displays component version information and validates JVM version.
globus-check-remote-environment - Displays remote component version information.
globus-update-client-config - Merges client-config.wsdd files from deployed modules into the global client-config.wsdd configuration file
globus-validate-descriptors - Validate configuration files of all services
globus-reload-container - Reinitializes standalone container
globus-remote-undeploy-gar - Undeploys a GAR file (remotely)
globus-remote-deploy-gar - Deploys a GAR file (remotely)
ws-enumerate-start - Starts an enumeration
ws-enumerate - Retrieves enumeration data
ws-enumerate-end - Stops an enumeration
globus-xpath-query - Performs XPath query on a resource property document
Common Java Client Options - list of common options across commands

Name

globus-start-container — Starts standalone container

Synopsis

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]

Table 11. Options

-help

Displays help information about the command.

-p <port>

Sets the port number for the container.

-i <address>

Binds container to the specified network address.

-quiet

Does not show a list of services at startup.

-debug

Enables debug mode.

-nosec

Starts a non secure (HTTP) container. Please note that this option only disables transport security. Message security can still be used.

-containerDesc <file>

Specifies a container security descriptor file.

-profile <name>

Specifies a configuration profile name for the container.

Name

globus-stop-container — Stops standalone container

Synopsis

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 it 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']

Table 12. Common 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 WS-Addressing 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 the GSI Secure Conversation authentication mechanism.

-g, --delegation <mode>

Enables delegation. mode can be either 'limited' or 'full'. Only supported with the GSI Secure Conversation authentication mechanism.

-l, --contextLifetime <value>

Sets the lifetime of the client security context. value is in milliseconds. Only supported with the 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 the GSI Secure Message authentication mechanism.

-p, --protection <type>

Specifies the protection level. type can be 'sig' for signature or 'enc' for encryption.

-x, --proxyFilename <value>

Sets the proxy file to use as client credential.

-z, --authorization <type>

Specifies authorization type. type can be 'self', 'host', 'none', or a string specifying the expected identity of the remote party.

-t, --timeout <timeout>

Specifies client timeout (in seconds). The client will wait maximum of the timeout value for a response from the server before returning an error. By default the timeout value is 10 minutes.

Table 13. Shutdown options

'soft' This option lets the threads die naturally.
'hard' This option forces an immediate JVM shutdown.

Example:

 $ globus-stop-container soft

Please see the troubleshooting section if you are having problems with globus-stop-container.

Name

globus-start-container-detached — Starts standalone container detached from controlling TTY

Synopsis

globus-start-container-detached

Tool description

Starts a standalone container detached from the controlling TTY. This can be useful for long running containers or when started from init.d scripts. Container log goes to $GLOBUS_LOCATION/var/container.log and a PID file is written to $GLOBUS_LOCATION/var/container.pid. globus-start-container-detached is just a wrapper around globus-start-container so see globus-start-container for more information and options.

[Note]Note

Note that this tool is only available after doing a full Globus install. It is not available in Java WS Core only installs.

Command syntax

 globus-start-container-detached [options] | [arguments to container]

Table 14. Options

-logfile <file>

Specifies an alternate container log file.

-append

Do not overwrite the existing log file.

-pidfile <file>

Specifies an alternate PID file location.

Name

globus-stop-container-detached — Stops standalone container detached from controlling TTY

Synopsis

globus-stop-container-detached

Tool description

Stops a standalone container detached from the controlling TTY. $GLOBUS_LOCATION/var/container.pid is used to find the PID of the running container and signals are sent to stop the container.

[Note]Note

Note that this tool is only available after doing a full Globus install. It is not available in Java WS Core only installs.

Command syntax

 globus-stop-container-detached [options]

Table 15. Options

-pidfile <file>

Specifies an alternate PID file location.

Name

wsrf-destroy — Destroys a resource

Synopsis

wsrf-destroy

Tool description

Destroys a resource.

Command syntax

wsrf-destroy [options]

Table 16. Common 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 WS-Addressing 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 the GSI Secure Conversation authentication mechanism.

-g, --delegation <mode>

Enables delegation. mode can be either 'limited' or 'full'. Only supported with the GSI Secure Conversation authentication mechanism.

-l, --contextLifetime <value>

Sets the lifetime of the client security context. value is in milliseconds. Only supported with the 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 the GSI Secure Message authentication mechanism.

-p, --protection <type>

Specifies the protection level. type can be 'sig' for signature or 'enc' for encryption.

-x, --proxyFilename <value>

Sets the proxy file to use as client credential.

-z, --authorization <type>

Specifies authorization type. type can be 'self', 'host', 'none', or a string specifying the expected identity of the remote party.

-t, --timeout <timeout>

Specifies client timeout (in seconds). The client will wait maximum of the timeout value for a response from the server before returning an error. By default the timeout value is 10 minutes.

Example:

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

Name

wsrf-set-termination-time — Sets termination time of a resource

Synopsis

wsrf-set-termination-time

Tool description

Sets a termination time of a resource.

Command syntax

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

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

Table 17. Command-specific options

-u, --utc

Display time in UTC.

Table 18. Common 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 WS-Addressing 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 the GSI Secure Conversation authentication mechanism.

-g, --delegation <mode>

Enables delegation. mode can be either 'limited' or 'full'. Only supported with the GSI Secure Conversation authentication mechanism.

-l, --contextLifetime <value>

Sets the lifetime of the client security context. value is in milliseconds. Only supported with the 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 the GSI Secure Message authentication mechanism.

-p, --protection <type>

Specifies the protection level. type can be 'sig' for signature or 'enc' for encryption.

-x, --proxyFilename <value>

Sets the proxy file to use as client credential.

-z, --authorization <type>

Specifies authorization type. type can be 'self', 'host', 'none', or a string specifying the expected identity of the remote party.

-t, --timeout <timeout>

Specifies client timeout (in seconds). The client will wait maximum of the timeout value for a response from the server before returning an error. By default the timeout value is 10 minutes.

Example:

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

Name

wsrf-query — Performs query on a resource property document

Synopsis

wsrf-query

Tool description

Queries the 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]

Table 19. Common 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 WS-Addressing 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 the GSI Secure Conversation authentication mechanism.

-g, --delegation <mode>

Enables delegation. mode can be either 'limited' or 'full'. Only supported with the GSI Secure Conversation authentication mechanism.

-l, --contextLifetime <value>

Sets the lifetime of the client security context. value is in milliseconds. Only supported with the 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 the GSI Secure Message authentication mechanism.

-p, --protection <type>

Specifies the protection level. type can be 'sig' for signature or 'enc' for encryption.

-x, --proxyFilename <value>

Sets the proxy file to use as client credential.

-z, --authorization <type>

Specifies authorization type. type can be 'self', 'host', 'none', or a string specifying the expected identity of the remote party.

-t, --timeout <timeout>

Specifies client timeout (in seconds). The client will wait maximum of the timeout value for a response from the server before returning an error. By default the timeout value is 10 minutes.

Examples:

 $ wsrf-query -s https://127.0.0.1:8443/wsrf/services/DefaultIndexService \
    "count(//*[local-name()='Entry'])"

 $ wsrf-query -s https://127.0.0.1:8443/wsrf/services/DefaultIndexService \
    "number(//*[local-name()='GLUECE']/glue:ComputingElement/glue:State/@glue:FreeCPUs)=0"

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

Name

wsrf-get-property — Gets values of a single resource property

Synopsis

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.

Table 20. Common 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 WS-Addressing 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 the GSI Secure Conversation authentication mechanism.

-g, --delegation <mode>

Enables delegation. mode can be either 'limited' or 'full'. Only supported with the GSI Secure Conversation authentication mechanism.

-l, --contextLifetime <value>

Sets the lifetime of the client security context. value is in milliseconds. Only supported with the 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 the GSI Secure Message authentication mechanism.

-p, --protection <type>

Specifies the protection level. type can be 'sig' for signature or 'enc' for encryption.

-x, --proxyFilename <value>

Sets the proxy file to use as client credential.

-z, --authorization <type>

Specifies authorization type. type can be 'self', 'host', 'none', or a string specifying the expected identity of the remote party.

-t, --timeout <timeout>

Specifies client timeout (in seconds). The client will wait maximum of the timeout value for a response from the server before returning an error. By default the timeout value is 10 minutes.

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"

Name

wsrf-get-properties — Gets values of multiple resource properties

Synopsis

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.

Table 21. Common 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 WS-Addressing 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 the GSI Secure Conversation authentication mechanism.

-g, --delegation <mode>

Enables delegation. mode can be either 'limited' or 'full'. Only supported with the GSI Secure Conversation authentication mechanism.

-l, --contextLifetime <value>

Sets the lifetime of the client security context. value is in milliseconds. Only supported with the 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 the GSI Secure Message authentication mechanism.

-p, --protection <type>

Specifies the protection level. type can be 'sig' for signature or 'enc' for encryption.

-x, --proxyFilename <value>

Sets the proxy file to use as client credential.

-z, --authorization <type>

Specifies authorization type. type can be 'self', 'host', 'none', or a string specifying the expected identity of the remote party.

-t, --timeout <timeout>

Specifies client timeout (in seconds). The client will wait maximum of the timeout value for a response from the server before returning an error. By default the timeout value is 10 minutes.

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"

Name

wsrf-insert-property — Inserts values into a resource property

Synopsis

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.

Table 22. Common 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 WS-Addressing 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 the GSI Secure Conversation authentication mechanism.

-g, --delegation <mode>

Enables delegation. mode can be either 'limited' or 'full'. Only supported with the GSI Secure Conversation authentication mechanism.

-l, --contextLifetime <value>

Sets the lifetime of the client security context. value is in milliseconds. Only supported with the 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 the GSI Secure Message authentication mechanism.

-p, --protection <type>

Specifies the protection level. type can be 'sig' for signature or 'enc' for encryption.

-x, --proxyFilename <value>

Sets the proxy file to use as client credential.

-z, --authorization <type>

Specifies authorization type. type can be 'self', 'host', 'none', or a string specifying the expected identity of the remote party.

-t, --timeout <timeout>

Specifies client timeout (in seconds). The client will wait maximum of the timeout value for a response from the server before returning an error. By default the timeout value is 10 minutes.

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

Name

wsrf-update-property — Updates value of a resource property

Synopsis

wsrf-update-property

Tool description

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

Table 23. Common 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 WS-Addressing 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 the GSI Secure Conversation authentication mechanism.

-g, --delegation <mode>

Enables delegation. mode can be either 'limited' or 'full'. Only supported with the GSI Secure Conversation authentication mechanism.

-l, --contextLifetime <value>

Sets the lifetime of the client security context. value is in milliseconds. Only supported with the 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 the GSI Secure Message authentication mechanism.

-p, --protection <type>

Specifies the protection level. type can be 'sig' for signature or 'enc' for encryption.

-x, --proxyFilename <value>

Sets the proxy file to use as client credential.

-z, --authorization <type>

Specifies authorization type. type can be 'self', 'host', 'none', or a string specifying the expected identity of the remote party.

-t, --timeout <timeout>

Specifies client timeout (in seconds). The client will wait maximum of the timeout value for a response from the server before returning an error. By default the timeout value is 10 minutes.

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

Name

wsrf-delete-property — Deletes a resource property

Synopsis

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.

Table 24. Common 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 WS-Addressing 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 the GSI Secure Conversation authentication mechanism.

-g, --delegation <mode>

Enables delegation. mode can be either 'limited' or 'full'. Only supported with the GSI Secure Conversation authentication mechanism.

-l, --contextLifetime <value>

Sets the lifetime of the client security context. value is in milliseconds. Only supported with the 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 the GSI Secure Message authentication mechanism.

-p, --protection <type>

Specifies the protection level. type can be 'sig' for signature or 'enc' for encryption.

-x, --proxyFilename <value>

Sets the proxy file to use as client credential.

-z, --authorization <type>

Specifies authorization type. type can be 'self', 'host', 'none', or a string specifying the expected identity of the remote party.

-t, --timeout <timeout>

Specifies client timeout (in seconds). The client will wait maximum of the timeout value for a response from the server before returning an error. By default the timeout value is 10 minutes.

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"

Name

wsn-get-current-message — Gets a current message associated with a topic

Synopsis

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.

Table 25. Common 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 WS-Addressing 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 the GSI Secure Conversation authentication mechanism.

-g, --delegation <mode>

Enables delegation. mode can be either 'limited' or 'full'. Only supported with the GSI Secure Conversation authentication mechanism.

-l, --contextLifetime <value>

Sets the lifetime of the client security context. value is in milliseconds. Only supported with the 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 the GSI Secure Message authentication mechanism.

-p, --protection <type>

Specifies the protection level. type can be 'sig' for signature or 'enc' for encryption.

-x, --proxyFilename <value>

Sets the proxy file to use as client credential.

-z, --authorization <type>

Specifies authorization type. type can be 'self', 'host', 'none', or a string specifying the expected identity of the remote party.

-t, --timeout <timeout>

Specifies client timeout (in seconds). The client will wait maximum of the timeout value for a response from the server before returning an error. By default the timeout value is 10 minutes.

Example:

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

Name

wsn-pause-subscription — Pauses a subscription

Synopsis

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]

Table 26. Common 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 WS-Addressing 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 the GSI Secure Conversation authentication mechanism.

-g, --delegation <mode>

Enables delegation. mode can be either 'limited' or 'full'. Only supported with the GSI Secure Conversation authentication mechanism.

-l, --contextLifetime <value>

Sets the lifetime of the client security context. value is in milliseconds. Only supported with the 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 the GSI Secure Message authentication mechanism.

-p, --protection <type>

Specifies the protection level. type can be 'sig' for signature or 'enc' for encryption.

-x, --proxyFilename <value>

Sets the proxy file to use as client credential.

-z, --authorization <type>

Specifies authorization type. type can be 'self', 'host', 'none', or a string specifying the expected identity of the remote party.

-t, --timeout <timeout>

Specifies client timeout (in seconds). The client will wait maximum of the timeout value for a response from the server before returning an error. By default the timeout value is 10 minutes.

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"

Name

wsn-resume-subscription — Resumes a subscription

Synopsis

wsn-resume-subscription

Tool description

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

Command syntax

wsn-resume-subscription [options]

Table 27. Common 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 WS-Addressing 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 the GSI Secure Conversation authentication mechanism.

-g, --delegation <mode>

Enables delegation. mode can be either 'limited' or 'full'. Only supported with the GSI Secure Conversation authentication mechanism.

-l, --contextLifetime <value>

Sets the lifetime of the client security context. value is in milliseconds. Only supported with the 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 the GSI Secure Message authentication mechanism.

-p, --protection <type>

Specifies the protection level. type can be 'sig' for signature or 'enc' for encryption.

-x, --proxyFilename <value>

Sets the proxy file to use as client credential.

-z, --authorization <type>

Specifies authorization type. type can be 'self', 'host', 'none', or a string specifying the expected identity of the remote party.

-t, --timeout <timeout>

Specifies client timeout (in seconds). The client will wait maximum of the timeout value for a response from the server before returning an error. By default the timeout value is 10 minutes.

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"

Name

wsn-subscribe — Subscribes to a topic

Synopsis

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:

Table 28. Command-specific 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.

Table 29. Common 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 WS-Addressing 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 the GSI Secure Conversation authentication mechanism.

-g, --delegation <mode>

Enables delegation. mode can be either 'limited' or 'full'. Only supported with the GSI Secure Conversation authentication mechanism.

-l, --contextLifetime <value>

Sets the lifetime of the client security context. value is in milliseconds. Only supported with the 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 the GSI Secure Message authentication mechanism.

-p, --protection <type>

Specifies the protection level. type can be 'sig' for signature or 'enc' for encryption.

-x, --proxyFilename <value>

Sets the proxy file to use as client credential.

-z, --authorization <type>

Specifies authorization type. type can be 'self', 'host', 'none', or a string specifying the expected identity of the remote party.

-t, --timeout <timeout>

Specifies client timeout (in seconds). The client will wait maximum of the timeout value for a response from the server before returning an error. By default the timeout value is 10 minutes.

Example:

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

Name

globus-deploy-gar — Deploys a GAR file (locally)

Synopsis

globus-deploy-gar

Tool description

Deploys a GAR file (locally) into Java WS Core or Apache Tomcat container.

Command syntax

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

The <gar.file> is the path to the GAR file to be deployed.

Table 30. Options

-help

Displays help information about the command.

-debug

Enables debug mode.

-verbose

Enables verbose mode.

-backup

Creates backup of existing configuration files.

-overwrite

Overwrite existing deployment.

-profile <name>

Specifies the profile name under which the configuration files in the GAR will be deployed. Please see "Configuration Profiles" under Configuring Java WS Core for details.

-tomcat <dir>

Deploys a GAR file to Apache Tomcat. The <dir> argument must point to the Tomcat installation directory. Note: Java WS Core must be already deployed in Tomcat. Please see Deploying into Tomcat section for details.

-D<property>=<value>

Passes arbitrary property-value pairs. See below for the list of currently supported properties.

Table 31. Supported property-value pairs

-Dall.scripts=true

Causes Windows and Unix launcher scripts to be generated.

-DdoValidation=false

Turns off automatic validation of service configuration files.

[Note]Note

Since GT 4.2, globus-deploy-gar command will NOT overwrite the existing deployment unless -overwrite option is specified. It is recommended to undeploy the existing deployment first. The container must be off to deploy a GAR file.

Example I:

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

The above command will deploy the globus_wsrf_core_samples_counter.gar into Java WS Core installation directory. The above command invokes the deployGar task in the build-packages.xml Ant build file. 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 the -Dprofile Ant option. To enable back up of the existing configuration files add the -DcreateBackup=true Ant option. Make sure to use the absolute path name for the gar file when using Ant directly.

Example II:

 $ globus-deploy-gar -tomcat /soft/tomcat-5.5.20 \
    /tmp/gars/globus_wsrf_core_samples_counter.gar

The above command will deploy the globus_wsrf_core_samples_counter.gar into Apache Tomcat. The above command invokes the deployGar task in the tomcat-service.xml Ant build file. The above example is equivalent to running:

 $ ant -f $GLOBUS_LOCATION/share/globus_wsrf_common/tomcat/tomcat-service.xml deployGar \
    -Dgar.name=/tmp/gars/globus_wsrf_core_samples_counter.gar \ -Dtomcat.dir=/soft/tomcat-5.5.20

By default the GAR file will be deployed under the "wsrf" web application. To specify a different web application name use -Dwebapp.name=<name> option.

Name

globus-undeploy-gar — Undeploys a GAR file (locally)

Synopsis

globus-undeploy-gar

Tool description

Undeploys a GAR file (locally) from Java WS Core or Apache Tomcat container.

Command syntax

 globus-undeploy-gar [options] <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 $GLOBUS_LOCATION/etc/globus_packages/ are the GAR ids of the undeployable items.

Table 32. Options

-help

Displays help information about the command.

-debug

Enables debug mode.

-verbose

Enables verbose mode.

-tomcat <dir>

Undeploy a GAR file from Apache Tomcat. The <dir> argument must point to the Tomcat installation directory.

-D<property>=<value>

Passes arbitrary property-value pairs.

[Note]Note

The container must be off to undeploy a GAR file.

Example I:

 $ globus-undeploy-gar globus_wsrf_core_samples_counter

The above command will undeploy globus_wsrf_core_samples_counter GAR from Java WS Core installation directory. The above command invokes the undeployGar task in the build-packages.xml Ant build file. The above example is equivalent to running:

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

Example II:

 $ globus-undeploy-gar -tomcat /soft/tomcat-5.5.20 \ globus_wsrf_core_samples_counter

The above command will undeploy globus_wsrf_core_samples_counter GAR from Apache Tomcat. The above command invokes the undeployGar task in the tomcat-service.xml Ant build file. The above example is equivalent to running:

 $ ant -f $GLOBUS_LOCATION/share/globus_wsrf_common/tomcat/tomcat-service.xml undeployGar
    \ -Dgar.id=globus_wsrf_core_samples_counter \ -Dtomcat.dir=/soft/tomcat-5.5.20

By default the GAR file will be undeployed under the "wsrf" web application. To specify a different web application name use -Dwebapp.name=<name> option.

Name

globus-check-environment — Displays component version information and validates JVM version.

Synopsis

globus-check-environment

Tool description

Displays component version information and validates the JVM version. This tool is primarily used for debugging purposes.

Name

globus-check-remote-environment — Displays remote component version information.

Synopsis

globus-check-remote-environment

Tool description

Displays remote component version information.

Command syntax

 globus-check-environment [-help] -s endpoint -z authz

Table 33. Options

-help

Displays help information about the command.

-s endpoint

Remote endpoint to print vesion information about. It should be of the format protocol://host:port, example https://localhost:8443.

-z authz

Sets authorization, can be 'self', 'host', 'hostOrSelf' or 'none' or a string specifying the expected identity of the remote party. Defaults to no authorization.

Name

globus-update-client-config — Merges client-config.wsdd files from deployed modules into the global client-config.wsdd configuration file

Synopsis

globus-update-client-config

Tool description

Merges multiple client-config.wsdd files from deployed modules into the global configuration file. Scans each $GLOBUS_LOCATION/etc/<modulename>/client-config.wsdd and merges the contents into $GLOBUS_LOCATION/client-config.wsdd This tool is primarily intended for use by administrators and automation tools to facilitate the adding and removing of module specific type-mapping and/or other client-side configuration from the global client-config.wsdd file used by the Globus installation.

Command syntax

 globus-update-client-config [<filename>]

Table 34. Options

<filename>

Optional argument that specifies an alternate path to write the result client-config.wsdd file. By default, running the program with no arguments will write the file to $GLOBUS_LOCATION/client-config.wsdd

Name

globus-validate-descriptors — Validate configuration files of all services

Synopsis

globus-validate-descriptors

Tool description

Validates the Web Services Deployment Descriptor (.wsdd) files, JNDI configuration files (jndi-config.xml), and security descriptors for all services.

Command syntax

 globus-validate-descriptors [options]

Table 35. Options

-help

Displays help information about the command.

-debug

Enables debug mode.

-verbose

Enables verbose mode.

-D<property>=<value>

Passes arbitrary property-value pairs.

Name

globus-reload-container — Reinitializes standalone container

Synopsis

globus-reload-container

Tool description

Invokes the reload() operation on the DeployService running in the remote container. It tells the container to reinitialize all of its services, re-read its and service configuration files, etc. For example, the administrator can change the security descriptor of a service and then use the globus-reload-container command to force the container to load the updated configuration without restarting the container.

By default the DeployService is configured to perform self authorization and therefore the globus-reload-container must be executed with the same credentials as the container it 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).

[Note]Note

This command only works with the standalone container. Please see the Java WS Core Dynamic Deploy Design Document for more information.

Command syntax

globus-reload-container [options]

Table 36. Common 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 WS-Addressing 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 the GSI Secure Conversation authentication mechanism.

-g, --delegation <mode>

Enables delegation. mode can be either 'limited' or 'full'. Only supported with the GSI Secure Conversation authentication mechanism.

-l, --contextLifetime <value>

Sets the lifetime of the client security context. value is in milliseconds. Only supported with the 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 the GSI Secure Message authentication mechanism.

-p, --protection <type>

Specifies the protection level. type can be 'sig' for signature or 'enc' for encryption.

-x, --proxyFilename <value>

Sets the proxy file to use as client credential.

-z, --authorization <type>

Specifies authorization type. type can be 'self', 'host', 'none', or a string specifying the expected identity of the remote party.

-t, --timeout <timeout>

Specifies client timeout (in seconds). The client will wait maximum of the timeout value for a response from the server before returning an error. By default the timeout value is 10 minutes.

Example:

 $ globus-reload-container

Name

globus-remote-undeploy-gar — Undeploys a GAR file (remotely)

Synopsis

globus-remote-undeploy-gar

Tool description

The globus-remote-undeploy-gar command undeploys a GAR file remotely. It invokes the undeploy() operation on the DeployService running in the remote container. It works just like the globus-undeploy-gar command but the GAR file is undeployed remotely.

By default the DeployService is configured to perform self authorization and therefore the globus-remote-undeploy-gar must be executed with the same credentials as the container it 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).

[Note]Note

This command only works with the standalone container. Please see the Java WS Core Dynamic Deploy Design Document for more information.

Command syntax

globus-remote-undeploy-gar [options] <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".

Table 37. Common 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 WS-Addressing 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 the GSI Secure Conversation authentication mechanism.

-g, --delegation <mode>

Enables delegation. mode can be either 'limited' or 'full'. Only supported with the GSI Secure Conversation authentication mechanism.

-l, --contextLifetime <value>

Sets the lifetime of the client security context. value is in milliseconds. Only supported with the 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 the GSI Secure Message authentication mechanism.

-p, --protection <type>

Specifies the protection level. type can be 'sig' for signature or 'enc' for encryption.

-x, --proxyFilename <value>

Sets the proxy file to use as client credential.

-z, --authorization <type>

Specifies authorization type. type can be 'self', 'host', 'none', or a string specifying the expected identity of the remote party.

-t, --timeout <timeout>

Specifies client timeout (in seconds). The client will wait maximum of the timeout value for a response from the server before returning an error. By default the timeout value is 10 minutes.

Example:

 $ globus-remote-undeploy-gar globus_wsrf_core_samples_counter

To see what GAR files can be undeployed on the remote container run the following query on the DeployService, for example:

 $ wsrf-query -z hostSelf -s https://127.0.0.1:8443/wsrf/services/DeployService

Name

globus-remote-deploy-gar — Deploys a GAR file (remotely)

Synopsis

globus-remote-deploy-gar

Tool description

The globus-remote-deploy-gar command deploys a GAR file remotely. It first transfers the GAR file to the DeployService running in the remote container and then it deploys it using the deploy() operation of the service (the tool can also perform these two operations separately).

By default the DeployService is configured to perform self authorization and therefore the globus-remote-deploy-gar must be executed with the same credentials as the container it 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).

[Note]Note

This command only works with the standalone container. Please see the Java WS Core Dynamic Deploy Design Document for more information.

Command syntax

globus-remote-deploy-gar [options] <gar>

The <gar> can be either an URL or a file location. If a file location is passed to the tool, it will transfer the file to the service via SOAP with Attachments (the upload() function) using the MTOM format. If an URL is passed, the tool will call the download() function of the service, and let the service download the GAR file.

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

Table 38. Command-specific options

-n, --transfer

Transfer GAR file only.

-y, --deploy

Deploy GAR file only (assumes the GAR is already transferred to the DeployService.

-o, --overwrite

Overwrite existing deployment.

-b, --backup

Creates backup of existing configuration files

Table 39. Common 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 WS-Addressing 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 the GSI Secure Conversation authentication mechanism.

-g, --delegation <mode>

Enables delegation. mode can be either 'limited' or 'full'. Only supported with the GSI Secure Conversation authentication mechanism.

-l, --contextLifetime <value>

Sets the lifetime of the client security context. value is in milliseconds. Only supported with the 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 the GSI Secure Message authentication mechanism.

-p, --protection <type>

Specifies the protection level. type can be 'sig' for signature or 'enc' for encryption.

-x, --proxyFilename <value>

Sets the proxy file to use as client credential.

-z, --authorization <type>

Specifies authorization type. type can be 'self', 'host', 'none', or a string specifying the expected identity of the remote party.

-t, --timeout <timeout>

Specifies client timeout (in seconds). The client will wait maximum of the timeout value for a response from the server before returning an error. By default the timeout value is 10 minutes.

Examples:

 $ globus-remote-deploy-gar /tmp/myServie.gar

 $ globus-remote-deploy-gar gsiftp://localhost/tmp/myServie.gar

To see what GAR files haven been transfered but not yet deployed on the remote container run the following query on the DeployService, for example:

 $ wsrf-query -z hostSelf -s https://127.0.0.1:8443/wsrf/services/DeployService

Name

ws-enumerate-start — Starts an enumeration

Synopsis

ws-enumerate-start

Tool description

Creates a new enumeration context and prints it out to the console.

[Note]Note

The remote service must support the enumerate operation of the WS-Enumeration specification.

Command syntax

ws-enumerate-start [options]

Table 40. Common 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 WS-Addressing 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 the GSI Secure Conversation authentication mechanism.

-g, --delegation <mode>

Enables delegation. mode can be either 'limited' or 'full'. Only supported with the GSI Secure Conversation authentication mechanism.

-l, --contextLifetime <value>

Sets the lifetime of the client security context. value is in milliseconds. Only supported with the 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 the GSI Secure Message authentication mechanism.

-p, --protection <type>

Specifies the protection level. type can be 'sig' for signature or 'enc' for encryption.

-x, --proxyFilename <value>

Sets the proxy file to use as client credential.

-z, --authorization <type>

Specifies authorization type. type can be 'self', 'host', 'none', or a string specifying the expected identity of the remote party.

-t, --timeout <timeout>

Specifies client timeout (in seconds). The client will wait maximum of the timeout value for a response from the server before returning an error. By default the timeout value is 10 minutes.

Example:

 $ ws-enumerate-start -s http://localhost:8080/wsrf/services/ContainerRegistryService \
    > enum.context

The created enumeration context will be stored in the enum.context file which then can be passed to ws-enumerate and ws-enumerate-end command line clients.

Name

ws-enumerate — Retrieves enumeration data

Synopsis

ws-enumerate

Tool description

Retrieves the next set of enumeration data and prints it out to the console.

[Note]Note

The remote service must implement the WS-Enumeration specification.

Command syntax

ws-enumerate [options] <enumContextFile>

The <enumContextFile> is a file that contains the enumeration context.

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

Table 41. Command-specific options

-i, --items <int>

Specifies the total number of enumeration items to retrieve. The parameter value can be 'all' to retrieve the all the enumeration data. By default, only one element is retrieved.

-r, --maxCharacters <int>

Specifies the maximum number of characters (in Unicode) of the enumeration data that the client can accept at a time. By default, there is no limit on the size of the elements.

-n, --maxElements <int>

Specifies the maximum number of enumeration items to fetch at a time. By default, one element is retrieved at a time.

-o, --maxTime <int>

Specifies the maximum amount of time (in milliseconds) in which the enumeration data must be assembled. By default, there is no time limit.

Table 42. Common 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 WS-Addressing 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 the GSI Secure Conversation authentication mechanism.

-g, --delegation <mode>

Enables delegation. mode can be either 'limited' or 'full'. Only supported with the GSI Secure Conversation authentication mechanism.

-l, --contextLifetime <value>

Sets the lifetime of the client security context. value is in milliseconds. Only supported with the 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 the GSI Secure Message authentication mechanism.

-p, --protection <type>

Specifies the protection level. type can be 'sig' for signature or 'enc' for encryption.

-x, --proxyFilename <value>

Sets the proxy file to use as client credential.

-z, --authorization <type>

Specifies authorization type. type can be 'self', 'host', 'none', or a string specifying the expected identity of the remote party.

-t, --timeout <timeout>

Specifies client timeout (in seconds). The client will wait maximum of the timeout value for a response from the server before returning an error. By default the timeout value is 10 minutes.

Example:

 $ ws-enumerate -s http://localhost:8080/wsrf/services/ContainerRegistryService \ -i 10
    -n 5 enum.context

This command will display 10 elements of the enumeration data obtaining 5 elements at a time from the service.

Name

ws-enumerate-end — Stops an enumeration

Synopsis

ws-enumerate-end

Tool description

Releases an enumeration context.

[Note]Note

The remote service must implement the WS-Enumeration specification.

Command syntax

ws-enumerate-end [options] <enumContextFile>

The <enumContextFile> is a file that contains the enumeration context.

Table 43. Common 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 WS-Addressing 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 the GSI Secure Conversation authentication mechanism.

-g, --delegation <mode>

Enables delegation. mode can be either 'limited' or 'full'. Only supported with the GSI Secure Conversation authentication mechanism.

-l, --contextLifetime <value>

Sets the lifetime of the client security context. value is in milliseconds. Only supported with the 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 the GSI Secure Message authentication mechanism.

-p, --protection <type>

Specifies the protection level. type can be 'sig' for signature or 'enc' for encryption.

-x, --proxyFilename <value>

Sets the proxy file to use as client credential.

-z, --authorization <type>

Specifies authorization type. type can be 'self', 'host', 'none', or a string specifying the expected identity of the remote party.

-t, --timeout <timeout>

Specifies client timeout (in seconds). The client will wait maximum of the timeout value for a response from the server before returning an error. By default the timeout value is 10 minutes.

Example:

 $ ws-enumerate-end -s http://localhost:8080/wsrf/services/ContainerRegistryService \
    enum.context

Name

globus-xpath-query — Performs XPath query on a resource property document

Synopsis

globus-xpath-query

Tool description

The globus-xpath-query uses a custom query dialect implementation called TargetedXPath to query the resource property document of a resource. Please see the querying resource properties using XPath section for more details.

Command syntax

globus-xpath-query [options] [query expression] [rpQName]

The query expression is an XPath expression. The rpQName is a resource property QName. If a resource property is specified only that resource property within the resource property document will be queried. Otherwise, the entire resource property document will be queried. By default, a simple XPath query is assumed that returns the entire resource property document.

Table 44. Command-specific options

-n, --nsMapFile <file>

Specifies a file that contains namespace mappings. By default, the etc/globus_wsrf_core/namespace-mappings.xml file is used.

-u, --enumerate

Enumerate the query results. The query response will contain an enumeration context through which the actual query results can be obtained. The returned enumeration context can be used with the ws-enumerate command line tool. Also, please note that by default the enumeration context will expire in 30 minutes.

Table 45. Common 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 WS-Addressing 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 the GSI Secure Conversation authentication mechanism.

-g, --delegation <mode>

Enables delegation. mode can be either 'limited' or 'full'. Only supported with the GSI Secure Conversation authentication mechanism.

-l, --contextLifetime <value>

Sets the lifetime of the client security context. value is in milliseconds. Only supported with the 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 the GSI Secure Message authentication mechanism.

-p, --protection <type>

Specifies the protection level. type can be 'sig' for signature or 'enc' for encryption.

-x, --proxyFilename <value>

Sets the proxy file to use as client credential.

-z, --authorization <type>

Specifies authorization type. type can be 'self', 'host', 'none', or a string specifying the expected identity of the remote party.

-t, --timeout <timeout>

Specifies client timeout (in seconds). The client will wait maximum of the timeout value for a response from the server before returning an error. By default the timeout value is 10 minutes.

Examples:

 $ globus-xpath-query -s http://localhost:8080/wsrf/services/ContainerRegistryService \
    "//wssg:MemberServiceEPR/wsa:Address"

The above command will query the entire resource property document of the service.

 $ globus-xpath-query -s http://localhost:8080/wsrf/services/ContainerRegistryService \
    "//wssg:MemberServiceEPR/wsa:Address" wssg:Entry

The above command will query only the wssg:Entry resource property of the resource property document of the service.

 $ globus-xpath-query -s http://localhost:8080/wsrf/services/ContainerRegistryService \
    -u "//wssg:MemberServiceEPR/wsa:Address" > enum.context $ ws-enumerate
    -s http://localhost:8080/wsrf/services/ContainerRegistryService \ -i all enum.context

The first command will create an enumeration for the query results and store the returned enumeration context in a file. The second command will use the enumeration context stored in that file to retrieve the actual query results.

Name

Common Java Client Options — list of common options across commands

Common Java Client Options

Table 46. Common 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 WS-Addressing 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 the GSI Secure Conversation authentication mechanism.

-g, --delegation <mode>

Enables delegation. mode can be either 'limited' or 'full'. Only supported with the GSI Secure Conversation authentication mechanism.

-l, --contextLifetime <value>

Sets the lifetime of the client security context. value is in milliseconds. Only supported with the 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 the GSI Secure Message authentication mechanism.

-p, --protection <type>

Specifies the protection level. type can be 'sig' for signature or 'enc' for encryption.

-x, --proxyFilename <value>

Sets the proxy file to use as client credential.

-z, --authorization <type>

Specifies authorization type. type can be 'self', 'host', 'none', or a string specifying the expected identity of the remote party.

-t, --timeout <timeout>

Specifies client timeout (in seconds). The client will wait maximum of the timeout value for a response from the server before returning an error. By default the timeout value is 10 minutes.

Appendix A. Errors

Table A.1. Java WS Core Errors

Error CodeDefinitionPossible Solutions
Failed to acquire notification consumer home instance from registryCaused by javax.naming.NameNotFoundException: Name services is not bound in this Context error. Please see Running client programs from any directory if a client fails with this error.
The WS-Addressing 'To' request header is missingThis warning is logged by the container if the request did not contain the necessary WS-Addressing headers. The client either did not attempt to send those headers at all or is somehow misconfigured.If you are using a Java client and launching it directly using the java executable, take a look at Appendix B, Running client programs from any directory.
java.io.IOException: Token length X > 33554432 If you see this error in the container log, it usually means you are trying to connect to HTTPS server using HTTP. For example, the service address specifies 8443 as a port number and http as the protocol name.In general, use 8443 port number with the https protocol, and 8080 port number with the http protocol.
java.lang.NoSuchFieldError: DOCUMENTThis error usually indicates a mismatch between the version of Apache Axis that the code was compiled with and the version of Axis that the code is currently running with. Make sure that the same version of Axis is used at compile time and at runtime.
org.globus.wsrf. InvalidResourceKeyException: Argument key is null / Resource key is missingThese errors usually indicate that a resource key was not passed with the request or that an invalid resource key was passed with the request (that is, the element QName of the resource key did not match what the service expected).Make sure that the EPR used to invoke the service that contains the appropriate resource key. If you are using some command-line tool make sure to specify the resource key using the -k option or pass a complete EPR from a file using the -e option.
Unable to connect to localhost:xxxCannot resolve localhost. The machine's /etc/hosts isn't set up correctly and/or you do not have DNS for these machines. There should always be an entry in /etc/hosts (or /etc/hostname/ on Debian) for localhost in the following format (IP address/fully qualified domain name/short name):
140.221.8.109   cognito.mcs.anl.gov cognito
org.globus.common.ChainedIOException: Failed to initialize security contextThis may indicate that the user's proxy is invalid.To correct the error, the user must properly initialize the user proxy. See grid-proxy-init for more information on proxy initialization.
Error: org.xml.sax.SAXException: Unregistered type: class xxxThis may indicate that an Axis generated XML type, defined by the WS RLS XSD, was not properly registered. While all the XML types should get registered upon deployment without intervention by the user, sometimes they do not.To remedy the situation add a typeMapping to the server-config.wsdd file under globus_wsrf_replicalocation_service. Use the format shown here.
No socket factory for 'https' protocol

When a client fails with the following exception:

 java.io.IOException: No socket factory for 'https' protocol at
        org.apache.axis.transport.http.HTTPSender.getSocket(HTTPSender.java:179) at
        org.apache.axis.transport.http.HTTPSender.writeToSocket(HTTPSender.java:397) at
        org.apache.axis.transport.http.HTTPSender.invoke(HTTPSender.java:135)

FIXME - it may have happened because...

Add the following to the client:

 import org.globus.axis.util.Util; ... static { Util.registerTransport(); }
...
No client transport named 'https' found

When a client fails with the following exception:

No client transport named 'https' found at
        org.apache.axis.client.AxisClient.invoke(AxisClient.java:170) at
        org.apache.axis.client.Call.invokeEngine(Call.java:2726)

The client is most likely loading an incorrect client-config.wsdd configuration file.

Ensure that the GT4 installation directory is listed as the first entry in the CLASSPATH of the client. For example:

CLASSPATH=/usr/local/globus-4.2.0:/foo/bar/others.jar:...

If you are seeing this problem in Tomcat, copy the client-config.wsdd from the GT4 installation directory to the Web application's WEB-INF/classes directory.

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 from working 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.

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

FIXME - what causes this?

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"
GAR deploy/undeploy fails with container is running error

A GAR file can only be deployed or undeployed locally while the container is off. However, GAR deployment/undeployment might still sometimes fail with this error even if the container is off. This usually happens if the container has crashed or was stopped improperly, preventing the container from cleaning up its state files.

To resolve this problem, delete any files under the $GLOBUS_LOCATION/var/state directory and try to redeploy/reundeploy the GAR file again.

Glossary

C

certificate

A public key plus information about the certificate owner bound together by the digital signature of a CA. In the case of a CA certificate, the certificate is self signed, i.e. it was signed using its own private key.

G

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. See the Java WS Core Developer's Guide for details.

J

JNDI

Java Naming and Directory Interface (JNDI) API are used to access a central transient container registry. The registry is mainly used for discovery of the ResourceHome implementations. However, the registry can also be used store and retrieve arbitrary information. The jndi-config.xml files are used to populate the registry. See the JNDI Tutorial for details.

jndi-config.xml

It is an XML-based configuration file used to populate the container registry accessible via the JNDI API. See in the Java WS Core Developer's Guide] for details.

R

ResourceHome

In Java WS Core, resources are managed and discovered via ResourceHome implementations. The ResourceHome implementations can also be responsible for creating new resources, performing operations on a set of resources at a time, etc. ResourceHomes are configured in JNDI and are associated with a particular web service.

S

server-config.wsdd

Axis server-side WSDD configuration file. It contains information about the services, the type mappings and various handlers.

W

Web Services Addressing (WSA)

The WS-Addressing specification defines transport-neutral mechanisms to address web services and messages. Specifically, it defines XML elements to identify web service endpoints and to secure end-to-end endpoint identification in messages. See the W3C WS Addressing Working Group for details.

Web Services Description Language (WSDL)

WSDL is an XML document for describing Web services. Standardized binding conventions define how to use WSDL in conjunction with SOAP and other messaging substrates. WSDL interfaces can be compiled to generate proxy code that constructs messages and manages communications on behalf of the client application. The proxy automatically maps the XML message structures into native language objects that can be directly manipulated by the application. The proxy frees the developer from having to understand and manipulate XML. See the WSDL 1.1 specification for details.

X

XML

Extensible Markup Language (XML) is standard, flexible, and extensible data format used for web services. See the W3C XML site for details.