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

Part Number E13734-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

12 Using Callbacks

This chapter describes how to use callbacks to notify clients of events for WebLogic Web services using Java API for XML Web Services (JAX-WS).

This chapter includes the following sections:

Overview of Callbacks

A callback is a contract between a client and service that allows the service to invoke operations on a client-provided endpoint during the invocation of a service method for the purpose of querying the client for additional data, allowing the client to inject behavior, or notifying the client of progress. The service advertises the requirements for the callback using a WSDL that defines the callback port type and the client informs the service of the callback endpoint address using WS-Addressing.

Example Callback Implementation

The example callback implementation described in this section consists of the following three Java files:

The following shows the flow of messages for the example callback implementation.

Figure 12-1 Example Callback Implementation

Description of Figure 12-1 follows
Description of "Figure 12-1 Example Callback Implementation"

  1. The call() method of the CallerService Web service, running in one WebLogic Server instance, explicitly invokes the targetOperation() method of the TargetService and passes a Web service endpoint to the CallbackService. Typically, the TargetService service is running in a separate WebLogic Server instance.

  2. The implementation of the TargetService.targetOperation() method explicitly invokes the callback() method of the CallbackService, which implements the callback service, using the Web service endpoint that is passed in from CallerService when the method is called.

  3. The CallbackService.callback() method sends information back to the TargetService Web service.

  4. The TargetService.targetOperation() method, in turn, sends the information back to the CallerService service, completing the callback sequence.

Steps to Program Callbacks

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 Web service. 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-WS Web Services for Oracle WebLogic Server.

Table 12-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 Web service. However, the step that describes how to program the callback Web service 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 Updating the build.xml File for the Target Web Service.

3

Run the Ant target to build the target Web service.

For example:

prompt> ant build-target

4

Deploy the target Web service as usual.

See "Deploying and Undeploying WebLogic Web Services" in Getting Started With JAX-WS 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 JWS file that implements the callback Web service.

See Programming Guidelines for the Callback Web Service.

7

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

The jwsc Ant task that builds the client Web service also compiles CallbackWS.java and includes the class file in the WAR file using the Fileset Ant task element. For example:

<clientgen
     type="JAXWS"
    wsdl="${awsdl}"
    packageName="jaxws.callback.client.add"/>
<clientgen
     type="JAXWS"
    wsdl="${twsdl}"
    packageName="jaxws.callback.client.target"/>
<FileSet dir="." >
    <include name="CallbackWS.java" />
</FileSet>

8

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

For example:

prompt> ant build-caller

9

Deploy the client Web service as usual.

See "Deploying and Undeploying WebLogic Web Services" in Getting Started With JAX-WS 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 javax.jws.WebService;
import javax.xml.ws.BindingType;
import javax.xml.ws.wsaddressing.W3CEndpointReference;
import examples.webservices.callback.callbackservice.*;

@WebService(
        portName="TargetPort",
        serviceName="TargetService",
        targetNamespace="http://example.com",
        endpointInterface=
                   "examples.webservices.callback.target.TargetPortType",
        wsdlLocation="/wsdls/Target.wsdl")
@BindingType(value="http://schemas.xmlsoap.org/wsdl/soap/http")

public class TargetImpl {
  public String targetOperation(String s, W3CEndpointReference callback)
  {
      CallbackService aservice = new CallbackService();
      CallbackPortType aport = 
         aservice.getPort(callback, CallbackPortType.class);
      String result = aport.callback(s);
      return result + " processed by target"; 
  }
}

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.

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 javax.annotation.Resource;
import javax.jws.WebMethod;
import javax.jws.WebService;
import javax.xml.ws.BindingType;
import javax.xml.ws.Endpoint; 
import javax.xml.ws.WebServiceContext; 
import javax.xml.ws.WebServiceException;
import javax.xml.ws.WebServiceRef;
import javax.xml.ws.handler.MessageContext; 
import javax.xml.ws.wsaddressing.W3CEndpointReference; 
 
import examples.webservices.callback.target.*; 

@WebService(
        portName="CallerPort",
        serviceName="CallerService",
        targetNamespace="http://example.com")
@BindingType(value="http://schemas.xmlsoap.org/wsdl/soap/http")

public class CallerImpl
{
   @Resource
   private WebServiceContext context;

   @WebServiceRef()
   private TargetService target;

   @WebMethod()
   public String call(String s) { 
      Object sc =  
          context.getMessageContext().get(MessageContext.SERVLET_CONTEXT); 
      Endpoint callbackImpl = Endpoint.create(new CallbackWS()); 
      callbackImpl.publish(sc); 
      TargetPortType tPort = target.getTargetPort(); 
      String result = tPort.targetOperation(s,  
           callbackImpl.getEndpointReference(W3CEndpointReference.class)); 
       callbackImpl.stop(); 
      return result;
  }
}

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:

Programming Guidelines for the Callback Web Service

The following example shows a simple JWS file for a callback Web service. The callback operation is shown in bold.

package examples.webservices.callback;

import javax.jws.WebService;
import javax.xml.ws.BindingType;

@WebService(
     portName="CallbackPort",
     serviceName="CallbackService",
     targetNamespace="http://example.com",
     endpointInterface=
         "examples.webservices.callback.callbackservice.CallbackPortType",
     wsdlLocation="/wsdls/Callback.wsdl")

@BindingType(value="http://schemas.xmlsoap.org/wsdl/soap/http")

public class CallbackWS implements 
     examples.webservices.callback.callbackservice.CallbackPortType {

     public CallbackWS() {
     }

     public java.lang.String callback(java.lang.String arg0) {
          return arg0.toUpperCase(); 
     }
}

Updating the build.xml File for the Target Web Service

You update a build.xml file to generate a target Web service that invokes the callback Web service by adding taskdefs and a build-target 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-target">
    <jwsc srcdir="src" destdir="${ear-dir}" listfiles="true">
         <jws file="TargetImpl.java" 
           compiledWsdl="${cowDir}/target/Target_wsdl.jar" type="JAXWS">
           <WLHttpTransport contextPath="target" serviceUri="TargetService"/>
         </jws>
         <clientgen
           type="JAXWS"
           wsdl="Callback.wsdl"
           packageName="examples.webservices.callback.callbackservice"/>
    </jwsc>
     <zip destfile="${ear-dir}/jws.war" update="true">
        <zipfileset dir="src/examples/webservices/callback" prefix="wsdls">
           <include name="Callback*.wsdl"/>
        </zipfileset>
     </zip>
   </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:

For more information about jwsc, see "Running the jwsc WebLogic Web Services Ant Task" in Getting Started With JAX-RPC Web Services for Oracle WebLogic Server.