Chapter 43. Writing Handlers
Abstract
JAX-WS provides a flexible plug-in framework for adding message processing modules to an application. These modules, known as handlers, are independent of the application level code and can provide low-level message processing capabilities.
43.1. Handlers: An Introduction
Overview
When a service proxy invokes an operation on a service, the operation's parameters are passed to Apache CXF where they are built into a message and placed on the wire. When the message is received by the service, Apache CXF reads the message from the wire, reconstructs the message, and then passes the operation parameters to the application code responsible for implementing the operation. When the application code is finished processing the request, the reply message undergoes a similar chain of events on its trip to the service proxy that originated the request. This is shown in Figure 43.1, “Message Exchange Path”.
Figure 43.1. Message Exchange Path
JAX-WS defines a mechanism for manipulating the message data between the application level code and the network. For example, you might want the message data passed over the open network to be encrypted using a proprietary encryption mechanism. You could write a JAX-WS handler that encrypted and decrypted the data. Then you could insert the handler into the message processing chains of all clients and servers.
As shown in Figure 43.2, “Message Exchange Path with Handlers”, the handlers are placed in a chain that is traversed between the application level code and the transport code that places the message onto the network.
Figure 43.2. Message Exchange Path with Handlers
Handler types
The JAX-WS specification defines two basic handler types:
- Logical HandlerLogical handlers can process the message payload and the properties stored in the message context. For example, if the application uses pure XML messages, the logical handlers have access to the entire message. If the application uses SOAP messages, the logical handlers have access to the contents of the SOAP body. They do not have access to either the SOAP headers or any attachments unless they were placed into the message context.Logical handlers are placed closest to the application code on the handler chain. This means that they are executed first when a message is passed from the application code to the transport. When a message is received from the network and passed back to the application code, the logical handlers are executed last.
- Protocol HandlerProtocol handlers can process the entire message received from the network and the properties stored in the message context. For example, if the application uses SOAP messages, the protocol handlers would have access to the contents of the SOAP body, the SOAP headers, and any attachments.Protocol handlers are placed closest to the transport on the handler chain. This means that they are executed first when a message is received from the network. When a message is sent to the network from the application code, the protocol handlers are executed last.NoteThe only protocol handler supported by Apache CXF is specific to SOAP.
Implementation of handlers
The differences between the two handler types are very subtle and they share a common base interface. Because of their common parentage, logical handlers and protocol handlers share a number of methods that must be implemented, including:
- handleMessage()The
handleMessage()method is the central method in any handler. It is the method responsible for processing normal messages. - handleFault()
handleFault()is the method responsible for processing fault messages. - close()
close()is called on all executed handlers in a handler chain when a message has reached the end of the chain. It is used to clean up any resources consumed during message processing.
The differences between the implementation of a logical handler and the implementation of a protocol handler revolve around the following:
- The specific interface that is implementedAll handlers implement an interface that derives from the
Handlerinterface. Logical handlers implement theLogicalHandlerinterface. Protocol handlers implement protocol specific extensions of theHandlerinterface. For example, SOAP handlers implement theSOAPHandlerinterface. - The amount of information available to the handlerProtocol handlers have access to the contents of messages and all of the protocol specific information that is packaged with the message content. Logical handlers can only access the contents of the message. Logical handlers have no knowledge of protocol details.
Adding handlers to an application
To add a handler to an application you must do the following:
- Determine whether the handler is going to be used on the service providers, the consumers, or both.
- Determine which type of handler is the most appropriate for the job.
- Implement the proper interface.To implement a logical handler see Section 43.2, “Implementing a Logical Handler”.To implement a protocol handler see Section 43.4, “Implementing a Protocol Handler”.
- Configure your endpoint(s) to use the handlers. See Section 43.10, “Configuring Endpoints to Use Handlers”.
