Last Modified: 06/15/05
JAX-WS 2.0 defines a Handler
interface, with subinterfaces LogicalHandler
and SOAPHandler
. The Handler
interface contains handleMessage(C context)
and handleFault(C context)
methods, where C
extends MessageContext
. A property in the MessageContext
object is used to determine if the message is inbound or outbound. SOAPHandler
objects have access to the full soap message including headers. Logical handlers are independent of protocol and have access to the payload of the message.
The new handler types can now be written without casting the message context object that is passed to them. For instance:
public class MyLogicalHandler implements LogicalHandler<LogicalMessageContext> { public boolean handleMessage(LogicalMessageContext messageContext) { LogicalMessage msg = messageContext.getMessage(); return true; } // other methods } public class MySOAPHandler implements SOAPHandler<SOAPMessageContext> { public boolean handleMessage(SOAPMessageContext messageContext) { SOAPMessage msg = messageContext.getMessage(); return true; } // other methods }
Besides the standard lifecycle methods and new handle methods, a close(C context)
method has been added that is called on the handlers at the conclusion of a message exchange pattern. This allows handlers to clean up any resources that were used for the processing of a request-only or request/response exchange.
The init()
method of Handler
now takes a Map<String, Object>
rather than HandlerInfo
. This can be used to pass initialization parameters into a handler. The HandlerInfo
object has been removed from JAX-WS, simplifying the use of handler chains. If an application used the HandlerInfo
object previously to pass understood headers to a handler instance rather than coding them into the handler, these should now be passed in as initialization parameters instead.
In the examples above, the LogicalMessage
object allows a handler to get and set the message payload either as a JAXB object or as a javax.xml.transform.Source
. The SOAPMessage
object allows access to headers and the SOAP body of the message.
Both context objects extend MessageContext
, which holds properties that the handlers can use to communicate with each other. A standard property MessageContext.MESSAGE_OUTBOUND_PROPERTY
holds a Boolean
that is used to determine the direction of a message. For example, during a request, the property would be Boolean.TRUE
when seen by a client handler and Boolean.FALSE
when seen by a server handler.
The message context object can also hold properties set by the client or provider. For instance, port proxy and dispatch objects both extend BindingProvider
. A message context object can be obtained from both to represent the request or response context. Properties set in the request context can be read by the handlers, and properties set by the handler will be available in the response context. On the server end, a context object is passed into the invoke
method of a Provider
.
Starting from a WSDL file, handler chain configuration is through WSDL customizations as defined by JSR 109. A <handlerChains>
element is added to the customization file. The following is a simple handler chain with one handler (customization may be on server or client side):
<-- excerpt from customization file --> <bindings xmlns="http://java.sun.com/xml/ns/jaxws" xmlns:jws="http://www.bea.com/xml/ns/jws" xmlns:j2ee="http://java.sun.com/xml/ns/j2ee"> <jws:handler-chain> <jws:handler> <j2ee:handler-class>fromwsdl.handler_simple.common.TestHandler</j2ee:handler-class> <j2ee:init-param> <j2ee:param-name>name1</j2ee:param-name> <j2ee:param-value>value1</j2ee:param-value> </j2ee:init-param> <j2ee:soap-role>role1</j2ee:soap-role> <jws:handler> </jws:handler-chain> </bindings>
Starting from a Java class, annotations are used to describe the handler chain as defined by JSR 181. The following example uses the @HandlerChain
annotation to refer to a file describing the chain:
import javax.jws.HandlerChain; import javax.jws.WebService; @WebService @HandlerChain( file="handlers.xml", name="Chain1") public class MyServiceImpl { // implementation of class }
An example handlers.xml
file is shown below:
<?xml version="1.0" encoding="UTF-8"?> <jws:handler-config xmlns:jws="http://www.bea.com/xml/ns/jws"> <jws:handler-chain> <jws:handler> <jws:handler-class>com.example.MySOAPHandler</jws:handler-class> </jws:handler> </jws:handler-chain> </jws:handler-config>
When packaging the service, the handlers.xml file must be in the classpath within the WAR file, either directly under WEB-INF/classes
or further down in the same package as the service class file.
On the server side, the handlers may be configured in the sun-jaxws.xml deployment descriptor as well. A handler chain specified here will override handlers in WSDL customizations or annotated classes. An example is below:
<endpoint ....> <handler-chain> <handler> <handler-class>fromwsdl.handler_dd.common.TestHandler</handler-class> <soap-role>SecurityProvider</soap-role> <init-param> <param-name>logCategory</param-name> <param-value>MyService</param-value> </init-param> </handler> </handler-chain> </endpoint>
Handler chains may be configured on the client side at runtime by setting a chain directly on a BindingProvider
(e.g., a Dispatch
object or a port proxy). The HandlerRegistry
obtained from a JAX-WS service is not functional in this release. This example shows how to add a handler chain to a port proxy:
// given proxy interface HelloPortType HelloPortType myProxy = // create proxy Binding binding = myProxy.getBinding(); // can create new list or use existing one List<Handler> handlerList = binding.getHandlerChain(); handlerList.add(new MyHandler()); binding.setHandlerChain(handlerList);
With an existing binding provider, a Binding
object can be obtained with getBinding
. The binding object has a setHandlerChain
method that takes a list of handler info objects that can be used to set a new handler chain on the client. When the SOAP protocol is being used, the binding can be cast to a SOAPBinding
object that can be used to programmatically set the SOAP roles for the binding.
The fromjavahandler
and fromwsdlhandler
samples set a SOAPHandler
on the client and server. This handler simply outputs the contents of the SOAP message and can be used to see the requests and responses being passed back and forth. See the sample documentation for information on running the samples.
Copyright © 2005 Sun Microsystems, Inc. All rights reserved.