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.
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
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
To Add a Message Buffer to a Java Control's Callback
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.
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.
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 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;
}
You can control the retry behavior of WebLogic Server during design or at runtime.
To Specify Retry Behavior During Design
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:
Getting Started with Web Services
Getting Started: Using Asynchrony to Enable Long-Running Operations