![]() ![]() ![]() ![]() ![]() ![]() |
The following sections describe how to use callbacks to notify clients of events:
WARNING: | This feature can be implemented only for a JAX-RPC 1.1-based Web Service; you cannot implement it for a JAX-WS 2.0 Web Service. |
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 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.
To implement callbacks, you must create or update the following three Java files:
jwsc
Ant task automatically 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()
.
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 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:
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.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. 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.
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:
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. |
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.
prompt> ant build-mainService
See Deploying and Undeploying WebLogic Web Services.
See Programming Guidelines for the Callback Client Web Service.
See Programming Guidelines for the Callback Interface.
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.
prompt> ant build-clientService
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.
import weblogic.jws.Callback;
@weblogic.jws.Callback
JWS annotation to specify that a variable is a callback, which means that you can use the annotated variable to send callback events back to a client Web Service that invokes an operation of the TargetService
Web Service. The data type of the variable is the callback interface, which in this case is called CallbackInterface
.@Callback
CallbackInterface callback;
TargetService
, use the annotated variable to invoke one of the callback methods of the callback interface, which in this case is called callbackOperation()
:callback.callbackOperation (message);
See JWS Annotation Reference for additional information about the WebLogic-specific JWS annotations discussed in this section.
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:
import weblogic.jws.ServiceClient;
import weblogic.jws.CallbackMethod;
import weblogic.jws.security.CallbackRolesAllowed;
import weblogic.jws.security.SecurityRole;
jwsc
Ant task. The stub package is specified by the packageName
attribute of the <clientgen>
child element of <jws>
, and the name of the stub is determined by the WSDL of the invoked Web Service.import examples.webservices.callback.CallbackPortType;
@ServiceClient
JWS annotation to specify the WSDL, name, and port of the target Web Service you want to invoke. You specify this annotation at the field-level on a private variable, whose data type is the JAX-RPC port type of the Web Service you are invoking. @ServiceClient(
wsdlLocation="http://localhost:7001/callback/TargetService?WSDL",
serviceName="TargetService",
portName="TargetServicePort")
@CallbackRolesAllowed(@SecurityRole(role="mgr", mapToPrincipals="joe"))
private CallbackPortType port;
The preceding code also shows how to use the optional @CallbackRolesAllowed
annotation to specify the list of @SecurityRoles
that are allowed to invoke the callback methods.
@ServiceClient
annotation, invoke an operation of the target Web Service. This operation in turn will invoke a callback method of the callback interface:port.targetOperation(message);
Annotate the method with the @CallbackMethod
annotation to specify that this method handles callback messages. Use the target
attribute to specify the name of the JAX-RPC port for which you want to receive callbacks (in other words, the variable you previously annotated with @ServiceClient
). Use the operation
attribute to specify the name of the callback method in the callback interface from which this method will handle callback messages.
@CallbackMethod(target="port", operation="callbackOperation")
@CallbackRolesAllowed(@SecurityRole(role="engineer", mapToPrincipals="shackell"))
public void callbackHandler(String msg) {
System.out.println (msg);
}
The preceding code also shows how to use the optional @CallbackRolesAllowed
annotation to further restrict the security roles that are allowed to invoke this particular callback method.
See JWS Annotation Reference for additional information about the WebLogic-specific JWS annotations discussed in this section.
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:
@weblogic.jws.CallbackService
.Holder
classes (user-defined data types that implement the javax.xml.rpc.holders.Holder
interface).
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
@Onewaypublic 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.
import weblogic.jws.CallbackService;
@CallbackService
annotation to specify that the JWS file implements a callback service:@CallbackService
public interface CallbackInterface {
jwsc
Ant task.public void callbackOperation (String msg);
Note: | Although the example shows the callback method returning void and annotated with the @Oneway annotation, this is not a requirement. |
See JWS Annotation Reference for additional information about the WebLogic-specific JWS annotations discussed in this section.
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.
![]() ![]() ![]() |