Using Callbacks to Notify Clients of Events 7-5
7.5 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
Section 7.4, 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; WebServicename=CallbackClientPortType,
serviceName=CallbackClientService, targetNamespace=http:examples.org
WLHttpTransportcontextPath=callbackClient, serviceUri=CallbackClient,
portName=CallbackClientPort
public class CallbackClientImpl {
ServiceClient wsdlLocation=http:localhost:7001callbackTargetService?WSDL,
serviceName=TargetService, portName=TargetServicePort
CallbackRolesAllowedSecurityRolerole=mgr, mapToPrincipals=joe private CallbackPortType port;
WebMethod public void clientOperation String message {
try {
port.targetOperationmessage; }
catch RemoteException e { e.printStackTrace;
}
} CallbackMethodtarget=port, operation=callbackOperation
CallbackRolesAllowedSecurityRolerole=engineer, mapToPrincipals=shackell
public void callbackHandlerString msg {
System.out.println msg; }
}
7-6 Programming Advanced Features of JAX-RPC Web Services for Oracle WebLogic Server
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 the required JWS annotations: import weblogic.jws.ServiceClient;
import weblogic.jws.CallbackMethod;
■
Optionally import the security-related annotations if you want to specify the roles that are allowed to invoke the callback methods:
import weblogic.jws.security.CallbackRolesAllowed; import weblogic.jws.security.SecurityRole;
■
Import the JAX-RPC stub of the port type of the target Web service you want to invoke. The actual stub itself will be created later by the 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;
■
In the body of the JWS file, use the 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:7001callbackTargetService?WSDL,
serviceName=TargetService, portName=TargetServicePort
CallbackRolesAllowedSecurityRolerole=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.
■
Using the variable you annotated with the ServiceClient annotation, invoke an operation of the target Web service. This operation in turn will invoke a
callback method of the callback interface:
port.targetOperationmessage;
■
Create a method that will handle the callback message received from the callback service. You can name this method anything you want. However, its signature
should exactly match the signature of the corresponding method in the callback interface.
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.
CallbackMethodtarget=port, operation=callbackOperation CallbackRolesAllowedSecurityRolerole=engineer,
mapToPrincipals=shackell public void callbackHandlerString msg {
System.out.println msg;
Using Callbacks to Notify Clients of Events 7-7
} 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 in WebLogic Web Services Reference for Oracle WebLogic
Server for additional information about the WebLogic-specific JWS annotations discussed in this section.
7.6 Programming Guidelines for the Callback Interface