public interface Handler {
// Public Instance Methods
public abstract void destroy( );
public abstract javax.xml.namespace.QName[ ] getHeaders( );
public abstract boolean handleFault(MessageContext context);
public abstract boolean handleRequest(MessageContext context);
public abstract boolean handleResponse(MessageContext context);
public abstract void init( HandlerInfo config);
}
The Handler interface defines the methods that
must be implemented by a message handler. The init(
) and destroy( ) methods mark the
beginning and end of the handler's life cycle. The
init( ) method receives a Map
containing property values that are typically set from a
configuration file such as the jaxrpc-ri.xml file
used by wsdeploy, the
config.xml used by wscompile,
or the webservices.xml file supplied to the J2EE
1.4 j2eec utility. The getHeaders(
) method returns the URIs of all of the headers that the
handler can process, in the form of an array of
javax.xml.namespace.QName objects. A handler whose
processing is not directly related to a header should return an empty
array.
The handler processing is carried out by the handleRequest(
), handleResponse( ), and
handleFault( ) methods, which are called for an
outgoing message, an incoming message that is not a fault, and a
fault, respectively. Each of these methods is passed a
MessageContext object that handlers can use to
store state that can then be read by other handlers in the chain. The
MessageContext object can also be used to retrieve
the message itself. If a handler successfully processes a message, it
should return true from these methods. If an error occurs that should
result in message processing being interrupted, the handler should
substitute a fault message for the original and return false. A
handler may also throw an exception from one of its
handleXXX( ) methods to report an exceptional
condition. This exception is thrown to the application that sent the
message. There are also cases in which a handler might wish to
terminate handling of a message without reporting an error. For
example, a handler might cache the replies to requests that it has
already seen. In this case, the handler should replace the message
with its cached response and return false. For examples that
illustrate the possible uses of a handler, refer to Chapter 6.
