41.10. Configuring Endpoints to Use Handlers
41.10.1. Programmatic Configuration
41.10.1.1. Adding a Handler Chain to a Consumer
Overview
Adding a handler chain to a consumer involves explicitly building the chain of handlers. Then you set the handler chain directly on the service proxy's
Binding
object.
Important
Any handler chains configured using the Spring configuration override the handler chains configured programmaticaly.
Procedure
To add a handler chain to a consumer you do the following:
- Create a
List<Handler>
object to hold the handler chain. - Create an instance of each handler that will be added to the chain.
- Add each of the instantiated handler objects to the list in the order they are to be invoked by the runtime.
- Get the
Binding
object from the service proxy.TipApache CXF provides an implementation of theBinding
interface calledorg.apache.cxf.jaxws.binding.DefaultBindingImpl
. - Set the handler chain on the proxy using the
Binding
object'ssetHandlerChain()
method.
Example
Example 41.14, “Adding a Handler Chain to a Consumer” shows code for adding a handler chain to a consumer.
Example 41.14. Adding a Handler Chain to a Consumer
import javax.xml.ws.BindingProvider; import javax.xml.ws.handler.Handler; import java.util.ArrayList; import java.util.List; import org.apache.cxf.jaxws.binding.DefaultBindingImpl; ... SmallNumberHandler sh = new SmallNumberHandler(); 1 List<Handler> handlerChain = new ArrayList<Handler>(); 2 handlerChain.add(sh); 3 DefaultBindingImpl binding = ((BindingProvider)proxy).getBinding(); 4 binding.getBinding().setHandlerChain(handlerChain); 5
The code in Example 41.14, “Adding a Handler Chain to a Consumer” does the following:
41.10.1.2. Adding a Handler Chain to a Service Provider
Overview
You add a handler chain to a service provider by decorating either the SEI or the implementation class with the
@HandlerChain
annotation. The annotation points to a meta-data file defining the handler chain used by the service provider.
Procedure
To add handler chain to a service provider you do the following:
- Decorate the provider's implementation class with the
@HandlerChain
annotation. - Create a handler configuration file that defines the handler chain.
The @HandlerChain annotation
The
javax.jws.HandlerChain
annotation decorates service provider's implementation class. It instructs the runtime to load the handler chain configuration file specified by its file property.
The annotation's file property supports two methods for identifying the handler configuration file to load:
- a URL
- a relative path name
Example 41.15, “Service Implementation that Loads a Handler Chain” shows a service provider implementation that will use the handler chain defined in a file called
handlers.xml
. handlers.xml
must be located in the directory from which the service provider is run.
Example 41.15. Service Implementation that Loads a Handler Chain
import javax.jws.HandlerChain;
import javax.jws.WebService;
...
@WebService(name = "AddNumbers",
targetNamespace = "http://apache.org/handlers",
portName = "AddNumbersPort",
endpointInterface = "org.apache.handlers.AddNumbers",
serviceName = "AddNumbersService")
@HandlerChain(file = "handlers.xml")
public class AddNumbersImpl implements AddNumbers
{
...
}
Handler configuration file
The handler configuration file defines a handler chain using the XML grammar that accompanies JSR 109 (Web Services for Java EE, Version 1.2). This grammar is defined in the
http://java.sun.com/xml/ns/javaee
.
The root element of the handler configuration file is the
handler-chains
element. The handler-chains
element has one or more handler-chain
elements.
The
handler-chain
element define a handler chain. Table 41.1, “Elements Used to Define a Server-Side Handler Chain” describes the handler-chain
element's children.
Element | Description |
---|---|
handler | Contains the elements that describe a handler. |
service-name-pattern | Specifies the QName of the WSDL service element defining the service to which the handler chain is bound. You can use * as a wildcard when defining the QName. |
port-name-pattern | Specifies the QName of the WSDL port element defining the endpoint to which the handler chain is bound. You can use * as a wildcard when defining the QName. |
protocol-binding |
Specifies the message binding for which the handler chain is used. The binding is specified as a URI or using one of the following aliases:
##SOAP11_HTTP , ##SOAP11_HTTP_MTOM , ##SOAP12_HTTP , ##SOAP12_HTTP_MTOM , or ##XML_HTTP .
For more information about message binding URIs see Appendix C, Apache CXF Binding IDs.
|
The
handler-chain
element is only required to have a single handler
element as a child. It can, however, support as many handler
elements as needed to define the complete handler chain. The handlers in the chain are executed in the order they specified in the handler chain definition.
Important
The final order of execution will be determined by sorting the specified handlers into logical handlers and protocol handlers. Within the groupings, the order specified in the configuration will be used.
The other children, such as
protocol-binding
, are used to limit the scope of the defined handler chain. For example, if you use the service-name-pattern
element, the handler chain will only be attached to service providers whose WSDL port
element is a child of the specified WSDL service
element. You can only use one of these limiting children in a handler
element.
The
handler
element defines an individual handler in a handler chain. Its handler-class
child element specifies the fully qualified name of the class implementing the handler. The handler
element can also have an optional handler-name
element that specifies a unique name for the handler.
Example 41.16, “Handler Configuration File” shows a handler configuration file that defines a single handler chain. The chain is made up of two handlers.
Example 41.16. Handler Configuration File
<handler-chains xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee"> <handler-chain> <handler> <handler-name>LoggingHandler</handler-name> <handler-class>demo.handlers.common.LoggingHandler</handler-class> </handler> <handler> <handler-name>AddHeaderHandler</handler-name> <handler-class>demo.handlers.common.AddHeaderHandler</handler-class> </handler> </handler-chain> </handler-chains>
41.10.2. Spring Configuration
Overview
The easiest way to configure an endpoint to use a handler chain is to define the chain in the endpoint's configuration. This is done by adding a
jaxwxs:handlers
child to the element configuring the endpoint.
Important
A handler chain added through the configuration file takes precedence over a handler chain configured programatically.
Procedure
To configure an endpoint to load a handler chain you do the following:
- If the endpoint does not already have a configuration element, add one.For more information on configuring Apache CXF endpoints see Chapter 15, Configuring JAX-WS Endpoints.
- Add a
jaxws:handlers
child element to the endpoint's configuration element. - For each handler in the chain, add a
bean
element specifying the class that implements the handler.TipIf your handler implementation is used in more than one place you can reference abean
element using theref
element.
The handlers element
The
jaxws:handlers
element defines a handler chain in an endpoint's configuration. It can appear as a child to all of the JAX-WS endpoint configuration elements. These are:
jaxws:endpoint
configures a service provider.jaxws:server
also configures a service provider.jaxws:client
configures a service consumer.
You add handlers to the handler chain in one of two ways:
- add a
bean
element defining the implementation class - use a
ref
element to refer to a namedbean
element from elsewhere in the configuration file
The order in which the handlers are defined in the configuration is the order in which they will be executed. The order may be modified if you mix logical handlers and protocol handlers. The run time will sort them into the proper order while maintaining the basic order specified in the configuration.
Example
Example 41.17, “Configuring an Endpoint to Use a Handler Chain In Spring” shows the configuration for a service provider that loads a handler chain.
Example 41.17. Configuring an Endpoint to Use a Handler Chain In Spring
<beans ... xmlns:jaxws="http://cxf.apache.org/jaxws" ... schemaLocation="... http://cxf.apache.org/jaxws http://cxf.apache.org/schemas/jaxws.xsd ..."> <jaxws:endpoint id="HandlerExample" implementor="org.apache.cxf.example.DemoImpl" address="http://localhost:8080/demo"> <jaxws:handlers> <bean class="demo.handlers.common.LoggingHandler" /> <bean class="demo.handlers.common.AddHeaderHandler" /> </jaxws:handlers> </jaws:endpoint> </beans>