In the document/literal mode as defined in the WS-I Basic Profile at most one <wsdl:part> is allowed in the <wsdl:message> element and it must use the 'element' attribute. Also, the wire signatures must be unique (cannot use the same 'element' attribute in <wsdl:part> in two different <wsdl:message> elements).

Note

Axis' WSDL2Java tool might sometimes incorrectly detect that schema follows the wrapped/literal mode and generate wrong stub and type classes. To ensure that document/literal mode is always used: use Java WS Core's generateStub* Ant tasks in <install>/share/globus_wsrf_tools/build-stubs.xml file if you are using Axis' WSDL2Java tool directly, you can alternatively specify the -W command line option. Also, with wrapped/literal mode, the element name had to match the operation name in wsdl. This is not necessary with document/literal mode.

Do not use or mix the literal mode with the SOAP encoding mode (R2706). For example, do not use the soapenc:Array type. Please see the 5.2.3 section in the WS-I Basic Profile for details.

When deploying a Java Bean using the <resource> entry in jndi-config.xml please note the following:

To obtain JNDI InitialContext do:

import org.globus.wsrf.jndi.JNDIUtils;
...
InitialContext ctx = JNDIUtils.getInitialContext();
Foo foo = (Foo)ctx.lookup(...);

	Note
	It is important to use this API to obtain the InitialContext as the context must be initialized with the right properties. That ensures that the right JNDI implementation is used as there might be other JNDI implementations present as for example in application servers such as JBoss.

To activate a service, an RPCProvider is available from both Axis and Globus.

The scope setting of the service dictates when and how service instances are created:

If the service implements the javax.xml.rpc.server.ServiceLifecycle interface, the lifecycle methods will be called according to the scope setting as a service instance is created and destroyed.

For example, in Application scope, destroy() will be called on container shutdown, and in Request scope it will be called after the service method is called.

With Axis RPCProvider, JAAS credentials are never associated with the invocation thread.

The scope setting of the service dictates when and how service instances are created (only Application and Request scopes are supported with Globus RPCProvider):

A ResourceHome will be activated either on the first service invocation or, if "loadOnStartup" parameter is set to "true", during container startup. Both mechanisms trigger actual activation by looking up the ResourceHome in the JNDI directory. This initial lookup causes a proper MessageContext and/or JAAS subject to be associated with the current thread, instantiation of the object implementing the ResourceHome and, if the ResourceHome implements the org.globus.wsrf.jndi.Initializable interface, the invocation of the initialize() function.

In fact, the same steps are performed upon initial lookup of any JNDI resource entry that uses the org.globus.wsrf.jndi.BeanFactory class for its factory and is defined directly under a service entry in a jndi-config.xml file.

If you are using a ServiceResourceHome please make sure to deploy the service with the "loadOnStartup" option enabled and in Application scope. That will ensure that the ResourceHome is initialized with the right service/resource.

The WS-RF and WS-N specifications distributed with Java WS Core use WS-Addressing (the March 2004 version of the specification) for addressing services and resources. Java WS Core uses the Apache Addressing library for WS-Addressing support. The API is pretty straightforward and easy to use. Most of the work is done in AddressingHandler deployed in the client and server configuration files. See Apache Addressing documentation for details.

Service service = new Service();
Call call = (Call) service.createCall();

String url = "http://localhost:8080/axis/services/Version";

AddressingHeaders headers = new AddressingHeaders();
headers.setTo(new To(url));

// pass the addressing info to the addressing handler
call.setProperty(Constants.ENV_ADDRESSING_REQUEST_HEADERS, headers);

call.setTargetEndpointAddress(new URL(url));
call.setOperationName(new QName(url, "getVersion")); // url here is just a namespace

String ret = (String) call.invoke(new Object[]);

String url = "http://localhost:8080/axis/services/Version";

EndpointReferenceType epr = new EndpointReferenceType();
epr.setAddress(new Address(url));

VersionServiceAddressingLocator locator =
     new VersionServiceAddressingLocator();

VerionServicePortType port = locator.getVersionPort(epr);

port.getVersion();

// create a reference property
QName keyName = new QName("http://axis.org", "VersionKey");
String keyValue = "123";
 
SimpleResourceKey key = new SimpleResourceKey(keyName, keyValue);

ReferencePropertiesType props = new ReferencePropertiesType();

// convert to SOAPElement and add to the list
props.add(key.toSOAPElement()); 
...

...
Service service = new Service();
Call call = (Call) service.createCall();

String url = "http://localhost:8080/axis/services/Version";

AddressingHeaders headers = new AddressingHeaders();
headers.setTo(new To(url));
headers.setReferenceProperties(props);

// pass the addressing info to the addressing handler
call.setProperty(Constants.ENV_ADDRESSING_REQUEST_HEADERS, headers);

call.setTargetEndpointAddress(new URL(url));
call.setOperationName(new QName(url, "getVersion")); // url here is just a namespace

String ret = (String) call.invoke(new Object[]);

...
String url = "http://localhost:8080/axis/services/Version";

EndpointReferenceType epr = new EndpointReferenceType();
epr.setAddress(new Address(url));
epr.setProperties(props);

VersionServiceAddressingLocator locator =
    new VersionServiceAddressingLocator();

VerionServicePortType port = locator.getVersionPort(epr);

port.getVersion();

There are a few steps involved in setting up and receiving notifications:

5.2.1.2.1. Step 1: Implement the callback

The notification consumer application must provide an implementation of the org.globus.wsrf.NotifyCallback interface. The deliver function of the interface will be invoked whenever a notification for that consumer arrives. The message parameter will either be of org.w3c.dom.Element type if the message type was unknown or some object mapped to the type of the message.

	Note
	The deliver function should be thread-safe as multiple notifications might come at once. Notifications might also come unordered and some might even be lost (due to network failures).

5.2.1.2.2. Step 2: Start NotificationConsumerManager

In order to facilitate the receipt of notifications, start a NotificationConsumerManager by doing the following:

import org.globus.wsrf.NotificationConsumerManager; 
...

NotificationConsumerManager consumer = null;
try {
   consumer = NotificationConsumerManager.getInstance();
   consumer.startListening();
   ...
} catch (...) {
   ...
}

Important

On the client when the consumer.startListening() is called an embedded container is actually started in the background. That embedded container is the same as the standalone container but configured with only one or two services needed to handle the notifications. Therefore, any client using notification consumer API will have the same dependencies on the libraries and configurations files as the basic standalone container code. Also, please check the Section 4.2, “Program fails with "Failed to acquire notification consumer home instance from registry" error” if the consumer.startListening() call failed on the client. On the server when the consumer.startListening() is called the container in which the service is running in is used to receive the notifications. Therefore, there are no extra dependencies.

import org.globus.wsrf.NotifyCallback;
import org.apache.axis.message.addressing.EndpointReferenceType;
...

   MyCallback callback = new MyCallback();
   EndpointReferenceType consumerEPR =
       consumer.createNotificationConsumer(callback);
   ...

class MyCallback implements NotifyCallback {
  ....
}

import org.oasis.wsn.TopicExpressionType;
import org.oasis.wsn.Subscribe;
import org.oasis.wsn.SubscribeResponse;
import org.globus.wsrf.WSNConstants;
import org.globus.wsrf.WSRFConstants;
...

TopicExpressionType topicExpression = new TopicExpressionType();
topicExpression.setDialect(WSNConstants.SIMPLE_TOPIC_DIALECT);
topicExpression.setValue(WSRFConstants.TERMINATION_TIME);

Subscribe request = new Subscribe();
request.setUseNotify(Boolean.TRUE);
request.setConsumerReference(consumerEPR);
request.setTopicExpression(topicExpression);

SubscribeResponse subResponse = port.subscribe(request);
...

import org.globus.wsrf.core.notification.SubscriptionManager;
import org.globus.wsrf.core.notification.service.SubscriptionManagerServiceAddressingLocator;
import org.oasis.wsrf.lifetime.Destroy;
...

SubscriptionManagerServiceAddressingLocator sLocator = new SubscriptionManagerServiceAddressingLocator();
SubscriptionManager manager = sLocator.getSubscriptionManagerPort(
                        subResponse.getSubscriptionReference());
manager.destroy(new Destroy());
...

   ...
} catch(Exception e) {
   ...
} finally {
   if (consumer != null) {
      try { consumer.stopListening(); } catch (Exception ee) {}
   }
}

The org.globus.wsrf.utils.Version API can be used to obtain Java WS Core version information programmatically. For example to display major, minor and patch version information do:

import org.globus.wsrf.utils.Version;
...
System.out.println("Major: " + Version.getMajor());
System.out.println("Minor: " + Version.getMinor());
System.out.println("Patch: " + Version.getPatch());

Java WS Core supports SOAP with Attachments. DIME, MIME, and MTOM formats are supported.

To add an attachment to a request do:

import javax.activation.DataHandler;
import javax.activation.FileDataSource;
import javax.xml.rpc.Stub;
import org.apache.axis.client.Call;
....
File file = new File(..);
DataHandler dataHandler = 
        new DataHandler(new FileDataSource(file));

((Stub)port)._setProperty(
        Call.ATTACHMENT_ENCAPSULATION_FORMAT,
        Call.ATTACHMENT_ENCAPSULATION_FORMAT_MTOM);
            
((org.apache.axis.client.Stub)port).addAttachment(dataHandler);

To retrieve attachments associated with a request do:

import javax.activation.DataHandler;
import javax.xml.soap.AttachmentPart;
import org.apache.axis.Message;
import org.apache.axis.MessageContext;
....
MessageContext msgContext = MessageContext.getCurrentContext();
Message reqMsg = msgContext.getRequestMessage();
if (reqMsg.getAttachmentsImpl() == null) {
  throw new Exception("Attachments are not supported");
}
Iterator it = reqMsg.getAttachments();
while (it.hasNext()) {
  AttachmentPart part = (AttachmentPart) it.next();
  DataHandler dataHandler = part.getDataHandler();
}

The SwA support adds a small overhead to overall SOAP processing. To disable SwA support for improved performance delete $GLOBUS_LOCATION/lib/common/geronimo-activation_1.0.2_spec-1.1-SNAPSHOT.jar and $GLOBUS_LOCATION/lib/common/geronimo-javamail_1.3.1_spec-1.1-SNAPSHOT.jar files.

Please note that SOAP attachments can be used with message security but they will not be signed or encrypted.

In most cases, a service will need to return the endpoint information of the container to a client. Unfortunately, getting that information might not be easy. The only reliable way of getting the container endpoint information is to extract it from the MessageContext.TRANS_URL property of the MessageContext/ResourceContext associated with the current thread.

To obtain base container endpoint information use ServiceHost API. For example:

import org.globus.wsrf.container.ServiceHost;
...
URL containerBaseUrl = ServiceHost.getBaseURL();
...

The above will return the base container URL such as http://localhost:8080/wsrf/services/.

To obtain service endpoint information use ResourceContext API. For example:

import org.globus.wsrf.ResourceContext;
...
URL serviceUrl = ResourceContext.getResourceContext().getServiceURL();
...

The above will return the service URL such as http://localhost:8080/wsrf/services/MyService.

To obtain WS-Addressing endpoint for the service use AddressingUtils API. For example:

import org.apache.axis.message.addressing.EndpointReferenceType;
import org.globus.wsrf.utils.AddressingUtils;
...
EndpointReferenceType containerEndpoint = 
       AddressingUtils.createEndpointReference(null);
...

The above will create a EndpointReferenceType object initialized with the Address field set to the service URL (as before) and empty reference properties. Also, you can pass a non-null ResourceKey instance to the createEndpointReference() function to create an endpoint for a specific resource. The reference properties field of the created EndpointReferenceType object will be set to the given ResourceKey.

	Note
	The ServiceHost API will return the correct information and AddressingUtils API will work correctly only if called from the same thread as the service method was invoked from.

While we strongly recommend that you use the JNDI mechanism to provide your service with configuration information, it is sometimes necessary to obtain the value of parameters set in the WSDD file. Java WS Core provides some helper functions to ease this process:

import org.globus.wsrf.utils.ContextUtils;
import org.apache.axis.MessageContext;
...
MessageContext context = MessageContext.getCurrentContext();
String sampleProperty = (String)
    ContextUtils.getServiceProperty(context, "myProperty");
...

Note that this function requires that a MessageContext is associated with the current thread, which in general means that the call needs to happen within the context of a web service invocation.

	Note
	Specifying parameters using WSDD files depends on Axis and will likely not be supported in future versions of the toolkit.

The following properties can be obtained from the SOAPContext/MessageContext associated with the current thread:

The Constants.MC_CONFIGPATH property should be used to load any type of configuration file. Only Constants.MC_CONFIGPATH and Constants.MC_HOME_DIR are associated with the thread during activation. In the standalone container the Constants.MC_HOME_DIR and Constants.MC_CONFIGPATH properties will usually point to the same directory. However, in Tomcat they will point to two different directories. Since GT 4.0.1, the Constants.MC_HOME_DIR value can be accessed using the org.globus.wsrf.ContainerConfig.getSchemaDirectory() static call, and Constants.MC_CONFIGPATH value via the org.globus.wsrf.ContainerConfig.getBaseDirectory() static call.

Services in the container can be invoked locally. Local invocations work just like remote invocations (all handlers are called, messages get serialized/deserialized) but messages do not travel over the network - everything happens in memory.

Local invocations can only be made on the server side. URLs with "local" protocol name are used for local invocations.

To invoke a service locally, do the following:

That's all. By default the local invocations are made using the default instance of the AxisServer engine. It is possible to make local invocations using a different AxisServer engine instance if there is a MessageContext associated with the current thread (the MessageContext should have a reference to the desired AxisServer engine instance). To make a local invocation using non-default AxisServer engine add the following (using above example):

import org.globus.axis.transport.local.LocalTransportUtils;
...
MyService port = ...

LocalTransportUtils.enableLocalTransport((Stub)port);

port.hello();

import org.globus.axis.transport.local.LocalTransportUtils;
...
LocalTransportUtils.init();
...

Axis associates a MessageContext object with the current thread of execution only during a remote service invocation (when a service method is actually called remotely). Sometimes, it might be necessary to execute a piece of code with some specific MessageContext object associated with the current thread. For example, a background server-side task might want to call some service method directly.

The MessageContextHelper API can be used to temporarily associate a specific MessageContext object with the current thread in order to call some code that needs that context to be associated with the thread. Example:

import org.globus.axis.utils.MessageContextHelper;
...
MessageContext newCtx = ...;
MessageContextHelper helper = new MessageContextHelper(newCtx);
helper.set();
try {
   // call code that needs MessageContext associated with the thread
} finnally {
   helper.restore();
}
...

By default Java WS Core clients will use HTTP 1.1 protocol with chunked encoding. Java WS Core clients will also attempt to reuse HTTP/S connections between the calls. The default timeout for clients is 10 minutes. All of these connection properties can be controlled programmatically using the HTTPUtils API as shown below.

	Note
	Please note that once a connection property is set on a given Stub, it is applied to ALL calls made using that Stub.

import org.globus.axis.transport.HTTPUtils;
...
MyServiceAddressingLocator locator = 
       new MyServiceAddressingLocator();
MyService port = locator.getMyServicePort(url);

// set timeout to 2 minutes
HTTPUtils.setTimeout((Stub)port, 1000 * 60 * 2);

port.hello();

import org.globus.axis.transport.HTTPUtils;
...
MyServiceAddressingLocator locator = 
       new MyServiceAddressingLocator();
MyService port = locator.getMyServicePort(url);

// close connection after the call
HTTPUtils.setCloseConnection((Stub)port, true);

port.hello();

// do not close connection - let it be reused
HTTPUtils.setCloseConnection((Stub)port, false);

port.hello();

import org.globus.axis.transport.HTTPUtils;
...
MyServiceAddressingLocator locator = 
       new MyServiceAddressingLocator();
MyService port = locator.getMyServicePort(url);

// disable chunked encoding
HTTPUtils.setChunkedEncoding((Stub)port, false);

port.hello();

// re-enable chunked encoding
HTTPUtils.setChunkedEncoding((Stub)port, true);

port.hello();

import org.globus.axis.transport.HTTPUtils;
...
MyServiceAddressingLocator locator = 
       new MyServiceAddressingLocator();
MyService port = locator.getMyServicePort(url);

// force HTTP 1.0
HTTPUtils.setHTTP10Version((Stub)port, true);

port.hello();

// force HTTP 1.1
HTTPUtils.setHTTP10Version((Stub)port, false);

port.hello();

Any program that is based on Java WS Core should contain as a first entry in its classpath the directory of the Java WS Core installation. This is to ensure that the right client-config.wsdd is used by the client. That configuration file contains important client-side information such as handlers, type mappings, etc.

Also, any program that is a notification consumer should be initialized with the appropriate GLOBUS_LOCATION system property (set to the installation directory of Java WS Core). If the system property is not set, the notification consumer might not initialize or work properly.

The contents of the GAR file are processed in the following way (all steps are performed only if necessary):

Notes:

To execute all tests contained in a given jar file with an internal container run the following:

$ cd $GLOBUS_LOCATION
$ ant -f share/globus_wsrf_test/runtests.xml run -Dtests.jar=<test.jar>

Where <test.jar> is an absolute path to the jar file that contains the tests.

To execute all tests contained in a given jar file with an external container run the following:

$ cd $GLOBUS_LOCATION
$ ant -f share/globus_wsrf_test/runtests.xml runServer -Dtests.jar=<test.jar>

By default, the external container is assumed to be running at http://localhost:8080/wsrf/services/. To specify a different container, use the -Dtest.server.url=<url> property.

By default, all PackageTests and SecurityTests tests will be executed. To execute PackageTests only, specify -DbasicTestsOnly=true option. To execute SecurityTests only, specify -DsecurityTestsOnly=true option.

By default, the test results will be generated in the XML format.

To execute a single test suite with an internal container run the following:

$ cd $GLOBUS_LOCATION
$ ant -f share/globus_wsrf_test/runtests.xml runOne -Dtest.class=<test.class>

Where <test.class> is a Java class that contains a test suite.

To execute a single test suite with an external container run the following:

$ cd $GLOBUS_LOCATION
$ ant -f share/globus_wsrf_test/runtests.xml runOneServer -Dtest.class=<test.class>

By default, the external container is assumed to be running at http://localhost:8080/wsrf/services/. To specify a different container, use the -Dtest.server.url=<url> property.

By default, the test results will be generated in the plain text format.

It is also possible to execute a single test case (or a set of test cases) within a test suite by specifying a -Dtests=<testCase1[,testCaseN]> property. However, this will only work with test suites that inherit from org.globus.wsrf.test.FilteredTestSuite or org.globus.wsrf.test.GridTestSuite classes. Example:

$ cd $GLOBUS_LOCATION
$ ant -f share/globus_wsrf_test/runtests.xml runOne \
   -Dtest.class=org.globus.interop.widget.test.PackageTests \
   -Dtests="testScenario1,testScenario2"

The test reports will be put in the $GLOBUS_LOCATION/share/globus_wsrf_test/tests/test-reports directory by default. A different test reports directory can be specified by passing -Djunit.reports.dir=<directory>.

Use -Djunit.test.format property to generate the test results in a specified format (xml or plain). Example:

$ ant -f share/... -Djunit.test.format=plain

Use -Djunit.jvmarg to pass arbitrary properties to the testing JVM. Example:

$ ant -f share/... -Djunit.jvmarg="-Dorg.globus.wsrf.container.server.id=myServerID"

The evaluators must be registered in order for Java WS Core to recognize them. The registration is done through the JNDI configuration file. The expression evaluators must be deployed as global resources under a specific subcontext.

<global>
  <resource name="query/eval/MyQueryExpressionEval"
            type="foo.bar.MyQueryExpressionEvaluator">
    <resourceParams>
      <parameter>
        <name>factory</name>
        <value>org.globus.wsrf.jndi.BeanFactory</value>
      </parameter>
    </resourceParams>
  </resource>
</global>

<global>
  <resource name="topic/eval/MyTopicExpressionEval"
            type="foo.bar.MyTopicExpressionEvaluator">
    <resourceParams>
      <parameter>
        <name>factory</name>
        <value>org.globus.wsrf.jndi.BeanFactory</value>
      </parameter>
    </resourceParams>
  </resource>
</global>

A serializer/deserializer must be registered for the dialect of the evaluator in order for the expression to be properly serialized and deserialized. The serializers/deserializers for the dialect are deployed as almost any other type mapping. In general, each type mapping specifies a type QName. For dialect serializers/deserializers, that type QName takes a slightly different name.

5.5.1.3.1. Specifying the QName for query expression evaluators

For query expression evaluators, that QName must have the local name part set to QueryExpressionDialect and namespace part set to the dialect of the query expression evaluator.

Example:

<typeMapping 
   encodingStyle="" 
   deserializer="org.apache.axis.encoding.ser.SimpleDeserializerFactory"
   serializer="org.apache.axis.encoding.ser.SimpleSerializerFactory"
   type="java:java.lang.String"
   qname="ns12:QueryExpressionDialect" 
   xmlns:ns12="http://foo.bar/MyQueryDialect"/>

	Note
	These type mappings must be deployed both on the client and the server.

5.5.1.3.2. Specifying the QName for topic expression evaluators

For topic expression evaluators, that QName must have the local name part set to TopicExpressionDialect and namespace part set to the dialect of the topic expression evaluator.

Example:

<typeMapping 
   encodingStyle="" 
   deserializer="org.apache.axis.encoding.ser.SimpleDeserializerFactory"
   serializer="org.apache.axis.encoding.ser.SimpleSerializerFactory"
   type="java:java.lang.String"
   qname="ns12:TopicExpressionDialect" 
   xmlns:ns12="http://foo.bar/MyTopicDialect"/>

	Note
	These type mappings must be deployed both on the client and the server.

The standard GetCurrentMessageProvider might not know how to properly serialize the notification message currently associated with the specified topic. The GetCurrentMessageProvider can be configured to use a helper serializer for a given notification message type.

To configure such a helper serializer, define the following global resource in your deploy-jndi.xml configuration file:

<global>
  <resource
    name="providers/GetCurrentMessageProvider/foo.bar.MyNotificationMessage"
    type="foo.bar.MyMessageSerializer">
    <resourceParams>
      <parameter>
        <name>factory</name>
        <value>org.globus.wsrf.jndi.BeanFactory</value>
      </parameter>
    </resourceParams>
  </resource>
</global>

Where the <resource> attribute: