Registering Handlers on a Service Control

This topic explains how to register handlers on a service control in order to add a layer of processing to incoming or outgoing web service messages. Service control handlers are typically used to inspect or alter messages or log information.

For infomation on using handlers to process the mustUnderstand attribute on SOAP headers see Processessing SOAP Headers with Message Handlers.

Processing Web Service Messages with Handlers

The Workshop service control supports the JAX-RPC handler API.

The primary way of registering a handler on a service control is with the @ServiceControl.Handler annotation such as the following:

...
@ControlExtension
@ServiceControl.Handler(operation={"client.ClientHandler"})
public interface TargetServiceControl extends ServiceControl {
...

Note that the operation attribute is an array of strings that specifies the class names of the handlers that will be called when the service control sends and receives messages. The array may be a space-separated list of handler class names or the name of a <handler-chain> defined in a handler configuration file specified by the file attribute. All handler classes must implement the javax.xml.rpc.handler.Handler interface. (An easy way to do this is to subclass the GenericHandler.)

Note that you can specify a handler chain configuration file using the file attribute, as shown below:

@ServiceControl.Handler(file={"handlerConfig.xml"})

A handler configuration file is an XML file that defines handlers, handler chains and handler initialization data. The handler configuration XML file must conform to the handler chain configuration file schema, which can be found in Appendix B of JSR-181: Web Services Metadata for the Java Platform.

Example Handler Configuration File

A handler configuration file is an XML file that conforms to the Workshop handler configuration schema. The example below illustrates a sample handler configuration file:

<?xml version="1.0" encoding="UTF-8"?>
<handler-config xmlns="http://www.bea.com/xml/ns/jws" xmlns:j2ee="http://java.sun.com/xml/ns/j2ee">
   <handler-chain>
     <handler-chain-name>HandlerChain</handler-chain-name>
     <handler>
       <j2ee:handler-name>handler1</j2ee:handler-name>
       <j2ee:handler-class>service.MyHandler</j2ee:handler-class>
     </handler>
   </handler-chain>
</handler-config>

The handler-class attribute of each <handler> element must refer to a handler class that implements the javax.xml.rpc.handler.Handler interface.

Any <init-param> elements that are present for a given <handler> element will be passed to the handler's init() method when the handler is initialized.