@jws:message-buffer Tag

Specifies that there should be a queue between the service's implementation code and the message transport wire for the specified method.

# Syntax

    @jws:buffer

    	[enable="true | false"]

    	[retry-count="protocolName"]
    	[retry-delay="targetServiceEndPoint"]

# Attributes

enable

Required. Specifies whether the messages arriving or departing via the associated method or callback are queued.

retryCount

Optional. The number of times WebLogic Server will attempt to deliver queued messages to the service.

retryDelay

Optional. The amount of time that should pass between message delivery attempts.

# Remarks

The following rules apply to this tag's use:

- Only one @jws:buffer tag may appear within a single Javadoc block.

- Optionally may appear in front of a @jws:operation method in a JWS file.

- Optionally may appear in front of a callback method (event declaration) in a JWS file.

- Optionally may appear in front of an event handler method (control_eventName method) in a JWS file.

- Optionally may appear in front of a method declaration in a CTRL file.

The @jws:buffer tag may only be placed on methods or callbacks with return type void.

The @jws:buffer tag places a queue between the method and the communication wire. For incoming messages, this means that the message is queued before it is processed. For outgoing messages, this means that the message is queued before it is sent on the wire.

Note that the queue is transparent to the method that is marked with the @jws:buffer tag. When multiple messages arrive, they may be queued (or for the client, in the case of a callback) while the method is processing a previous message. Callers invoking a buffered method or callback will always experience an immediate return.

The retryDelay attribute can be specified using friendly names for units of time. For example, the default unit is seconds, and can be expressed as "30 seconds". The following are also possible values:

- 5 minutes

- 24 hours

- 3 days

The unit for the retryDelay value can also be expressed as a partial name, as follows:

- 30 s

- 30 sec

- 30 seconds

Note that all parameters to methods and callbacks that are marked with the @jws:message-buffer tag must be serializable (must implement java.io.Serializable). For an example, see Asynchronous Methods.

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.

# Controlling Retry Behavior

You may control retry behavior of buffered methods at runtime by using weblogic.jws.RetryException. See Controlling Retry Behavior in the topic Asynchronous Methods.

Related Topics

Using Asynchrony to Enable Long-Running Operations

Asynchronous Methods