14.5.2. JAX-WS Common API Reference
The handler framework is implemented by a JAX-WS protocol binding in the runtime of the client and the endpoint, which is the server component. Proxies and Dispatch instances, known collectively as binding providers, each use protocol bindings to bind their abstract functionality to specific protocols.
Types of Message Handlers
- Logical Handler
- Logical handlers only operate on message context properties and message payloads. Logical handlers are protocol-independent and cannot affect protocol-specific parts of a message. Logical handlers implement interface
javax.xml.ws.handler.LogicalHandler. - Protocol Handler
- Protocol handlers operate on message context properties and protocol-specific messages. Protocol handlers are specific to a particular protocol and may access and change protocol-specific aspects of a message. Protocol handlers implement any interface derived from
javax.xml.ws.handler.Handler except javax.xml.ws.handler.LogicalHandler. - Service Endpoint Handler
- On a service endpoint, handlers are defined using the
@HandlerChainannotation. The location of the handler chain file can be either an absolutejava.net.URLinexternalFormor a relative path from the source file or class file.Example 14.30. Example Service Endpoint Handler
@WebService @HandlerChain(file = "jaxws-server-source-handlers.xml") public class SOAPEndpointSourceImpl { ... } - Service Client Handler
- On a JAX-WS client, handlers are defined either by using the
@HandlerChainannotation, as in service endpoints, or dynamically, using the JAX-WS API.Example 14.31. Defining a Service Client Handler Using the API
Service service = Service.create(wsdlURL, serviceName); Endpoint port = (Endpoint)service.getPort(Endpoint.class); BindingProvider bindingProvider = (BindingProvider)port; List<Handler> handlerChain = new ArrayList<Handler>(); handlerChain.add(new LogHandler()); handlerChain.add(new AuthorizationHandler()); handlerChain.add(new RoutingHandler()); bindingProvider.getBinding().setHandlerChain(handlerChain);The call to thesetHandlerChainmethod is required.
The MessageContext interface is the super interface for all JAX-WS message contexts. It extends Map<String,Object> with additional methods and constants to manage a set of properties that enable handlers in a handler chain to share processing related state. For example, a handler may use the put method to insert a property into the message context. One or more other handlers in the handler chain may subsequently obtain the message via the get method.
APPLICATION or HANDLER. All properties are available to all handlers for an instance of a message exchange pattern (MEP) of a particular endpoint. For instance, if a logical handler puts a property into the message context, that property is also available to any protocol handlers in the chain during the execution of an MEP instance.
Note
APPLICATION level are also made available to client applications and service endpoint implementations. The defaultscope for a property is HANDLER.
- Logical Message Context
- When logical handlers are invoked, they receive a message context of type
LogicalMessageContext.LogicalMessageContextextendsMessageContextwith methods which obtain and modify the message payload. It does not provide access to the protocol-specific aspects of a message. A protocol binding defines which components of a message are available via a logical message context. A logical handler deployed in a SOAP binding can access the contents of the SOAP body but not the SOAP headers. On the other hand, the XML/HTTP binding defines that a logical handler can access the entire XML payload of a message. - SOAP Message Context
- When SOAP handlers are invoked, they receive a
SOAPMessageContext.SOAPMessageContextextendsMessageContextwith methods which obtain and modify the SOAP message payload.
An application may throw a SOAPFaultException or an application-specific user exception. In the case of the latter, the required fault wrapper beans are generated at run-time if they are not already part of the deployment.
Example 14.32. Fault Handling Examples
public void throwSoapFaultException()
{
SOAPFactory factory = SOAPFactory.newInstance();
SOAPFault fault = factory.createFault("this is a fault string!", new QName("http://foo", "FooCode"));
fault.setFaultActor("mr.actor");
fault.addDetail().addChildElement("test");
throw new SOAPFaultException(fault);
}
public void throwApplicationException() throws UserException
{
throw new UserException("validation", 123, "Some validation error");
}
The annotations available via the JAX-WS API are defined in JSR-224, which can be found at http://www.jcp.org/en/jsr/detail?id=224. These annotations are in package javax.xml.ws.
javax.jws.
