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
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.
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.
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"> <wsp:ExactlyOne> <wsp:All> <wsam:Addressing wsp:Optional="false"/> <wsrm:RMAssertion> <wsrm:InactivityTimeout Milliseconds="600000"/> <wsrm:AcknowledgementInterval Milliseconds="200"/> </wsrm:RMAssertion> </wsp:All> </wsp:ExactlyOne> </wsp:Policy>
This snippet would be equally valid in either a WSIT configuration file or a web service's WSDL document.
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.
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:
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:
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.
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] [java] Invoking addNumbers(-10, 20) [java] Caught AddNumbersFault_Exception: Numbers: -10, 20 [java] 12.1.2012 15:34:37 [com.sun.xml.ws.rx.rm.runtime.ClientTube] 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 [com.sun.xml.ws.rx.rm.runtime.ClientTube] closeRmSession [java] INFO: WSRM1157: Waiting for sequence [ uuid:6ecc55a3-78cf-4e8f-9b18-87ffa6fbb8b0 ] state change to [ TERMINATING ] has timed out after 3 000 milliseconds
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.
asadmin undeploy --user admin wsit-enabled-fromjava asadmin undeploy --user admin wsit-enabled-fromwsdl