Using Reliable Messaging

Download Docs

Site Map

Glossary

e-docs > WebLogic Server > Programming WebLogic Web Services > Using Reliable Messaging

Programming WebLogic Web Services

Using Reliable Messaging

The following sections describe how to use reliable messaging, both as a sender and a receiver of a SOAP message:

Overview of Reliable Messaging

Reliable messaging is a framework whereby an application running in one WebLogic Server instance can asynchronously and reliably invoke a Web Service running on another WebLogic Server instance.

Note: Reliable messaging works only between two WebLogic Server instances.

One WebLogic Server, called the sender, has an application that asynchronously invokes a Web Service operation running on a different WebLogic Server, called the receiver, by sending it a SOAP message that has reliable messaging information in the SOAP header. The Web Service operation being invoked has been configured for reliable messaging. Due to the asynchronous nature of the invoke, the sender does not immediately know whether the relevant operation has been invoked, but it has the guarantee that it will get one of two possible notifications:

The message has been received by the receiver.

Note: This does not mean that the Web Service operation on the receiver WebLogic Server was successfully invoked. For example, it is possible that the receiver receives the message and sends the appropriate notification to the sender, but then the receiver WebLogic Server crashes and the operation is never invoked. Because the sender has received notification that the message was received, it does not retry sending it, even though in this case the operation was never invoked.

The sender was unable to deliver the message.

The sender can either poll the receiver for notification, or register a callback to be notified. Eventually, either the sender receives a notification that the message was received, or it receives notification that the message was not delivered.

Reliable SOAP messaging is transport independent. By default, it uses HTTP/S. However, you can also use JMS if you configure the receiving Web Service appropriately and use the JMS port when the sender invokes the Web Service. For details on using JMS transport, see Using JMS Transport to Invoke a WebLogic Web Service.

Terminology and Architecture

The following terms are used in this section:

sender: The WebLogic Server instance that sends the reliable message.
sender application: The user application running in the sender that reliably invokes a Web Service operation running on the receiver.
sender runtime: The WebLogic Server code running on the sender that handles reliable messaging.
receiver: The WebLogic Server instance that receives a reliable message.
receiver Web Service: The Web Service running on the receiver that contains the operation configured to be invoked reliably.
receiver runtime: The WebLogic Server code running on the receiver that handles reliable messaging.

The following diagram describes the architecture of the reliable messaging feature.

The sender application invokes a reliable operation running on the receiver WebLogic Server.
The sender runtime saves the message in its persistent JMS store. The store can be either a JMS File or JDBC store.
The sender runtime sends the SOAP message to the receiver WebLogic Server.
The receiver runtime receives the message, checks for duplicates in its persistent JMS store, and if none are found, saves the message ID in store. If it finds a duplicate, the receiver ignores the message.
The receiver runtime immediately sends notification back to the sender that the message was received.
The receiver runtime invokes the reliable operation.
Because only void operations can be invoked reliably, the receiver does not return any values or exceptions to the sender.
The sender runtime removes the message from its persistent store so that the message does not get sent again.
The sender is configured to retry sending the message if it does not receive notification of receipt. You configure the number of retries, and amount of time between retries, of the sender using the Administration Console. Once sender runtime has resent the message the maximum number of retries, it removes the message from its store.
The sender runtime sends notification to the sender application (either via callbacks or polling) that either the message was received or that it was never successfully delivered.

Limitations

The reliable messaging feature has the following limitations:

Only Web Service operations that return void can be configured to be invoked reliably.
If the invoke of the Web Service operation fails, the exception will not be propagated to the sender application.

Using Reliable Messaging: Main Steps

The following procedure describes the main steps to use reliable messaging when invoking a WebLogic Web Service operation. The procedure describes configuration and code-writing tasks that take place in both the sender and receiver WebLogic Server instances.

Note: It is assumed that you have already implemented and assembled a WebLogic Web Service and you want to enable one or more of its operations to be invoked reliably. Additionally, it is assumed that you have already coded a server-side application (such as a servlet in a Web application) that invokes the Web Service in a non-reliable way and you want to update the application to invoke the Web Service reliably.

For details about these tasks, see Implementing WebLogic Web Services, Assembling WebLogic Web Services Using Ant Tasks, and Invoking Web Services.

Configure the reliable messaging attributes for the sender WebLogic Server instance (the WebLogic Server instance on which the sender application that will reliably invoke a Web Service is deployed.)
See Configuring the Sender WebLogic Server.
Configure the reliable messaging attributes for the receiver WebLogic Server instance (the WebLogic Server instance on which the reliable Web Service being invoked is deployed.)
See Configuring the Receiver WebLogic Server.
Update the build.xml file that contains the call to the servicegen Ant task, adding the <reliability> child element to the <service> element that builds your Web Service on the receiver WebLogic Server, as shown in the following example:

      <servicegen
         destEar="c:\myWebService.ear"
         warName="myWAR.war" 
         contextURI="web_services" >
         <service
             ejbJar="c:\myEJB.jar"
             targetNamespace="http://www.bea.com/examples/Trader"
             serviceName="TraderService"
             serviceURI="/TraderService"
             generateTypes="True"
             expandMethods="True" >
             <reliability duplicateElimination="True"
                          persistDuration="60"
             />
         </service>
     </servicegen>

For more information on the attributes of the <reliability> element, see servicegen.

Note: When you regenerate your Web Service using this build.xml file, every operation will be enabled for reliable invocation. If you want only certain operations to be invoked reliably, or you prefer not to regenerate your Web Service using servicegen, you can update the web-services.xml file of your WebLogic Web Service manually. For details, see Writing the Java Code to Invoke an Operation Reliably.

Re-run the servicegen Ant task to regenerate your Web Service that is running on the receiver WebLogic Server.
Re-run the clientgen Ant task, specifying the generateAsyncMethods="True" attribute, to generate a new Web Service-specific client JAR file that contains the asynchronous operation invocations. This new client JAR file will be used with the server-side application running in the sender WebLogic Server.
On the client application running on the sender WebLogic Server, update the Java code that invokes the Web Service to invoke it reliably.
See Writing the Java Code to Invoke an Operation Reliably.

Configuring the Sender WebLogic Server

This section describes how to configure reliable messaging attributes for a WebLogic Server instance in its role as a sender of a reliable message.

Note: Part of the reliable messaging configuration involves configuring JMS components. This includes creating, if they do not already exist, a JMS server and a JMS File or JDBC store.

The following table describes the reliable messaging attributes.

Table 10-1 Reliable Messaging Attributes for a Sender WebLogic Server

Attribute	Description
Store	The persistent JMS store used by WebLogic Server, in its role as a sender, to persist the reliable messages that it sends.
Default Retry Count	The default maximum number of times that the sender runtime should attempt to redeliver a message that the receiver WebLogic Server has not yet acknowledged. Default value is 10.
Default Retry Interval	The default minimum number of seconds that the sender runtime should wait between retries if the receiver does not send an acknowledgement of receiving the message, or if the sender runtime detects a communications error while attempting to send a message. Default value is 600.

Attribute

Description

Store

The persistent JMS store used by WebLogic Server, in its role as a sender, to persist the reliable messages that it sends.

Default Retry Count

The default maximum number of times that the sender runtime should attempt to redeliver a message that the receiver WebLogic Server has not yet acknowledged.

Default value is 10.

Default Retry Interval

The default minimum number of seconds that the sender runtime should wait between retries if the receiver does not send an acknowledgement of receiving the message, or if the sender runtime detects a communications error while attempting to send a message.

Default value is 600.

To configure these attributes:

Invoke the Administration Console by entering the following URL in your browser:
```
http://host:port/console
```
where
- host refers to the computer on which the Administration Server is running.
- port refers to the port number where the Administration Server is listening for connection requests. The default port number for the Administration server is 7001.
Create, if one does not already exist, a JMS server. For details, see Configuring a JMS Server.
Create, if one does not already exist, a JMS store. This can be either a JMS File store or a JMS JDBC store. For details, see JMS File Store Tasks and JMS JDBC Store Tasks.
Warning: The JMS Server with which this JMS store is associated cannot be targetted to a Migratable Target.
Click the Servers node in the left pane.
Select the WebLogic Server for which you want to configure reliable messaging in its role as a sender.
In the right pane, select the Services tab.
Select the Web Services tab.
Select the JMS store from the Store drop-down list that will contain WebLogic Server's reliable messages when acting as a sender.
Enter the default maximum number of times the sender WebLogic Server should attempt to resend a message in the Default Retry Count field.
Enter the default minimum number of seconds that the sender WebLogic Server should wait between retries in the Default Retry Interval field.
Enter the default minimum number of seconds that the receiver of the reliable message should persist the history of the message in its JMS store in the Default Time to Live field
Warning: This value should be larger than the corresponding value of any Web Service operation being invoked reliably. Later sections describe how to configure his value in the Web Service's web-services.xml file by updating the persist-duration attribute of the <reliable-delivery> subelement of the invoked <operation>.
Click Apply.

Configuring the Receiver WebLogic Server

This section describes how to configure reliable messaging attributes for a WebLogic Server instance in its role as a receiver of a reliable message.

Note: Part of the reliable messaging configuration involves configuring JMS components. This includes creating, if they do not already exist, a JMS server and a JMS File or JDBC store.

The following table describes the reliable messaging attributes.

Table 10-2 Reliable Messaging Attributes for a Receiver WebLogic Server

Attribute	Description
Store	The persistent JMS store used by the receiver WebLogic Server to persist the history of a reliable message sent by a sender.
Default Time To Live	The default number of seconds that the receiver of the reliable message should persist the history of the reliable message in its store. If the Default Time to Live number of seconds have passed since the message was first sent, the sender will not resend a message with the same message ID. If a sender cannot send a message successfully before the Default Time To Live number of seconds has passed, the sender will report a delivery failure. The receiver, after recovering from a crash, will not dispatch saved messages that have expired.

Attribute

Description

Store

The persistent JMS store used by the receiver WebLogic Server to persist the history of a reliable message sent by a sender.

Default Time To Live

The default number of seconds that the receiver of the reliable message should persist the history of the reliable message in its store.

If the Default Time to Live number of seconds have passed since the message was first sent, the sender will not resend a message with the same message ID.

If a sender cannot send a message successfully before the Default Time To Live number of seconds has passed, the sender will report a delivery failure.

The receiver, after recovering from a crash, will not dispatch saved messages that have expired.

To configure these attributes:

Invoke the Administration Console by entering the following URL in your browser:
```
http://host:port/console
```
where
- host refers to the computer on which the Administration Server is running.
- port refers to the port number where the Administration Server is listening for connection requests. The default port number for the Administration server is 7001.
Create, if one does not already exist, a JMS server. For details, see Configuring a JMS Server.
Create, if one does not already exist, a JMS store. This can be either a JMS File store or a JMS JDBC store. For details, see JMS File Store Tasks and JMS JDBC Store Tasks.
Warning: The JMS Server with which this JMS store is associated cannot be targetted to a Migratable Target.
Click the Servers node in the left pane.
Select the WebLogic Server for which you want to configure reliable messaging in its role as a receiver.
In the right pane, select the Services tab.
Select the Web Services tab.
Select the JMS store from the Store drop-down list that will contain WebLogic Server's reliable messages when acting as a receiver.
Enter the default minimum number of seconds that the receiver of the reliable message should persist the history of the message in its persistent JMS store in the Default Time to Live field.
Note: Later sections in this document describe how each Web Service operation can override this default value in its web-services.xml file by setting the persist-duration of the <reliable-delivery> sublement of the corresponding <operation> element.
Click Apply.

Writing the Java Code to Invoke an Operation Reliably

Writing the Java code to invoke a Web Service operation reliably from a sender application is very similar to invoking an operation asynchronously, as described in Writing an Asynchronous Client. The asynchronous invoke of an operation is split into two methods: startOperation() and endOperation().

In addition to the standard asynchronous client Java code, to invoke an operation reliably you must:

enable reliable delivery in your client application with the AsyncInfo.setReliableDelivery() method
create and set a listener to listen for the results of a reliable operation invocation with the AsyncInfo.setResultListener(listener) method. The listener class implements the ResultListener interface, which in turn defines the onCompletion() listener callback method in which you define what happens when the asynchronous reliable operation invocation completes.

The following example shows a sender application that reliabley invokes the myMethod operation of the EchoService Web Service. The example shows how to split the invoke of this operation into two asynchronous invokes using the following two methods: startMyMethod() and endMyMethod(). You tell clientgen Ant task to generate these two methods in the stubs by specifying the generateAsyncMethods attribute.

/**
 * @author Copyright (c) 2002 by BEA Systems. All Rights Reserved.
 */

import weblogic.utils.Debug;

import weblogic.webservice.async.FutureResult;
import weblogic.webservice.async.AsyncInfo;
import weblogic.webservice.async.ResultListener;
import weblogic.webservice.async.InvokeCompletedEvent;

public final class ReliableSender {

  public String echoString(String f) {
    try {
      EchoService echoService = new EchoService_Impl();
      EchoServicePort echoPort = echoService.getEchoServicePort();

      //async poll style with reliable delivery
      AsyncInfo asyncCtx = new AsyncInfo();
      RMListener listener = new RMListener();
      asyncCtx.setReliableDelivery();
      asyncCtx.setResultListener(listener);
      FutureResult futureResult = echoPort.startMyMethod(f, asyncCtx);

      while( !futureResult.isCompleted()) {
        Debug.say("async polling  ...");
        Thread.sleep(300);
      }

      String result = echoPort.endMyMethod(futureResult);
      Debug.say("poll result: " + result);

      return result;

    } catch (Exception e) {
      Debug.say("Exception in ReliableSender: " + e);
    }
    return null;
  }

  class RMListener implements ResultListener {
      public void onCompletion(InvokeCompletedEvent event) {
          System.out.println("onCompletion called");
      }
  }
}

Updating the web-services.xml File Manually for Reliable Messaging

If you regenerated your Web Service using the servicegen Ant task, every operation is enabled for reliable invocation. If you want only certain operations to be invoked reliably, or you prefer not to regenerate your Web Service using servicegen, you can update the web-services.xml file of your WebLogic Web Service manually, as described in this section.

The web-services.xml file is located in the WEB-INF directory of the Web application of the Web Services EAR file. See The Web Service EAR File Package for more information on locating the file.

To update the web-services.xml file to enable reliable messaging for one or more operations:

Open the file in your favorite editor.
For each operation for which you want to enable reliable messaging, add a <reliable-delivery> subelement. Specify the following optional attributes of the <reliable-delivery> element to configure the specific reliable delivery features of the operation:
- duplicate-elimination - Boolean that specifies whether the WebLogic Web Service should ignore duplicate invokes from the same sender application. Default value is True.
- persist-duration - Integer value that specifies the default minimum number of seconds that the Web Service should persist the history of the reliable message (received from the sender that invoked the Web Service) in its storage. When the persist-duration number of seconds have elapsed, the receiver WebLogic Server deletes the history of the message from its store. This attribute overrides the default server value you set in Configuring the Receiver WebLogic Server. The default if neither is set is 360 seconds.