Web services typically use HTTP to provide
communication between a client and a server (where the web service resides). HTTP
is a request-response protocol where each
operation consists of a request-response pair: (1) a request message sent from
the client to a server followed by (2) a response message returned from the server
to the client. The server must always send a response for the operation to complete
successfully. Such requests are called synchronous because during the
request the client is synchronized with the server; the client cannot continue
processing until the server responds or the request times out (the client may
time out if a response is not received within a specific period of time).
Some of the operations the web service performs may be long-running.
If an operation involves human interaction such as approval by a loan officer
of a bank, the operation could take days to complete. It would be a poor design
if individual request-response cycles were allowed to span days; such requests
would unnecessarily engage resources on both the client and server hosts.
With Workshop and WebLogic Server, you can design your web service
to be asynchronous, which means that the service disengages from the
client after the initial request and calls back the client when the final
response is ready. This allows the client to continue performing other work while
the application completes the requested operation. It also keeps each request-response
interaction between the client and application as short as possible. Think of
phoning a friend to request some information. If your friend doesn't have the
answer right away, you wouldn't sit on hold for hours at a time. Instead you would
ask the friend to call you back when he gets the information.
An asynchronous web service provides a method that accept requests from clients
that begin an operation but do not wait for the operation to complete.
The method typically returns immediately, supplying the response portion of
the initial request-response interaction but not supplying the actual,
substantial result of the requested operation. The service also provides a
callback method, which sends the results of the long-running operation to
the client when the results are finally ready.
The following diagram shows a web service with two methods: an initiating
method and a callback method. The client (typically a web service control)
invokes requestMessage to initiate the web service's main process. When the
main process is complete (that is, when the response is constructed) the onMessage
callback method is invoked that sends the response back to the client.
Adding Callback Methods to a Web Service
To add a callback method to a web service, right-click anywhere in the web
service source code and select Insert > Callback. The
default callback interface containing one callback method will be added. By
default the callback method is named newMethod(). In the example below, the
default method name has been changed to sendMessage().
@WebService
public class HelloWorldWebService {
@Callback
private CallbackSvc callback;
@WebMethod
public void requestMessage() {
}
@CallbackService
public interface CallbackSvc extends CallbackInterface {
@WebMethod
public void onMessage();
}
}
Multiple callback methods can be added to the callback interface.
Parameters added to the callback method represent data sent to the client. For
example, if you want to send a String response back to the client, add a String
parameter to the callback method as follows.
@CallbackService
public interface CallbackSvc extends CallbackInterface {
@WebMethod
public void sendMessage(String message);
}
To send a response back to the client, you must (1) declare the callback
interface and then (2) invoke the appropriate callback method based on that
declaration.
(1) To declare the callback interface, use the @Callback annotation. (The
Insert > Callback command will automatically supply this declaration.)
@Callback
private CallbackSvc callback;
(2) Then invoke the appropriate callback method:
@WebService
public class HelloMessage {
@Callback
private CallbackSvc callback;
@WebMethod
public void initiateRequest() {
callback.sendMessage("This is your callback message.");
}
@CallbackService
public interface CallbackSvc extends CallbackInterface {
@WebMethod
public void sendMessage(String message);
}
}
Typically, a web service communicates with its client through a service control.
The diagram below shows the relationship between a web service client, a service
control, and a web service.
The client (on the far left) begins the interaction by requesting a message,
a request that is passed on to the web service through the web service control.
When the web service has completed the response, it is passed back to the original
client. This process has three stages: (1) The web service invokes its callback
method that sends the response to the control. (2) The control event set method
listens for the response and passes it to the client. (3) Finally the client handler
method listens for the control event set method and receives the event.
For more information about the relationship between a web service and a web
service control, see Handling
Web Service Callback Messages.
For more information about the relationship between a client and a web service
control, see Creating
and Using a Service Control.
For more information about testing Web Service callback methods see Testing
Web Service Callback Methods.