Asynchronous Methods

Asynchronous methods and callbacks return immediately to the caller, allowing the calling web service or application to continue other processing until the result of the operation is complete. Asynchronous methods and callbacks are also referred to as being buffered, because the asynchrony is accomplished using message buffers. Buffering methods and callbacks can help your web services handle high loads.

Message buffers may only be added to methods and callbacks that have a void return type. 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 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. Since the queue must always return void, any methods or callbacks that are buffered must return void.

You may add message buffers to the methods and callback handlers of a web service. It is important, however, 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 client's infrastructure. Design View reinforces this by drawing the message buffer "spring" icons on the end of the wire closest to your web service.

Adding a message buffer to a method makes the method asynchronous, meaning that callers to that method do not wait for a response.

Note: You can use message buffers to avoid a potential deadlock condition when your web service is conversational. If the web service has at least one non-buffered incoming method with conversational phase set to "continue" or "finish" and has at least one non-buffered outgoing callback, it is possible that the callback will be initiated at the same time as a client calls one of the incoming methods. This situation will result in deadlock, causing one or both of the transactions to time out and be rolled back. If you experience this problem, make either all incoming methods or all outgoing callbacks message-buffered. For more information about conversations, see "Overview:Conversations".

# Message Buffers on Web Service Methods

If you add a message buffer to a method of your web service, incoming messages (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 processes the request. Note that since 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 service to process the message.

# Message Buffers on Web Service Callbacks

In the case of a callback, your web service is acting as the client. Your web service is sending an outgoing messages (callback invocation) to the client, which may respond with a incoming message containing the callback's return value.

If you add a message buffer to a callback, outgoing messages (invocations of the callback) are buffered on the local machine. 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 service doesn't have to wait for the network roundtrip to occur.

# The message-buffer Property (@jws:message-buffer Javadoc Tag)

You can easily add a message buffer to a method or callback in Design View. Select the method or callback you want to buffer. Then navigate to the message-buffer property in the Properties editor and set the enabled attribute to true. This will add the Javadoc tag @jws:message-buffer enabled-true to the Javadoc comment preceding the method or callback in the source code.

# 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. 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 below 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;
    }

# Execution Order of Methods

When a web service defines buffered (asynchronous) methods, neither the web service designer nor the client can make any assumptions about the order in which methods and callbacks will execute. This is especially true when considering buffered and non-buffered methods in the same web service.

Note that invocations of synchronous methods are guaranteed to be in order of arrival. But if buffered methods are also defined in the same web service, you cannot determine when their invocations will occur relative to the synchronous methods or relative to other buffered methods.

Note also that WebLogic Workshop web services are single-threaded and serial. An arriving method or callback invocation request will never interrupt a currently executing method or callback handler in the same conversation.

# Controlling Retry Behavior

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

The constructors for the RetryException class 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

Guide to Building Web Services

Using Asynchrony to Enable Long-Running Operations

Asynchronous Web Services

Maintaining State with Conversations