Chapter 41. Writing Handlers
41.1. Handlers: An Introduction
Figure 41.1. Message Exchange Path
Figure 41.2. Message Exchange Path with Handlers
- 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
handleMessage()method is the central method in any handler. It is the method responsible for processing normal messages.
handleFault()is the method responsible for processing fault messages.
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 specific interface that is implementedAll handlers implement an interface that derives from the
Handlerinterface. Logical handlers implement the
LogicalHandlerinterface. Protocol handlers implement protocol specific extensions of the
Handlerinterface. For example, SOAP handlers implement the
- 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
- 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 41.2, “Implementing a Logical Handler”.To implement a protocol handler see Section 41.4, “Implementing a Protocol Handler”.
- Configure your endpoint(s) to use the handlers. See Section 41.10, “Configuring Endpoints to Use Handlers”.