7
Using Callbacks to Notify Clients of Events 7-1
7
Using Callbacks to Notify Clients of Events
The following sections describe how to use callbacks to notify clients of events:
■
Section 7.1, Overview of Callbacks
■
Section 7.2, Callback Implementation Overview and Terminology
■
Section 7.3, Programming Callbacks: Main Steps
■
Section 7.4, Programming Guidelines for Target Web Service
■
Section 7.5, Programming Guidelines for the Callback Client Web Service
■
Section 7.6, Programming Guidelines for the Callback Interface
■
Section 7.7, Updating the build.xml File for the Client Web Service
7.1 Overview of Callbacks
Callbacks notify a client of your Web service that some event has occurred. For example, you can notify a client when the results of that clients request are ready, or
when the clients request cannot be fulfilled.
When you expose a method as a standard public operation in your JWS file by using the WebMethod annotation, the client sends a SOAP message to the Web service to
invoke the operation. When you add a callback to a Web service, however, you define a message that the Web service sends back to the client Web service, notifying the client
of an event that has occurred. So exposing a method as a public operation and defining a callback are completely symmetrical processes, with opposite recipients.
WebLogic Server automatically routes the SOAP message from client invoke to the target Web service. In order to receive callbacks, however, the client must be operating
in an environment that provides the same services. This typically means the client is a Web service running on a Web server. If the client does not meet these requirements, it
is likely not capable of receiving callbacks from your Web service.
The protocol and message format used for callbacks is always the same as the protocol and message format used by the conversation start method that initiated the current
conversation. If you attempt to override the protocol or message format of a callback, an error is thrown.
7.2 Callback Implementation Overview and Terminology
To implement callbacks, you must create or update the following three Java files:
■
Callback interface: Java interface file that defines the callback methods. You do not explicitly implement this file yourself; rather, the jwsc Ant task automatically
7-2 Programming Advanced Features of JAX-RPC Web Services for Oracle WebLogic Server
generates an implementation of the interface. The implementation simply passes a message from the target Web service back to the client Web service. The generated
Web service is deployed to the same WebLogic Server that hosts the client Web service.
In the example in this section, the callback interface is called CallbackInterface
. The interface defines a single callback method called callbackOperation
.
■
JWS file that implements the target Web service
: The target Web service includes one or more standard operations that invoke a method defined in the callback
interface; this method in turn sends a message back to the client Web service that originally invoked the operation of the target Web service.
In the example, this Web service is called TargetService and it defines a single standard method called targetOperation.
■
JWS file that implements the client Web service
: The client Web service invokes an operation of the target Web service. This Web service includes one or more
methods that specify what the client should do when it receives a callback message back from the target Web service via a callback method.
In the example, this Web service is called CallbackClient and the method that is automatically invoked when it receives a callback is called
callbackHandler . The method that invokes TargetService in the
standard way is called clientOperation. The following graphic shows the flow of messages:
1.
The clientOperation method of the CallbackClient Web service, running in one WebLogic Server instance, explicitly invokes the
targetOperation operation of the TargetService. The TargetService
service might be running in a separate WebLogic Server instance.
2.
The implementation of the TargetService.targetOperation method explicitly invokes the callbackOperation operation of the
CallbackInterface , which implements the callback service. The callback
service is deployed to the WebLogic Server which hosts the client Web service.
3.
The jwsc-generated implementation of the CallbackInterface.callbackOperation
method simply sends a message back to the CallbackClient Web service. The client Web service
includes a method callbackHandler that handles this message.
Using Callbacks to Notify Clients of Events 7-3
7.3 Programming Callbacks: Main Steps
