Creating Callback Enabled Clients for Asynchronous Web Services
(http://dev2dev.bea.com/pub/a/2005/03/callback_clients.html)
Published on dev2dev (http://dev2dev.bea.com/)
http://dev2dev.bea.com/pub/a/2005/03/callback_clients.html
See this if you're having trouble printing code examples
Creating Callback Enabled Clients for Asynchronous Web Services
by Reza Shafii
03/14/2005
Abstract
Web services are a promising technology that play an important role in Service Oriented Architectures (SOA). A key, emerging aspect of this technology is the ability to provide asynchronous services. Although today’s web service standards contain specifications for providing such asynchronous services, the details on using them from a client application perspective can be confusing and unclear. Web services callbacks are an important element in the realization of these asynchronous services. This article provides a practical guide to the creation of client applications for web services that contain callback operations. All code segments shown in this article are from the included example, which you can download. The example contains the complete implementation of these code segments and usage guidelines.
Terminology
Before starting a discussion on callback-enabled clients, it is important that we clarify the terminology involved. The following diagram shows the main entities involved when a client uses a Web service with a callback operation.
Figure 1. A client making a call to a web service
This figure depicts a client making a call to a web service. The web service can then respond, at some later time, by making a call back to the client. Therefore, a client of a web service that contains a callback operation is special in that the client itself must provide an endpoint. We call this the callback endpoint and define an endpoint as a unique address identified by a URI to which SOAP request messages can be sent.
The client itself starts the interaction with the web service by sending a SOAP message to the web service endpoint. The correlated request messages sent by the client to the web service and their associated response messages form the client initiated operations. As mentioned, the client can process the request messages sent by the web service to its own callback endpoint. Together, the correlated request and response messages are referred to as a callback operation.
With this terminology in mind, let's take a closer look at the concept of web service callbacks and their relationship to conversational web services and asynchronous web service invocation.
Asynchronous vs. Callbacks vs. Conversational
The concept of an asynchronous web service invocation is sometimes confused with the idea of web service callbacks and conversational web services. Although related, the three concepts are different.
An asynchronous web service invocation means that the client is able to send a SOAP message request without blocking to receive the corresponding response message from the server. The process of making such asynchronous web service calls on BEA WebLogic Platform 8.1 web services is already comprehensively documented and is therefore not discussed further in this article.
Web service callbacks refer to scenarios that involve the web service provider sending a SOAP message back to its clients. The Web Services Description Language (WSDL) specifications define such operations as being of the type “solicit/response.” Clients of web services that support callback operations must have a web service endpoint themselves, which the web service can use for sending callback requests at any point in time, or, in other words, asynchronously. Note that this is unrelated to the concept of asynchronous invocation discussed earlier.
A web service is conversational if the series of messages going back and forth between the two endpoints are tracked with a unique conversation ID with specific operations flagged to start and end the flow of messages. Web services that provide callbacks are also, by definition, conversational. This is because in order for the web service to be able to make a callback call on a client, it has to have its callback endpoint information. This is only possible after an initial invocation has been made by the client. Therefore, at the very least, the initial operation initiated by the client and the callback operation made by the web service are related to each other and must be tracked with a unique conversation ID. If this is not done, there is no way for the client to differentiate between callback operations relating to different initiating calls.
We will now take these considerations into account and create callback-enabled clients. As we've just seen, these clients form the basis of solicit-response and conversational web services.
Creating Callback-Enabled Clients
As discussed earlier, callback-enabled web service clients need to provide a callback endpoint capable of asynchronously receiving and processing callback operation messages. To avoid the complications of having to provide a callback endpoint, a technique known as polling can be used as an alternative. However, this technique requires the client to periodically call the server to check for callback events. The overhead of these calls can be significant if the event in question does not occur frequently. This overhead can be avoided by having the client provide a callback endpoint and process the callback operations directly.
It should also be noted that although it is possible to create callback-enabled clients by using a web service over JMS (if such binding is offered), this approach has some limitations, one of the important ones being that it forces the client to use the same JMS implementation as the web service provider. We will therefore concentrate on accomplishing our task over the HTTP transport. There are two areas that require attention in creating such a client: the creation of proper client-initiated SOAP messages, and the handling of callback operations.
When our client initiates operations of a web service containing a callback, it needs to somehow include the URI of the callback endpoint on which it is listening within the request message. The Web Services Addressing and the SOAP Conversation Protocol specifications both define a SOAP header element that allows you to achieve this goal. Ideally, the specification used in specifying the callback endpoint would not matter. However, most web services containers, including BEA WebLogic Server 8.1, do not yet contain an implementation of the Web Services Addressing specifications. Currently, BEA WebLogic Workshop 8.1 web services support the SOAP Conversation Protocol specifications and that is the example used within our example client.
According to the SOAP Conversation Protocol, the required SOAP headers differ depending on the phase of the conversation. For the first client-initiated (start) operation within the conversation, we need to provide the web service with our callback endpoint through the callbackLocation header element. All operations, including the first one, will also require a unique ID that will be used in our SOAP messages throughout the dialogue. This is achieved through the conversationID element. The following is an example of a SOAP request message that starts a callback-enabled conversation:
<soapenv:Envelope soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:env="http://schemas.xmlsoap.org/soap/envelop/"
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/">
<soapenv:Header>
<con:StartHeader soapenv:actor="http://schemas.xmlsoap.org/soap/actor/next"
soapenv:mustUnderstand="0"
xmlns:con="http://www.openuri.org/2002/04/soap/conversation/">
<con:conversationID>[123456]:192.168.1.100:8181</con:conversationID>
<con:callbackLocation>
http://192.168.1.100:8181/StockNotificationCallback
</con:callbackLocation>
</con:StartHeader>
</soapenv:Header>
<soapenv:Body>
<n1:registerForThresholdNotif xmlns:n1="http://www.openuri.org/">
<n1:stockTicker>CCC</n1:stockTicker>
<n1:threshold>10</n1:threshold>
</n1:registerForThresholdNotif>
</soapenv:Body>
</soapenv:Envelope>
Most of the existing Java web service toolkits (for example, BEA WebLogic’s clientgen, Apache Axis, and JWSDP) allow you to create a proxy library that can be used by client applications to easily invoke web services operations. However, none of these frameworks supports callback operations with the main issue being that their proxies do not generate the required headers. Until such support is provided, it would be highly desirable to be able to use all the benefits of these frameworks (for example, complex type XML mapping) by extending them with support for callback operations. One technique for achieving this result is the use of a SOAP message handler.
All the web services toolkits named above can support SOAP message handlers. A message handler is a Java class that implements the javax.xml.rpc.handler.GenericHandler interface and contains methods called right before sending out (or after receiving) a SOAP message. We can introduce a message handler within our client that is able to find out the current phase of a particular conversation and accordingly extend the outgoing request message with the required headers.
It is important to note that the client SOAP message handler must be able to determine the phase of the conversation that the message in question belongs to so that the appropriate header elements are created. The generation of the conversation ID is also a task that is left up to the client handler.
Once the extended request message is received by the web service endpoint, it will then send request messages to the callback endpoint specified by the callbackLocation element of the start message. In most cases, the client process itself needs to provide this endpoint and handle the callback messages appropriately. If our client is running within a web service container, this could be accomplished by deploying a web service with the callback operation within the same container. However, if the client is not running within a container, the job can be accomplished by implementing the callback endpoint within a lightweight container embedded in the client process itself. This gives us the ability to invoke the client generated operations and handle the incoming callback operations within the same process context. Note that the processing entity behind the callback endpoint (and within the client) needs to be able to handle the XML mapping of the message parameters as well as the dispatching of the operation to the right area of code.
Off course the client could also choose to specify a callback endpoint living within a container separate from the calling process by simply setting the callbackLocation header element appropriately.
As we have seen, the creation of clients for web services containing callback operations is not trivial and contains complex elements including the handling of SOAP messages, management of the conversation (both in terms of phases and IDs), mapping of parameters, and dispatching of operations. These complexities are all abstracted when the web service in question is accessed through a BEA WebLogic Workshop Service Control, which automatically performs all these operations for the user.
Creating Callback-Enabled Client Using a Service Control
The accessing of web services through a WebLogic Workshop Service Control is already well-documented. This solution is by far the simplest way to use callback-enabled web services if the client entity is able to use controls (that is, it is a Java Process Definition business process or another control; Page Flows are not able to use control callbacks). All the complexities involved in accessing callback-enabled web services are abstracted by this method.
Example Stock Notification Service
The example included in this article contains a Stock Notification conversational web service and a sample client illustrating the concepts discussed here. The web service provides operations allowing clients to register stock tickers and an associated threshold price. The service then monitors the stock, and every time the price passes that threshold, notifies the client through a callback (onThresholdPassed()).
Figure 2. This diagram illustrates the configuration for our example
It is clear that a polling technique is not an optimal solution for the creation of our client: Stock prices could pass their associated thresholds on a frequent basis or very seldom. A short polling interval could therefore lead to many unnecessary calls whereas a long polling interval could result in the client being notified of a threshold crossing long after the fact.
The implementation of a callback endpoint within the client application seems like a better choice. Let's first look at how the example client sends operations to the StockNotification web service. We have implemented the client using two distinct techniques. The first technique uses the WebLogic Workshop-generated proxy library and is implemented by the makeCallUsingBEAProxy() method of the StockNotificationClient class:
public void makeCallUsingBEAProxy() {
try {
// Get the proxy instance so that we can start calling the web service operations
StockNotificationSoap sns = null;
StockNotification_Impl snsi = new StockNotification_Impl();
sns = snsi.getStockNotificationSoap();
// Register our conversational handler so that it can properly set our
// our conversation headers with a callback location
QName portName = new QName("http://www.openuri.org/",
"StockNotificationSoap");
HandlerRegistry registry = snsi.getHandlerRegistry();
List handlerList = new ArrayList();
handlerList.add(new HandlerInfo(
ClientConversationHandler.class, null, null));
registry.setHandlerChain(portName, handlerList);
// Register, call some methods, then sleep a bit so that our callback
// location can receive some notifications and finally finish the conversation.
sns.registerForThresholdNotif("AAAAA", "100");
sns.addToRegistration("BBBBB", "5");
StockList stocks = sns.getAllRegisteredStocks();
...
sns.endAllNotifications();
}
catch (Exception e) {
throw new RuntimeException(e);
}
}
As you can see in this code segment, we are able to use the classes generated by clientgen as we would normally. The only thing that stands out in this code as compared to the invocation of a web service without callbacks is the instantiation and registration of a client-side SOAP message handler at the beginning of the method. This handler intercepts the outgoing SOAP messages and adds the necessary conversational headers. Every time a SOAP request message is sent from the client process the handleRequest() method of our message handler is called with a MessageContext object containing information about the outgoing SOAP request. Below is a code segment of our example client’s message handler:
package weblogic.webservice.core.handler;
...
public class ClientConversationHandler
extends GenericHandler {
public boolean handleRequest(MessageContext ctx) {
...
if (phase.equals("START")) {
headerElement
= (SOAPHeaderElement) header
.addChildElement("StartHeader",
"con",
"http://www.openuri.org/2002/04/soap/conversation/");
headerElement.addChildElement("con:callbackLocation")
.addTextNode(CALLBACK_URI);
}
else if (phase.equals("CONTINUE") || phase.equals("FINISH")) {
headerElement
= (SOAPHeaderElement) header
.addChildElement("ContinueHeader",
"con",
"http://www.openuri.org/2002/04/soap/conversation/");
}
headerElement.addChildElement("con:conversationID").addTextNode(convID);
...
}
}
The proxy library generated by the BEA clientgen tool already uses a default client-side SOAP message handler that creates the conversational StartHeader header element. Unfortunately, currently clientgen output does not support callback operations and therefore the default handler does not create the required callbackLocation sub-element. We therefore have to ensure that our own message handler overrides the default conversational handler so as to manage the extra task of creating the callbackLocation header. We do this by ensuring that our handler is created within the same package as the default handler, namely weblogic.webservice.core.handler, and that it has the exact same class name as ClientConversationHandler. Note that this technique involves overriding the existing conversation message handler and therefore is not guaranteed to be forward-compatible. This example, however, does show how a message handler could be used for the creation of the callback headers and this concept can be used with any other web services framework supporting SOAP message handlers.
An alternative to the technique of using SOAP message handlers along with proxy classes is to use the JAXM API to directly create the SOAP request messages and send them to the web service. This is the second technique used by our example client and is implemented within the makeCallsUsingJAXM() and callMethodFromFile() methods of the StockNotificationClient class:
public void makeCallsUsingJAXM() {
callMethodFromFile("C:\\registerForNotifSOAP.xml");
...
callMethodFromFile("C:\\endAllNotifSOAP.xml");
}
private void callMethodFromFile(String fileName) {
try {
// Create a SOAP connection object
SOAPConnectionFactory scf = SOAPConnectionFactory.newInstance();
SOAPConnection conn = scf.createConnection();
// Create the SOAP request message from the specified file
MessageFactory mf = MessageFactory.newInstance();
SOAPMessage msg = mf.createMessage();
SOAPPart sp = msg.getSOAPPart();
// Read the file content into a string and replace the conversation ID with
// the current one.
String fileContent = readFileIntoString(fileName);
fileContent = fileContent.replaceFirst(CONV_ID_HOLDER,
ConvIDGenerator.getInstance().
getConversationID());
StreamSource prepMsg = new StreamSource(new StringBufferInputStream(
fileContent));
sp.setContent(prepMsg);
msg.saveChanges();
// Make the actual call
conn.call(msg, TARGET_SERVICE_URI);
conn.close();
}
catch (Exception ex) {
throw new RuntimeException(ex);
}
}
The callMethodFromFile() method reads the SOAP message from the specified file, replaces the message’s conversation ID with the client’s current conversation ID, and finally makes the actual call. When using the JAXM approach, the Java to XML mapping of operation parameters and return values must be implemented by the client. We have avoided this task by using pre-generated SOAP messages (that already contain the required parameter values) from the file. Although this approach serves as a good conceptual illustration, it is most likely not a feasible solution for clients containing a reasonable level of complexity. Such clients must create the messages programmatically from scratch using JAXM along with a Java to XML mapping API.
Now that we have reviewed the areas of our client responsible for creating the web service operations, let's turn to the implementation of the client’s callback endpoint and the processing of the callback messages coming from the web service. Since our callback endpoint needs to be able to handle the incoming HTTP requests, a servlet could be a logical choice. Further, it would be highly desirable to have a servlet that is able to extract the SOAP messages included within the incoming HTTP requests and provide it to us in an easy-to-use form. The ReqRespListener interface and the JAXMServlet class of the javax.xml.messaging package provide us with this functionality. Once properly deployed, servlets that use this interface and class will have all targeted HTTP post requests automatically converted to SOAPMessage instances passed to us through the onMessage() method. The following code shows the onMessage() method implementation for our example client.
public class CallBackHandlerServlet
extends JAXMServlet
implements ReqRespListener {
public SOAPMessage onMessage(SOAPMessage message) {
try {
// We have just received a SOAP message at the callback
// endpoint. In this example we will just assume that
// the message received is in fact the onThresholdPassed
// callback request. However, a servlet handling
// multiple callbacks cannot make this assumption and
// should process the SOAP message to see what callback
// it relates to and do as appropriate for each.
String stockTicker = extractOnThresholdPassedArgument(message);
System.out.println("[DEV2DEV CALLBACK EXAMPLE]: Received treshold notification
for: " + stockTicker);
// Now we have to create a proper response to the callback
// request. Returning this response as part of the onMessage()
// method will ensure that the SOAP response gets back to the server.
SOAPMessage response = createThresholdPassedResponse();
return response;
}
catch (Exception e) {
throw new RuntimeException(e);
}
}
...
}
Once a callback request message is received by the onMessage() method, our client then extracts the stock ticker argument, prints it to the standard output, and creates the correlated response message that is returned to the web service by our servlet. Clients that use web services that contain more than a single callback operation will also need to dispatch the incoming request to an appropriate area of client code based on the corresponding callback operation.
Although our servlet contains the appropriate code for the processing of incoming onThresholdPassed() callback messages from the web services, it needs to be deployed within a servlet container listening on the callback URI to complete the implementation of the callback endpoint. The Jetty open source project contains a lightweight servlet container that can be embedded within our client. The deployment of the CallBackHandlerServlet servlet within an embedded Jetty container allows us to have the callback endpoint reside within the client Java process. The StockNotificationCallbackProcessor class is a utility class used by our client to start the Jetty server and deploy the CallBackHandlerServlet servlet:
public class StockNotificationCallbackProcessor {
public static final String CALLBACK_SERVER_PORT = ":8181";
public static final String CALLBACK_SERVLET_CLASS =
"asynchwsconsumer.CallBackHandlerServlet";
public static final String CALLBACK_SERVLET_NAME = "CallBackHandlerServlet";
private HttpServer server;
public StockNotificationCallbackProcessor() {}
public void startListening() {
try {
// Configure the server so that we listen on the callback URI
server = new Server();
server.addListener(CALLBACK_SERVER_PORT);
ServletHttpContext context = (ServletHttpContext) server.getContext("/");
context.addServlet(CALLBACK_SERVLET_NAME, "/*",
CALLBACK_SERVLET_CLASS);
// Start the http server
server.start();
}
catch (Exception e) {
throw new RuntimeException(e);
}
}
public void stopListening() {
try {
server.stop();
}
catch (Exception e) {
throw new RuntimeException(e);
}
}
}
The startListening() method deploys the CallBackHandlerServlet on port 8181 and configures the embedded servlet container so that all HTTP requests are directed to this port. This method also starts the embedded servlet container.
Now that we have examined both the creation of the web service operations and the processing of the callback operations, let's see how the main() method of our example client uses these elements:
public static void main(String[] args) {
StockNotificationClient snClient = new StockNotificationClient();
snClient.snCallbackProcessor.startListening();
snClient.makeCallUsingBEAProxy();
ConvIDGenerator.getInstance().resetConversationID();
snClient.makeCallsUsingJAXM();
snClient.snCallbackProcessor.stopListening();
}
As you can see, the method starts by setting up the callback endpoint (which, as we saw before, involves starting the embedded servlet container and deploying the callback processing servlet to it). The method then uses the BEA clientgen proxy to make calls on the stock notification web service. Given that this interaction with the web services completes the conversation by calling the endAllNotifications() end operation, the client needs to change the conversation ID to start a new conversation. Our client uses the ConvIDGenerator singleton class to manage conversation IDs, and that class uses the java.rmi.dgc.VMID class to create properly formatted unique conversation IDs.
Once the conversation ID has been changed, the client then uses JAXM to once again make calls on the stock notification web service. Finally, the client stops the embedded servlet container and the process ends.
We have now completed our analysis of the example client that can be downloaded as part of this article. When you run this client against the stock notification web services, both the client and the web service will display messages to the standard output describing the various phases of the conversation including the processing of the callback operations.
Conclusion
This article shows the steps involved in the creation of a stand-alone client process for web services containing callback operations. Such a client needs to manage the conversational aspects of the web service calls and provide an endpoint that can be used by the web service for callback operations.
Download
CallbackExample.zip (1.7Mb) - This file contains the complete example application described in this article.
References
Reza Shafii works for BEA Systems professional services.
Return to dev2dev.
