Developing a WS-ReliableMessaging solution using WebSphere Message Broker V8

The Web Services Reliable Messaging (WS-RM) specification enables two SOAP-based systems to reliably send messages to each other over an unreliable HTTP link. WebSphere Message Broker V8 now supports the use WS-RM in message flows, and this article shows you how to configure WS-RM in a solution where a JAX-WS web service client and a Microsoft .NET client send SOAP/HTTP messages to Message Broker.

Graham Haxby (grahahax@uk.ibm.com), Software Engineer, IBM

Photo of Graham HaxbyGraham Haxby is a Software Engineer on the WebSphere Message Broker development team at the IBM Software Lab in Hursley, United Kingdom. He currently works on Message Broker Toolkit and Message Broker Explorer development. He has experience in reliability testing and Web services development and testing, and he's been employed by IBM since 2006. You can contact Graham at grahahax@uk.ibm.com.



Sanjay Nagchowdhury (sanjay_nagchowdhury@uk.ibm.com), Software Developer, IBM

Photo of Sanjay NagchowdhurySanjay Nagchowdhury is a software developer on the WebSphere Message Broker development team at the IBM Hursley Software Lab in the UK. You can contact Sanjay at sanjay_nagchowdhury@uk.ibm.com.



29 February 2012

Also available in Chinese

Introduction

This article demonstrates WS-RM support in IBM® WebSphere® Message Broker V8 (hereafter referred to as Message Broker) by invoking a Message Broker flow from JAX-WS and Microsoft® .NET WCF clients. The article includes an overview of WS-RM for those who are not familiar with the protocol, and shows you how to enable WS-RM for both clients and services. Building web service clients and services is not covered, as you can download the resources described in the article.

What is WS-RM?

WS-RM is an OASIS standard that enables two systems to reliably send SOAP messages to each other and ensure delivery, even if the destination endpoint is temporarily unavailable or a network connection fails. WS-RM overcomes these problems by defining how messages should be sent again if they were not delivered successfully, and it prevents duplicate messages from being delivered to the destination endpoint.

Figure 1. WS-RM overview
WS-RM overview

The WS-RM specification defines two endpoints -- RM Source (RMS) and RM Destination (RMD) -- that ensure messages are sent reliably. Reliability is achieved using sequences. Before the messages are sent, RMS and RMD perform a message exchange to establish a sequence, which is identified by a unique identifier and consists of a sequence of messages that are numbered starting from 1. RMD uses the message number to verify and ensure delivery.

RMS sends each message one or more times to RMD, and it sends back an acknowledgment for each message it receives. If RMS does not receive an acknowledgment that a message was received by RMD, it sends the message again until an acknowledgment is received. The figure above shows RMS and RMD being used to send SOAP messages reliably:

  1. The Application Source sends a message for reliable transfer.
  2. RMS accepts the message and transmits it one or more times.
  3. After accepting the message, RMD acknowledges it.
  4. RMD delivers the message to the Application Destination.

When all messages in a sequence have been successfully transmitted to RMD, RMS indicates that the sequence is terminated. RMS and RMD are not visible at the application level, but are used to ensure that messages are transmitted again if they have been lost or undelivered. In a two-way WS-RM scenario in which both requests and responses are delivered reliably, there will be an RMS and an RMD on the client and on the server.

Exchanging messages

The figure below shows an example of messages being exchanged between RMS and RMD endpoints and shows the benefits of using WS-RM. In this message exchange, a sequence of messages (assume they are one-way for this example) are sent between RMS and RMD. In this example, when Message 2 is initially sent by RMS, it is never received by RMD, so RMD only sends a sequence acknowledgement for Message 1 and Message 3. RMS then sends Message 2 again, and this time RMD receives it and sends an acknowledgment for all three messages. RMS then terminates the sequence:

Figure 2. Example: Message Exchange between RMS and RMD
Example: Message Exchange between RMS and RMD

Configuring Message Broker

In Message Broker V8, WS-RM support has been added to the SOAP Nodes, and configuring WS-RM on a message flow is an administrative task. The message flow developer does not need to be aware that the flow may be enabled for WS-RM as it does not affect the flow design. The administrator configures WS-RM using policy sets. Prior to Message Broker V8, policy sets were used for configuring WS-Security only. In V8, you can configure a policy set for WS-Security or for WS-RM. Within the policy set, an administrator can configure whether messages should be received in order and can define client compatibility settings. You can apply policy sets at the flow or node level using the BAR Editor in the Message Broker Toolkit or Message Broker Explorer. A policy set can be applied for providers (SOAPInput, SOAPReply) or consumers (SOAPRequest). A WS-RM enabled flow can also receive requests that are not using WS-RM headers. Although WS-RM is a message level protocol, you can use it only for SOAP/HTTP messages in Message Broker, since SOAP/JMS is already considered reliable. Message Broker supports both WS-RM V1.0 and B1.1. The default policy set uses WS-RM V1.1.

You can configure a policy set using the Policy Set Editor, which you can launch from within Message Broker Explorer:

  1. Right-click on your broker, and select Properties:
    Figure 3. Select Broker Properties
    Select Broker Properties
  2. In the Properties window, select Security and Policy => Policy Sets to open the Policy Set Editor:
    Figure 4. Open Policy Set Editor
    Open Policy Set Editor
  3. In the Policy Set Editor, you can configure settings for WS-Security and/or WS-RM. A default policy set is provided for WS-Security (WSS10Default) and for WS-RM (WSRMDefault). No configuration is necessary for WS-RM in a policy set binding:
    Figure 5. Selecting WS-RM in the Policy Set Editor
    Selecting WS-RM in the Policy Set Editor

You can specify if messages should be delivered in order (the default) or not. You can also set client compatibility. By default, outbound requests are sent using WS-RM V1.1. However, if you have a consumer flow containing a SOAPRequest node that needs to send outbound requests to a .NET WCF service, then you can select that option, which sends the outbound requests using WS-RM V1.0):

Figure 6. Setting WS-RM options in the Policy Set Editor
Setting WS-RM options in the Policy Set Editor

You can apply the policy set at a message flow level or node level using the BAR Editor:

Figure 7. Apply Policy Set to SOAP Input node
MBX

You can export and import policy sets. For example, you may have tested your flow and policy on a test system, and you now want to run it on a production system. Message Broker command line tools enable you to export and import your policy sets:

  1. To export the policy set, use mqsireportproperties. For example:
    mqsireportproperties MB8BROKER -c PolicySets -o TestPolicySet 
        -n ws-rm -p TestPolicySet.xml
  2. To import the policy set, use mqsicreateconfigurableservice and mqsichangeproperties. For example:
    mqsicreateconfigurableservice MB8BROKER -c PolicySets -o TestPolicySet 
    
    mqsichangeproperties MB8BROKER -c PolicySets -o TestPolicySet 
        -n ws-rm -p TestPolicySet.xml

InOrder delivery

If InOrder is true in the policy set (which is the default), messages for each individual sequence will be delivered in the same order that they have been sent by the Application Source. For a provider flow (using SOAP Input and SOAP Reply nodes), this means that messages will be processed in the same order in which they were sent by the client. If a message received by Message Broker has a message number higher than any preceding messages in the same sequence, it will not be processed by the SOAP Input node until the preceding messages have been received. The behaviour when InOrder is true is shown below:

Figure 8. Behaviour when InOrder is true
Behaviour when InOrder is true

If InOrder is false, then messages for a sequence can be delivered in a different order than in which they were sent by the Application Source. For a provider flow using SOAPInput and SOAPReply nodes, messages will therefore be processed as soon as they are received by Message Broker. If a message received by Message Broker has a message number higher than any preceding messages in the same sequence, it will be processed by the SOAPInput node before the preceding messages have been processed. The behaviour when InOrder is not specified is shown below:

Figure 9. Behaviour when InOrder is not specified
Behaviour when InOrder is not specified

Delivery assurance

When WS-RM is enabled for a provider flow, a message is processed by the SOAPInput node exactly once. If a message has already been processed by the provider flow and RMS sends the same message again, the message is not propagated down the message flow because it is a duplicate. The response that had been previously sent is automatically sent without the message being reprocessed by the flow, as shown below:

Figure 10. Delivery assurance
Delivery assurance

Example WS-RM scenario

To demonstrate how to use WS-RM with Message Broker, you can use a simple message flow that receives web service requests from clients and sends responses. You could extend the flow to forward the requests to a back-end service, but for simplicity, the flow receives web service requests using a SOAPInput node, formulates responses in a Compute node, and sends responses using a SOAPReply node. The example will first show that if the clients and flow are not using WS-RM, then messages can be lost if there is a network outage. You will then enable WS-RM on the clients and flow, and demonstrate that even if there a network outage occurs, the messages will reach their destination once connectivity is restored.

This example uses the simple message flow shown below, which receives WS-RM sequences from .NET web service clients (denoted by black arrows) and JAX-WS clients (denoted by blue arrows). The flow is intentionally kept simple to illustrate WS-RM.

Figure 11. SOAPInput and SOAPReply nodes receiving requests from a .NET client and a JAX-WS web service client
SOAPInput and SOAPReply nodes receiving requests from a .NET client and a JAX-WS web service client

Message Broker using WS-RM

  1. Download the WMB_BankService_PI.zip Message Broker project at the bottom of the article.
  2. Start the Message Broker Toolkit.
  3. Import the project, by selecting File => Import. In the Import window, select Other => Project Interchange and then click Next.
  4. Browse to the Message Broker project file that you downloaded. Select BARFiles and BankService, and then click Finish.
  5. After importing the project, you should see the application shown below.
  6. Deploy the supplied Bank.bar file to a Message Broker execution group.
Figure 12. Message Broker Bank Service
Message Broker Bank Service

.NET WCF client using WS-RM

If you have Visual Studio 2010 or later, you can download the solution in BankClientSln.zip at the bottom of the article and run the .NET client from your development environment. Alternatively, you can download BankClient.zip and extract the 32-bit client BankClient.exe and the configuration file BankClient.exe.config.

The .NET client was produced by creating a C# console application and importing the WSDL as a service reference. The client then invokes each operation exposed in the Message Broker service flow. The code in the main method is shown below. Four operations are invoked in a try/catch block that will catch exceptions when a network outage is demonstrated later in this article.

BankDelegateClient bc = new BankDelegateClient();
try
{
    bc.orderNewChequeBook(123456);
    Console.WriteLine("Check Book Ordered");
    bc.depositFunds(1, 2, 3);
    Console.WriteLine("Funds Deposited");
    int intResponse = bc.checkBalance(123456);
    Console.WriteLine("Balance is: " + intResponse);
    Boolean boolResponse = bc.creditCheck("Message", "Broker");
    Console.WriteLine("Got creditCheck response of: " + boolResponse);
}
catch (Exception e)
{
    Console.WriteLine("I ran into some trouble:\n" + e);
}
Console.WriteLine("Press ENTER to exit.");
Console.ReadLine();

Sending non-RM messages from Microsoft .NET to Message Broker

  1. First, send a message from .NET to Message Broker without using WS-RM. Start the .NET client either from your development environment, or by running BankClient.exe. You should see output containing the responses received from Message Broker for each operation that was invoked:
    Figure 13. BankClient.exe
    BankClient.exe
  2. If you'd like to see the wire messages or simulate a network outage, you need to tunnel your requests though a monitor like tcpMon, or the TCP/IP Monitor in the Message Broker Toolkit. By default, the Message Broker listener starts on Port 7800 (you can check the event log to confirm this). Set up your monitor to listen on Port 7801 and tunnel to Port 7800.
  3. Next, edit the config file (either BankClient.exe.config or app.config using Visual Studio) using either a text editor or the Microsoft Service Configuration Editor. Change the endpoint address from 7800 to 7801. If you're familiar with .NET configuration, you may want to add a clientVia behaviour instead.
    Figure 14. Update endpoint address in Service Configuration Editor
    Update endpoint address in Service Configuration Editor
  4. Run the Bank Client application again and notice the four request and response messages:
    Figure 15. SOAP messages sent between client and service
    SOAP messages sent between client and service
  5. Stop the monitor and run the Bank Client app once more. Notice how the client gets an EndpointNotFoundException, since there is no possible way to recover once the tunnel is reestablished!
    Figure 16. Error message is returned when there was a network outage
    Error

Enabling WS-RM on a Message Broker flow

You can enable WS-RM in the BAR File Editor by selecting the WSRMDefault policy, as shown in Figure 7. You must redeploy your flow to the execution group afterwards for changes to take effect.

Sending WS-RM messages from a .NET client to a Message Broker service

  1. First, enable WS-RM in the .NET config file. The supplied file already contains a binding configured to use WS-RM, so simply change the endpoint to use BankPortBindingRM rather than BankPortBinding. The screen shot below shows the Microsoft Service Configuration Editor, but you can also use a text editor:
    Figure 17. BankClient configuration
    BankClient configuration
  2. Start with your tunnel enabled and run the Bank Client app. In addition to your application message that you saw without WS-RM, there are now WS-RM protocol messages such as CreateSequence.
  3. Stop the monitor and rerun the Bank Client app. Notice that instead of generating an error, the Bank Client app waits, because it was unable to establish a connection to Message Broker and is attempting to send the message again.
  4. Enable the tunnel once more. The .NET client appears to spring into action and complete each operation as if there had never been an interruption or problem:
    Figure 18. WS-RM messages are sent between client and service
    WS-RM messages are sent between client and service

JAX-WS client using WS-RM

Importing the JAX-WS web service client project into Rational Application Developer

A JAX-WS web service client project has been supplied that you can import into Rational Application Developer V8 and deploy to an application server.

  1. Download the Rational Application Developer projects in RAD_BankClient_Projects.zip at the bottom of the article.
  2. Unzip the zip file.
  3. Start Rational Application Developer.
  4. Import the projects by selecting File => Import. In the Import window, select General => Existing Projects into Workspace, and then click Next.
  5. Browse to the directory where you unzipped the zip file. Select BankClient and BankClientEAR, select Copy projects into workspace, and then click Finish.
  6. After importing the projects, you should see the application shown below, along with some JSP pages to invoke the Message Broker web service from the application server:
    Figure 19. Rational Application Developer Bank Client Application
    Rational Application Developer Bank Client Application

Sending non-RM messages from a JAX-WS web service client to a Message Broker service

  1. First, deploy the JAX-WS web service client to your application server. To do this in Rational Application Developer, select the Servers tab, right-click WebSphere Application Server V8 at localhost, and select Add and Remove.
  2. In the Add and Remove window, select BankClientEAR, click Add, and then click Finish. You should see the JAX-WS web service client deployed to your application server, as shown below:
    Figure 20. Deployed Bank Client
    Deployed Bank Client
  3. You can send a message to the Bank Service running on Message Broker by running the TestClient. You will find TestClient.jsp under BankClient => WebContent => sampleBankPortProxy.
  4. Right click on TestClient.jsp, select Run as, and then select Run on server.
  5. Select the application server and then click Finish.

    The TestClient application UI is now shown. First, send a message that does not use WS-RM and use a TCP/IP Monitor to view the message that is sent. You can simulate a network outage using the TCP/IP Monitor, and you can use the TCP/IP Monitor or tcpMon in the Message Broker Toolkit. The Message Broker listener starts by default on port 7800 (you can check the event log to confirm this). Set up your monitor to listen on 7801 and tunnel to 7800.

  6. In the TestClient interface, update the endpoint to http://localhost:7801/WebServiceProject/BankService, select checkBalance, and click Invoke as shown below. The balance is returned in the Result window:
    Figure 21. Invoke the checkBalance operation
    Invoke the checkBalance operation
  7. In the TCP/IP Monitor, you will see a request and response message for the checkBalance operation, as shown below:
    Figure 22. Request/Response shown in TCP/IP Monitor
    Request/Response shown in TCP/IP Monitor
  8. Stop the TCP/IP Monitor to simulate a network outage and invoke the checkBalance operation again. This time, instead of the balance being returned, you will see an error returned in the Result window:
    Figure 23. Error returned when there is a network outage
    Error returned when there is a network outage

Enabling WS-RM on the JAX-WS web service client

To enable WS-RM on the JAX-WS web service client, you need to apply a policy set to it. The policy set has been provided.

  1. Download WAS_WSRM_PolicySet.zip at the bottom of the article.
  2. Import the policy set: In Rational Application Developer, select File => Import and then select Web services => WebSphere policy sets.
  3. Browse to the downloaded policy set zip file and click Finish.

Next, apply the policy set to the web service client:

  1. Select BankClient => Services => Clients, right-click the Clients endpoint, and select Manage Policy Set Attachment.
  2. Select the service name and click Next.
  3. Under Application, click Add.
  4. For Policy set, select WSReliableMessaging default and then click OK. Ignore the warning that is displayed for WS-I Basic Profile 1.1.
  5. Click Finish.

For more information on how to apply a policy set to a web service client, see the developerWorks article Applying Web Services Reliable Messaging (WS-RM) to a web service.

Your JAX-WS client will be republished automatically to the application server. It is now configured to use WS-RM.

Sending RM messages from the JAX-WS web service client to Message Broker

  1. Relaunch the TestClient and ensure that the endpoint used by the TestClient is http://localhost:7801/WebServiceProject/BankService. Click Update. With the TCP/IP Monitor still stopped, invoke the checkBalance operation. After a few seconds, start the TCP/IP Monitor. You will see that the request was successful and a balance is returned.
  2. In the TCP/IP Monitor, you will see extra WS-RM protocol messages being sent alongside the application messages, such as CreateSequence sent by the client and CreateSequenceResponse returned by the service:
    Figure 24. WS-RM protocol messages are now sent by client and service running on Message Broker
    WS-RM protocol messages are now sent by client and service running on Message Broker

Conclusion

This article demonstrated the new WS-RM functionality for SOAP/HTTP in WebSphere Message Broker V8, and showed how Message Broker interoperates with JAX-WS or .NET WCF clients using WS-RM. By first simulating a network outage using a TCP/IP tunnel, you saw how an unreliable transport causes a SOAP/HTTP request to fail, requiring any retry logic to be implemented in the client application. Enabling WS-RM on client and service enables recovery from the error without additional coding by the client or web service provider. The scenario was simple and only demonstrated the error case when the endpoint was unavailable from the beginning, but WS-RM enables recovery at any point in the sequence, including a missing application request or an asynchronous response.


Downloads

DescriptionNameSize
Code sampleBankClient.zip5 KB
.NET Bank Client solution for Visual Studio 2010BankClientSln.zip114 KB
RAD zip file containing the Bank Client projectsRAD_BankClient_Projects.zip72 KB
WAS policy setWAS_WSRM_PolicySet.zip2 KB
WMB zip file containing the Bank Service projectsWMB_BankService_PI.zip26 KB

Resources

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere
ArticleID=800342
ArticleTitle=Developing a WS-ReliableMessaging solution using WebSphere Message Broker V8
publish-date=02292012