Table of Contents
This chapter describes the concept of reliable messaging and how to configure it.
Reliable messaging is intended for creating more reliable web services with high quality of service (QoS). Reliability is measured by the ability to transmit a message from one place to another. The main purpose of reliable messaging is to guarantee application message transmission from/to each end of a web service.
Reliable messaging technology guarantees that messages are transmitted to both ends of the web service exactly once and in order upon request. It is used to recover a message that failed to be transmitted. If a message gets lost during transmission, the sender attempts to re-transmit the message until it receives an acknowledgement from the recipient. If the message arrives in the wrong order, the system that receives the message modifies the order and transmits the message to the web service endpoint in the correct order.
The following are the specifications for reliable messaging.
Reconsider using reliable messaging if the following problems occur.
If a communication failure causes an unavailable network or connection drop
If an application message gets lost during transmission.
If application messages are not transmitted in the correct order when the ordered delivery option is used.
Also consider the following strengths and weaknesses of reliable messaging.
Reliable messaging guarantees that a message is transmitted from a source to a destination exactly once. If the ordered delivery of the messages has been set, the messages will be transmitted in order.
Transmitting a web service message through reliable messaging may degrade the overall performance of the web service. Using the ordered delivery option will degrade performance.
A client that does not use reliable messaging is not interoperable with a web service that uses it.
WS-reliable messaging can be configured on a server by using WSDL or Java class.
To implement WS-Reliable Messaging in WSDL, configure the web service policy in the WSDL document and use it to create a web service through the wsimport tool.
The following are the steps for configuring WS-Reliable Messaging in the WSDL file according to the web service policy setting.
Set the following value to PolicyAssertion.
<wsrm:RMAssertion xmlns:wsrm="http://schemas.xmlsoap.org/ws/2005/02/rm/policy" />
Set the following value to PolicyAssertion to guarantee ordered delivery.
<rmp:Ordered xmlns:rmp="http://sun.com/2006/03/rm" />
The following is the WSDL file with the previous settings.
[Example 15.1] << AddNumbers.wsdl >>
<?xml version="1.0" ?>
<definitions name="AddNumbers" targetNamespace="http://example.org"
xmlns:tns="http://example.org" xmlns="http://schemas.xmlsoap.org/wsdl/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns:wsrm="http://schemas.xmlsoap.org/ws/2005/02/rm/policy"
xmlns:wsaw="http://www.w3.org/2006/05/addressing/wsdl"
xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/
oasis-200401-wss-wssecurity-utility-1.0.xsd"
xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy">
<wsp:UsingPolicy />
<wsp:Policy wsu:Id="AddNumbers_policy">
<wsp:ExactlyOne>
<wsp:All>
<wsaw:UsingAddressing />
<wsrm:RMAssertion>
<wsrm:InactivityTimeout Milliseconds="600" />
<wsrm:AcknowledgementInterval Milliseconds="200" />
</wsrm:RMAssertion>
</wsp:All>
</wsp:ExactlyOne>
</wsp:Policy>
<types>
<xsd:schema xmlns="http://www.w3.org/2001/XMLSchema"
elementFormDefault="qualified"
targetNamespace="http://example.org">
<element name="addNumbersResponse" type="tns:addNumbersResponse" />
<complexType name="addNumbersResponse">
<sequence>
<element name="return" type="xsd:int" />
</sequence>
</complexType>
<element name="addNumbers" type="tns:addNumbers" />
<complexType name="addNumbers">
<sequence>
<element name="arg0" type="xsd:int" />
<element name="arg1" type="xsd:int" />
</sequence>
</complexType>
</xsd:schema>
</types>
<message name="addNumbers">
<part name="parameters" element="tns:addNumbers" />
</message>
<message name="addNumbersResponse">
<part name="result" element="tns:addNumbersResponse" />
</message>
<portType name="AddNumbersPortType">
<operation name="addNumbers">
<input message="tns:addNumbers" name="add" />
<output message="tns:addNumbersResponse" name="addResponse" />
</operation>
</portType>
<binding name="AddNumbersBinding" type="tns:AddNumbersPortType">
<wsp:PolicyReference URI="#AddNumbers_policy" />
<soap:binding transport="http://schemas.xmlsoap.org/soap/http"
style="document" />
<operation name="addNumbers">
<soap:operation soapAction="" />
<input>
<soap:body use="literal" />
</input>
<output>
<soap:body use="literal" />
</output>
</operation>
</binding>
<service name="AddNumbersService">
<port name="AddNumbersPort" binding="tns:AddNumbersBinding">
<soap:address location="REPLACE_WITH_ACTUAL_URL" />
</port>
</service>
</definitions>
To configure WS-Reliable Messaging in Java class, use the '-policy' option of the wsgen console tool to obtain the wsit-endpoint.xml file.
$ wsgen fromjava.server.AddNumbersImpl -d web/WEB-INF -policy service-config.xml
The following is the service-config.xml file.
[Example 15.2] << service-config.xml >>
<?xml version="1.0" encoding="UTF-8"?>
<web-services-config xmlns="http://www.tmaxsoft.com/xml/ns/jeus">
<policy>
<endpoint-policy-subject>
<addressing-policy/>
<rm-policy>
<inactivityTimeout>600000</inactivityTimeout>
<acknowledgementInterval>1000</acknowledgementInterval>
</rm-policy>
</endpoint-policy-subject>
</policy>
</web-services-config>
There are no additional settings for WS-Reliable Messaging on the client side. JEUS web services automatically provide a suitable environment for WS-Reliable Messaging by interpreting the WS-Reliable Messaging policy in WSDL of a remote web service at client runtime.
The implementation in a Java class is the same as that of JEUS 8 web service. The only difference is that the deployment descriptor file, 'wsit-endpoint.xml', is added to the 'WEB-INF' folder as a WAR or EAR package.
The following is an example of the service-config.xml file.
[Example 15.3] << service-config.xml >>
<?xml version="1.0" encoding="UTF-8"?>
<web-services-config xmlns="http://www.tmaxsoft.com/xml/ns/jeus">
<policy>
<endpoint-policy-subject>
<addressing-policy/>
<rm-policy>
<inactivityTimeout>600000</inactivityTimeout>
<acknowledgementInterval>1000</acknowledgementInterval>
</rm-policy>
</endpoint-policy-subject>
</policy>
</web-services-config>
Execute the following command to create a web service by using wsgen with the previous service-config.xml file.
$ ant build
When the web service is created successfully, the structure will look like the following.
web
|
+-- WEB-INF
|
+-- wsit-fromjava.server.AddNumbersImpl.xml
+-- classes
|
+-- fromjava.server.AddNumbersImpl
The wsit-fromjava.server.AddNumbersImpl.xml file is saved in the 'WEB-INF' folder as a WAR or EAR package.
To deploy the service, execute the following command.
$ ant deploy
After the web service is deployed successfully, create a client and invoke the service as in the following example.
$ ant run
...
run:
[java] ##########################################
[java] ### JAX-WS Webservices examples - wsit ###
[java] ##########################################
[java] Testing wsit webservices...
[java] Success!
...
BUILD SUCCESSFUL