GT 3.9.5 Component Guide to Public Interfaces: Java WS Core

• Semantics and syntax of Java WS Core APIs
• Semantics and syntax of WSDL for Java WS Core
• Command-line tools
• GUIs
• Description of domain-specific interface data
• Configuration interface
• Environment variables

Semantics and syntax of APIs

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.

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

Semantics and syntax of the WSDL

Java WS Core contains an implementation of the following specifications. Please see the corresponding specifications for details:

• WSRF
  • WS-ResourceProperties (WSRF-RP) specification [wsdl | xsd]
  • WS-ResourceLifetime (WSRF-RL) specification [wsdl | xsd]
  • WS-ServiceGroup (WSRF-SG) specification [wsdl | xsd]
  • WS-BaseFaults (WSRF-BF) specification [wsdl | xsd]
• WSN
  • WS-BaseNotification specification [wsdl | xsd]
  • WS-Topics specification [xsd]

Command-line tools

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

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

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

globus-start-container

Tool description

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

Command syntax

globus-start-container [options]

globus-stop-container

Tool description

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

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

Command syntax

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

Where:

'soft'

This option lets the threads die naturally

'hard'

This option forces an immediate JVM shutdown.

Example:

$ globus-stop-container soft

wsrf-destroy

wsrf-destroy [options]

Example:

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

wsrf-set-termination-time

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

Example:

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

wsrf-query

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

Example:

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

wsrf-get-property

wsrf-get-property [options] <property>

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

Example:

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

wsrf-get-properties

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

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

Example:

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

wsrf-insert-property

wsrf-insert-property [options] <propertyValueFile>

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

Example:

Contents of in.xml:

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

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

wsrf-update-property

wsrf-update-property [options] <propertyValueFile>

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

Example:

Contents of in.xml:

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

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

wsrf-delete-property

wsrf-delete-property [options] <property>

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

Example:

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

wsn-get-current-message

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

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

Example:

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

wsn-pause-subscription

wsn-pause-subscription [options]

Example:

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

wsn-resume-subscription

wsn-resume-subscription [options]

Example:

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

wsn-subscribe

wsn-subscribe [options] <topic>

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

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

Example:

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

globus-deploy-gar

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

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

Example:

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

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

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

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

globus-undeploy-gar

globus-undeploy-gar <gar.id>

$ globus-undeploy-gar globus_wsrf_core_samples_counter

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

Common Command syntax

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

Overview of Graphical User Interface

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

Semantics and syntax of domain-specific interface

Interface introduction

[provide an overview of the purpose and structure of the domain-specific interface]

Syntax of the interface

[list and describe detailed information here]

Configuration interface

Configuration overview

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

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

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

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

Syntax of the interface

• Global Configuration
• Service Configuration
• Usage Statistics Configuration
• Configuration Profiles

Global Configuration

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

General configuration parameters:

Standalone/embedded container-specific configuration parameters:

Service Configuration

WSDD

An example of a deployment descriptor for a CounterService:

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

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

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

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

Axis Standard Parameters

Java WS Core Parameters

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

JNDI

An example of a JNDI configuration bit for a CounterService:

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

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

ResourceHomeImpl

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

Configuring Resource Cache

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

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

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

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

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

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

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

ServiceResourceHome

This implementation does not accept any special parameters.

Usage Statistics Configuration

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

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

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

Configuration Profiles

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

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

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

Environment variable interface

Globus Standard

Launch script specific

Options supported by the GLOBUS_OPTIONS environment property: