Customizing a Service Control: Buffering Methods and Callbacks

This topic describes customizations you can make to a Service control's CTRL file to modify the control's default behavior

To learn more about controls, see Controls: Using Resources from a Web Service.

To learn more about Service controls, see Service Control: Using Another Web Service.

To learn more about customizing Service controls, see Customizing a Service Control: Overview.

# Adding Buffers to Service Control Methods

To learn about message buffers, see Using Asynchronous Methods.

Message buffers may only be added to methods and callbacks that have a void return type.

You may add message buffers to the methods and callback handlers of a Service control. It is important to understand what happens when you add message buffers to Service controls. Remember that a Service control is a proxy for another web service (the target service). In many cases, the target service is located on a remote server. If you add message buffers to a Service control, the buffering always occurs on the local server.

Design View draws message buffers as a "spring" icon on the method or callback, as shown here:

Note that WebLogic Workshop draws message buffers on the "near" end of the wire. In general, you have no control over the execution environment or configuration of remote web services. In other words, you can't change what happens on the "far" end of the wire.

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

In the case of a Service control, your web service is the client when sending outgoing messages (Service control method invocations) and the other service is the client when sending incoming messages (Service control callbacks) to your service.

## Buffer Behavior on Service Control Methods

If you add a message buffer to a Service control's method, outgoing messages (invocations of the method) will be buffered on the local machine. The method invocation will return 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.

## Buffer Behavior on Service Control Callback Handlers

If you add a message buffer to a Service control's callback, incoming messages (invocations of the callback) will be buffered on the local machine. The callback invocation will return to the other web service immediately. This prevents the other service from waiting until your service processes the request. Note that since the buffering occurs on your end of the wire, the calling service still must wait for the network roundtrip even though it will return a void result. But the calling service does not have to wait for your service to process the message.

## Adding Message Buffers to a Service Control in WebLogic Workshop

There are two ways to specify that Service control methods and callback handlers should use message buffers:

- In Design View, select the method or callback. In the Tasks pane, select the Task that begins "Buffer this method...".

- In Design View, select the method or callback. In the Properties pane, expand the message-buffer property and set the enabled attribute to true.

These actions will add the appropriate annotations to the Service control's CTRL file. The specific annotations added are described in the next section.

# How Message Buffers are Specified in Code

Message buffers are specific in code using the @jws:message-buffer Javadoc tag. In a Service control CTRL file, the @jws:message-buffer tag may be placed on a method or a callback.

To learn about the @jws:message-buffer tag, see @jws:message-buffer Tag.

The following example contains a @jws:message-buffer tag on a Service control method:

    public interface QuoteServiceControl extends ServiceControl
    {
    ...
       /**
         * @jws:message-buffer enable="true"
         */
        public void getQuote (int customerID, java.lang.String tickerSymbol);
    ...
    }

The following example contains a @jws:message-buffer tag on a Service control callback:

    public interface QuoteServiceControl extends ServiceControl
    {
    ...
        public interface Callback
        {
            /**
             * @jws:message-buffer enable="true"
             */
            public void onQuoteReady (java.lang.String tickerSymbol, double dQuote);
        }
    ...
    }

Related Topics

Using Asynchrony to Enable Long-Running Operations

Asynchronous Methods