Links: Table of Contents | Single HTML | Single PDF

Enabling Advanced Features in a Web Service Application

This article highlights the steps required to enable Metro-specific advanced functionalities in a web service and its corresponding client application. As with the previous article, two accompanying code samples are included. Again, one starts from Java source code and the other from an existing WSDL document to develop their respective web services. However, this article and its code samples show how WS-Policy can used to enable WS-Addressing and WS-Reliable Messaging in the web services and their clients.

Table of Contents

1. Overview

Supporting code samples are included to demonstrate building a web service using WSIT functionality. The examples show how to develop a web service both starting from Java source code and starting from an existing WSDL document. For both cases, it shows how to develop a corresponding client application from the web service's WSDL document. The examples can be found in the WSIT source tree here:

As you follow along with the sample code, please confirm that you are working in either wsit-enabled-fromjava or wsit-enabled-fromwsdl rather than one of the previous article's sample code directories, wsit-jaxws-fromjava or wsit-jaxws-fromwsdl.

2. Prerequisites and Environment Configuration

As in the previous article, the steps in this document require that you have already installed the WSIT jars into your web container. It also requires the following software be installed: JDK 6.0 Update 29 or later, Apache Ant 1.6.5 or later, and a web container: either Glassfish v3.x or Apache Tomcat 7.0. Further, your Metro build environment needs to be configured as described in the Environment Configuration Settings section of the previous article.

3. WSIT Configuration and WS-Policy

Advanced web service features are enabled and configured using a mechanism defined by the Web Services Policy Framework (WS-Policy) specification. A web service expresses its requirements and capabilities via policies embedded in the service's WSDL description. A service consumer verifies it can handle the expressed requirements and, optionally, uses server capabilities advertised in policies.

Technologies like Reliable Messaging, Addressing, or Secure Conversations, provides a set of policy assertions it can process. Those assertions provide the necessary configuration details to the Metro run-time to enable proper operation of these features used by a given web service. The assertions may specify particular configuration settings or rely on default settings that are pre-determined by the specific technology. For instance, in the snippet shown below, wsrm:AcknowledgementInterval and wsrm:InactivityTimeout are both optional and could be omitted. The following is an XML snippet showing WS-Policy assertions for WS-Addressing and WS-Reliable Messaging:

<wsp:Policy wsu:Id="AddNumbers_policy">
      <wsam:Addressing wsp:Optional="false"/>
        <wsrm:InactivityTimeout Milliseconds="600000"/>
        <wsrm:AcknowledgementInterval Milliseconds="200"/>

This snippet would be equally valid in either a WSIT configuration file or a web service's WSDL document.

4. Configuring WSIT in the Web Service

4.1. Starting from Java

When developing a web service from scratch or based on an existing Java class, WSIT features are enabled using a configuration file. That file, wsit-fromjava.server.AddNumberImpl.xml, is written in WSDL format. An example configuration file can be found in the accompanying samples:

The configuration file settings will be incorporated dynamically by the WSIT run-time into the WSDL it generates for the web service. So when a client requests the service's WSDL, the run-time will embed into the WSDL any publically visible policy assertions contained in the configuration file. For the example link above, the Addressing and Reliable Messsaging assertions would be part of the WSDL as seen by the client.


wsit.xml must be in the WEB-INF sub-directories of the application's WAR file when it is deployed to the web container. Otherwise, the WSIT run-time environment will not find it.

4.2. Starting from WSDL

When developing a web service starting from an existing WSDL, the situation is actually simpler. The policy assertions needed to enable various WSIT technologies will already be embedded in the WSDL document. Here is an example WSDL document in the accompanying samples:

5. Building and Deploying the Web Service

Once configured, a WSIT-enabled web service is built and deployed in the same manner as a standard JAX-WS web service. If you are not familiar with those steps, please review the following sections from Building a Simple Metro Application: Building a JAX-WS Web Service and Deploying the Web Service to a Web Container. However, the URLs needed to verify the respective web services differ from the previous article's examples and are listed below:

6. Configuring WSIT in the Web Service Client

Client-side configuration of WSIT functionality is largely automatic in the WSIT environment. The WSDL document seen by the client will already contain the WSIT policy assertions. Those assertions describe any requirements from the server as well as any optional features the client may use. The WSIT build tools and run-time environment will detect the WSDL's policy assertions and configure themselves appropriately, if possible. If an unsupported assertion is found, an error message describing the problem will be displayed.

7. Building and Running a Web Service Client

As with the web service itself, building and running a WSIT-enabled client application is identical to running a standard JAX-WS client application. Those steps are described in the following sections of the previous article: Building a JAX-WS Web Service Client and Running the Web Service Client. You can expect to see output from the client similar to the following:

[java] Invoking addNumbers(10, 20)
[java] The result of adding 10 and 20 is 30.
[java] Invoking addNumbers(-10, 20)
[java] Caught AddNumbersFault_Exception: Numbers: -10, 20
[java] 12.1.2012 15:34:37 []  closeSequences
[java] INFO: WSRM1157: Waiting for sequence [ uuid:6ecc55a3-78cf-4e8f-9b18-87ffa6fbb8b0 ] state change to [ CLOSED ] has timed out after 3 000 milliseconds

[java] 12.1.2012 15:34:40 []  closeRmSession
[java] INFO: WSRM1157: Waiting for sequence [ uuid:6ecc55a3-78cf-4e8f-9b18-87ffa6fbb8b0 ] state change to [ TERMINATING ] has timed out after 3 000 milliseconds

8. Undeploying a Web Service

As described in Undeploying a JAX-WS Web Service, to undeploy a web service means to both disable and remove it from the web container. This section provides the necessary commands to undeploy this article's sample web services from both GlassFish and Tomcat.

8.1. Undeploying from GlassFish

asadmin undeploy --user admin wsit-enabled-fromjava
asadmin undeploy --user admin wsit-enabled-fromwsdl

8.2. Undeploying from Tomcat

rm $CATALINA_HOME/webapps/wsit-enabled-fromjava.war
rm $CATALINA_HOME/webapps/wsit-enabled-fromwsdl.war