# Using Buffering to Create Asynchronous Methods and Callbacks

When a conversational web service's request method is called by multiple clients at the same time, a client might have to wait until its call, however short, has been processed by the web service. In addition, when a web service has completed processing multiple requests and needs to send multiple callback messages, it must wait for a message to be processed by the client before it can send the next callback.

For a conversational web service, and especially for a web service receiving high-volume traffic, it is recommended to always add buffers to the web service's methods and callbacks. When clients call a buffered method, the call is stored in a buffer and the client does not have to wait for the web service to handle the call. When a web service sends a callback, the message is stored in a buffer and the web service does not have to wait until the client processes the callback. You can add a message buffer to any method or callback, provided that the method or callback's parameters are serializable and the return type is void. You can also specify when and whether to retry an invocation of the buffer if it fails.

This topic explains how to add a message buffer to a method or callback of your web service or Java control, how to use message buffers with methods and callbacks, how to make parameters serializable, and how to control retry behavior.

## Adding a Message Buffer

You can only add message buffers to methods and callbacks whose parameters are serializable and whose return type is void. When a method or callback with a message buffer is invoked, the message representing the method or callback invocation is placed in a queue to be delivered to the web service, Java control, or client when it is available. Since the queue has no information about the semantics of the message or the destination software component, it cannot return anything meaningful to the caller. And since the queue must always return void, any methods or callbacks that are buffered must return void.

Although you can add message buffers to the methods and callbacks of any web service, it is important to understand what happens when you add message buffers. The queues that provide the buffering always exist on your end of the wire. WebLogic Server has no way to cause configuration actions like message buffering in a remote client's infrastructure. The representation of a web service in Design View reinforces this by drawing the message buffer "spring" icons on the end of the wire closest to the web service. For Java controls, you add message buffers to the methods as you design the Java control, but you add message buffers to the callbacks when you add an instance of this control to a web service (or another Java control), reflecting that you define in the web service how to handle a Java control's callback.

To Add a Message Buffer to a Web Service

1. In the Design View of the Web Service, select the method or callback you want to buffer.
2. In the Properties pane, navigate to the message-buffer property.
3. Set the enabled attribute to true. WebLogic Workshop adds the Javadoc tag @common:message-buffer enabled-true to the Javadoc comment preceding the method or callback in the source code.

   > Note: In previous releases, the @common:message-buffer tag was known as the @jws:message-buffer tag. This tag is still supported for backward compatibility.

To Add a Message Buffer to a Java Control's Method

1. In the Design View of the Java control, select the method you want to buffer.
2. In the Properties pane, navigate to the message-buffer property.
3. Set the enabled attribute to true. WebLogic Workshop adds the Javadoc tag @common:message-buffer enabled-true to the Javadoc comment preceding the method or callback in the source code.

To Add a Message Buffer to a Java Control's Callback

1. In the Design View of the Web Service, click the name of the Java control callback you want to buffer. WebLogic Workshop goes to the Web Service's code in Source View that implements the callback.
2. In the Properties pane, navigate to the message-buffer property.
3. Set the enabled attribute to true. WebLogic Workshop adds the Javadoc tag @common:message-buffer enabled-true to the Javadoc comment preceding the method or callback in the source code of the Web Service.

## Using Message Buffers on Methods

If you add a message buffer to a method, incoming messages (that is, invocations of the method) are buffered on the local machine. The method invocation returns to the client immediately. This prevents the client from waiting until your web service or Java control processes the request. Because the buffering occurs on your end of the wire, the client still must wait for the network roundtrip even though it will return a void result. But the client does not have to wait for your web service or Java control to process the message.

### Determining the Execution Order of Methods

When a web service or Java control defines buffered (asynchronous) methods, neither the designer nor the client can make any assumptions about the order in which methods should be executed.

This is especially true when defining both buffered and non-buffered methods in the same web service or Java control. Invocations of synchronous methods are guaranteed to be in order of arrival. But if buffered methods are also defined, you cannot determine when their invocations will occur relative to the synchronous methods.

## Using Message Buffers on Callbacks

When you invoke a callback, your web service or Java control is acting as the caller, that is your service or control is sending an outgoing message (a callback invocation) to the client, which responds with an incoming message containing the callback's return value.

If you add a message buffer to a callback of a web service, outgoing messages (that is, invocations of the callback) are buffered on the local machine and the callback invocation returns immediately. This prevents your service from having to wait while the message is sent to the remote server and the (void) response is received. In other words, your web service doesn't have to wait for the network roundtrip to occur. If you add a message buffer to a callback of a Java control, the buffer is implemented by the web service. The Java control must still wait for the network roundtrip even though it will return a void result, but the Java control does not have to wait for the web service to process the message.

## All Parameters Must Be Serializable

All objects that are passed as method parameters to buffered methods or callbacks must be serializable. Method and callback invocations are placed in the queue through Java serialization.

Many built in Java classes are already serializable, and most other classes can be made serializable very easily by adding implements java.io.Serializable to the class declaration.

For example, if the Person class in the following example is passed as a method parameter, just add the bold text to the declaration to allow the class to be passed as a parameter to buffered methods or callbacks.

    public static class Person implements java.io.Serializable
    {
        public String firstName;
        public String lastName;
    }

## Controlling Retry Behavior

You can control the retry behavior of WebLogic Server during design or at runtime.

To Specify Retry Behavior During Design

1. Select the asynchronous method or callback as described above.
2. In the Properties pane, navigate to the message-buffer property.
3. Set the retry-count attribute to determine the number of times that redelivery is attempted.
4. Set the retry-delay attribute to determine the delay between delivery attempts.

To Specify Retry Behavior at Runtime

You can control the retry behavior of WebLogic Server at runtime from within a buffered method. If the method is invoked but you do not wish to service the request immediately, you can request that WebLogic Server reissue the request at a later time. You do this by throwing a weblogic.jws.RetryException from within the buffered method.

The constructors for the RetryException class, described in the following list, take a retry delay as an argument:

RetryException("Try sooner", 5)

The second argument is a long, specifying the number of seconds to delay before retrying.

RetryException("Try later", "5 days")

The second argument is a String specifying the delay before retrying.

RetryException("Try default", RetryException.DEFAULT_DELAY)

Passing the DEFAULT_DELAY constant specifies that the value of the retryDelay attribute of the @jws:message-buffer tag should be used.

Related Topics

Getting Started with Web Services

Getting Started: Using Asynchrony to Enable Long-Running Operations

Designing Conversational Web Services