The following sections describe how to use callbacks to notify clients of events:
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.
The example callback implementation described in this section consists of the following three Java files:
In the example in this section, the callback Web Service is called CallbackService
. The Web Service defines a single callback method called callback()
.
In the example, this Web Service is called TargetService
and it defines a single standard method called targetOperation()
.
In the example, this Web Service is called CallerService
. The method that invokes TargetService
in the standard way is called call()
.
The following shows the flow of messages for the example callback implementation.
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.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.CallbackService.callback()
method sends information back to the TargetService
Web Service.TargetService.targetOperation()
method, in turn, sends the information back to the CallerService
service, completing the callback sequence.
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 WebLogic Web Services Using JAX-WS.
Use your favorite IDE or text editor. See Programming Guidelines for Target Web Service.
|
||||
prompt> ant build-target |
||||
See
“Deploying and Undeploying WebLogic Web Services” in Programming WebLogic Web Services Using JAX-WS.
|
||||
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.
|
||||
prompt> ant build-caller |
||||
See
“Deploying and Undeploying WebLogic Web Services” in Programming WebLogic Web Services Using JAX-WS.
|
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.bea.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.
CallbackService
stub implementation.import javax.xml.ws.wsaddressing.W3CEndpointReference;
import examples.webservices.callback.callbackservice.*;
CallbackService
implementation using the stub implementation and get a port by passing the CallbackService
service endpoint, which is passed by the calling application (CallerService
).CallbackService aservice = new CallbackService();
CallbackPortType aport =
aservice.getPort(callback, CallbackPortType.class);
CallbackService
using the port you instantiated:String result = aport.callback(s);
CallerService
service.return result + " processed by target";
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.xml.ws.Endpoint;
import javax.jws.WebMethod;
import javax.jws.WebService;
import javax.xml.ws.BindingType;
import javax.xml.ws.WebServiceContext;import javax.xml.ws.WebServiceException;
import javax.xml.ws.handler.MessageContext;
import javax.xml.ws.WebServiceRef;
import javax.xml.ws.wsaddressing.W3CEndpointReference;import examples.webservices.callback.target.*;
@WebService(
portName="CallerPort",
serviceName="CallerService",
targetNamespace="http://example.bea.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:
TargetService
stub implementation. import javax.xml.ws.Endpoint;
import javax.xml.ws.WebServiceContext;
import javax.xml.ws.handler.MessageContext;
import javax.xml.ws.wsaddressing.W3CEndpointReference;
import examples.webservices.callback.target.*;
WebServiceContext
and MessageContext
. You will use the servlet context when publishing the Web Service endpoint, later.@Resource
Object sc
private WebServiceContext context;
.
.
.
context.getMessageContext().get(MessageContext.SERVLET_CONTEXT);
For more information about accessing runtime information using WebServiceContext
and MessageContext
, see
“Accessing Runtime Information About a Web Service” in Getting Started With WebLogic Web Services Using JAX-WS.
CallbackService
implementation and publish that endpoint to accept incoming requests.Endpoint callbackImpl = Endpoint.create(new CallbackWS());
callbackImpl.publish(sc);
For more information about Web Service publishing, see Publishing a Web Service Endpoint.
TargetService
stub implementation and invoke the targetOperation
operation of TargetService
using the port you instantiated. You pass the CallbackService
service endpoint as a javax.xml.ws.wsaddressing.W3CEndpointReference
data type:@WebServiceRef()
private TargetService target;.
TargetPortType tPort = target.getTargetPort();
.
.
String result = tPort.targetOperation(s,
callbackImpl.getEndpointReference(W3CEndpointReference.class));
callbackImpl.stop();
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.bea.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();
}
}
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:
<clientgen>
child element of the <jws>
element to generate and compile the Service
interface stubs for the deployed CallbackService
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 TartgetImpl
JWS file imports and uses one of the generated classes.<zip>
element to include the WSDL for the CallbackService
service in the WAR file so that other Web Services can access the WSDL from the following URL: http://${wls.hostname}:${wls.port}/callback/wsdls/Callback.wsdl
For more information about jwsc
, see
“Running the jwsc WebLogic Web Services Ant Task” in Programming WebLogic Web Services Using JAX-RPC.