Skip Headers
Oracle® Fusion Middleware Programming Advanced Features of JAX-RPC Web Services for Oracle WebLogic Server
11g Release 1 (10.3.6)

Part Number E13735-06
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

7 Using Callbacks to Notify Clients of Events

This chapter describes how to callbacks with WebLogic Java API for XML-based RPC (JAX-RPC) Web services to notify clients of events.

This chapter includes the following topics:

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 client's request are ready, or when the client's 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.

Callback Implementation Overview and Terminology

To implement callbacks, you must create or update the following three Java files:

The following graphic shows the flow of messages:

Description of message_flow.gif follows
Description of the illustration message_flow.gif

  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.

Programming Callbacks: Main Steps

The procedure in this section describes how to program and compile the three JWS files that are required to implement callbacks: the target Web service, the client Web service, and the callback interface. The procedure shows how to create the JWS files from scratch; if you want to update existing JWS files, you can also use this procedure as a guide.

It is assumed that you have set up an Ant-based development environment and that you have a working build.xml file to which you can add targets for running the jwsc Ant task and deploying the Web services. For more information, see Getting Started With JAX-RPC Web Services for Oracle WebLogic Server.

Table 7-1 Steps to Program Callbacks

#
Step Description

1

Create a new JWS file, or update an existing one, that implements the target Web service.

Use your favorite IDE or text editor. See Programming Guidelines for Target Web Service.

Note: The JWS file that implements the target Web service invokes one or more callback methods of the callback interface. However, the step that describes how to program the callback interface comes later in this procedure. For this reason, programmers typically program the three JWS files at the same time, rather than linearly as implied by this procedure. The steps are listed in this order for clarity only.

2

Update your build.xml file to include a call to the jwsc Ant task to compile the target JWS file into a Web service.

See "Running the jwsc WebLogic Web Services Ant Task" in Getting Started With JAX-RPC Web Services for Oracle WebLogic Server.

3

Run the Ant target to build the target Web service.

For example:

prompt> ant build-mainService

4

Deploy the target Web service as usual.

See "Deploying and Undeploying WebLogic Web Services" in Getting Started With JAX-RPC Web Services for Oracle WebLogic Server.

5

Create a new JWS file, or update an existing one, that implements the client Web service.

It is assumed that the client Web service is deployed to a different WebLogic Server instance from the one that hosts the target Web service. See Programming Guidelines for the Callback Client Web Service.

6

Create the callback JWS interface that implements the callback Web service.

See Programming Guidelines for the Callback Interface.

7

Update the build.xml file that builds the client Web service.

The jwsc Ant task that builds the client Web service also implicitly generates the callback Web service from the callback interface file. See Updating the build.xml File for the Client Web Service.

8

Run the Ant target to build the client and callback Web services.

For example:

prompt> ant build-clientService

9

Deploy the client Web service as usual.

See "Deploying and Undeploying WebLogic Web Services" in Getting Started With JAX-RPC Web Services for Oracle WebLogic Server.


Programming Guidelines for Target Web Service

The following example shows a simple JWS file that implements the target Web service; see the explanation after the example for coding guidelines that correspond to the Java code in bold.

package examples.webservices.callback;

import weblogic.jws.WLHttpTransport;
import weblogic.jws.Callback; 

import javax.jws.WebService;
import javax.jws.WebMethod;

@WebService(name="CallbackPortType",
            serviceName="TargetService",
            targetNamespace="http://examples.org/")

@WLHttpTransport(contextPath="callback",
                 serviceUri="TargetService",
                 portName="TargetServicePort")

/**
 * callback service
 */

public class TargetServiceImpl {

  @Callback 
  CallbackInterface callback; 

  @WebMethod
  public void targetOperation (String message) {

        callback.callbackOperation (message); 
  }

}

Follow these guidelines when programming the JWS file that implements the target Web service. Code snippets of the guidelines are shown in bold in the preceding example.

See "JWS Annotation Reference" in WebLogic Web Services Reference for Oracle WebLogic Server for additional information about the WebLogic-specific JWS annotations discussed in this section.

Programming Guidelines for the Callback Client Web Service

The following example shows a simple JWS file for a client Web service that invokes the target Web service described in Programming Guidelines for Target Web Service; see the explanation after the example for coding guidelines that correspond to the Java code in bold.

package examples.webservices.callback;

import weblogic.jws.WLHttpTransport;
import weblogic.jws.ServiceClient; 
import weblogic.jws.CallbackMethod; 
import weblogic.jws.security.CallbackRolesAllowed; 
import weblogic.jws.security.SecurityRole; 

import javax.jws.WebService;
import javax.jws.WebMethod;

import examples.webservices.callback.CallbackPortType; 

import java.rmi.RemoteException;

@WebService(name="CallbackClientPortType",
            serviceName="CallbackClientService",
            targetNamespace="http://examples.org/")

@WLHttpTransport(contextPath="callbackClient",
                 serviceUri="CallbackClient",
                 portName="CallbackClientPort")

public class CallbackClientImpl {

  @ServiceClient( 
     wsdlLocation="http://localhost:7001/callback/TargetService?WSDL", 
     serviceName="TargetService", 
     portName="TargetServicePort") 
  @CallbackRolesAllowed(@SecurityRole(role="mgr", mapToPrincipals="joe")) 
  private CallbackPortType port; 

  @WebMethod
  public void clientOperation (String message) {

    try {

        port.targetOperation(message); 
    }
    catch (RemoteException e) {
      e.printStackTrace();
    }

  }
  @CallbackMethod(target="port", operation="callbackOperation") 
  @CallbackRolesAllowed(@SecurityRole(role="engineer",  mapToPrincipals="shackell")) 
  public void callbackHandler(String msg) { 

        System.out.println (msg); 
  } 

}

Follow these guidelines when programming the JWS file that invokes the target Web service; code snippets of the guidelines are shown in bold in the preceding example:

See "JWS Annotation Reference" in WebLogic Web Services Reference for Oracle WebLogic Server for additional information about the WebLogic-specific JWS annotations discussed in this section.

Programming Guidelines for the Callback Interface

The callback interface is also a JWS file that implements a Web service, except for one big difference: instead of using the standard @javax.jws.WebService annotation to specify that it is a standard Web service, you use the WebLogic-specific @weblogic.jws.CallbackService to specify that it is a callback service. The attributes of @CallbackService are a restricted subset of the attributes of @WebService.

Follow these restrictions on the allowed data types and JWS annotations when programming the JWS file that implements a callback service:

The following example shows a simple callback interface file that implements a callback Web service. The target Web service, described in Programming Guidelines for Target Web Service, explicitly invokes a method in this interface. The jwsc-generated implementation of the callback interface then automatically sends a message back to the client Web service that originally invoked the target Web service; the client service is described in Programming Guidelines for the Callback Client Web Service. See the explanation after the example for coding guidelines that correspond to the Java code in bold.

package examples.webservices.callback;

import weblogic.jws.CallbackService; 

import javax.jws.Oneway;
import javax.jws.WebMethod;

@CallbackService 
public interface CallbackInterface { 

  @WebMethod
  @Oneway 
  public void callbackOperation (String msg); 

}

Follow these guidelines when programming the JWS interface file that implements the callback Web service. Code snippets of the guidelines are shown in bold in the preceding example.

See "JWS Annotation Reference" in WebLogic Web Services Reference for Oracle WebLogic Server for additional information about the WebLogic-specific JWS annotations discussed in this section.

Updating the build.xml File for the Client Web Service

When you run the jwsc Ant task against the JWS file that implements the client Web service, the task implicitly also generates the callback Web service, as described in this section.

You update a build.xml file to generate a client Web service that invokes the target Web service by adding taskdefs and a build-clientService target that looks something like the following example. See the description after the example for details.

<taskdef name="jwsc"
  classname="weblogic.wsee.tools.anttasks.JwscTask" />

<target name="build-clientService">

  <jwsc
      srcdir="src"
      destdir="${clientService-ear-dir}" >

      <jws file="examples/webservices/callback/CallbackClientImpl.java" >

        <clientgen
          wsdl="http://${wls.hostname}:${wls.port}/callback/TargetService?WSDL"
          packageName="examples.webservices.callback"
          serviceName="TargetService" />

      </jws>

  </jwsc>

</target>

Use the taskdef Ant task to define the full classname of the jwsc Ant tasks.

Update the jwsc Ant task that compiles the client Web service to include a <clientgen> child element of the <jws> element so as to generate and compile the JAX-RPC stubs for the deployed TargetService Web service. The jwsc Ant task automatically packages them in the generated WAR file so that the client Web service can immediately access the stubs. You do this because the CallbackClientImpl JWS file imports and uses one of the generated classes.

Because the WSDL of the target Web service includes an additional <service> element that describes the callback Web service (which the target Web service invokes), the <clientgen> child element of the jwsc Ant task also generates and compiles the callback Web service and packages it in the same EAR file as the client Web service.