javax.xml.rpc.handler

Interface Handler

public interface Handler

The javax.xml.rpc.handler.Handler interface is required to be implemented by a SOAP message handler. The handleRequest, handleResponse and handleFault methods for a SOAP message handler get access to the SOAPMessage from the SOAPMessageContext. The implementation of these methods can modify the SOAPMessage including the headers and body elements.
Method Summary
abstract voiddestroy()
The destroy method indicates the end of lifecycle for a Handler instance.
QName[]getHeaders()
Gets the header blocks processed by this Handler instance.
booleanhandleFault(MessageContext context)
The handleFault method processes the SOAP faults based on the SOAP message processing model.
booleanhandleRequest(MessageContext context)
The handleRequest method processes the request message.
booleanhandleResponse(MessageContext context)
The handleResponse method processes the response SOAP message.
abstract voidinit(HandlerInfo config)
The init method enables the Handler instance to initialize itself.

Method Detail

destroy

public abstract void destroy()
The destroy method indicates the end of lifecycle for a Handler instance. The Handler implementation class should release its resources and perform cleanup in the implementation of the destroy method.

Throws: javax.xml.rpc.JAXRPCException if there was any error during destroy

getHeaders

public QName[] getHeaders()
Gets the header blocks processed by this Handler instance.

Returns: Array of QNames of header blocks processed by this handler instance. QName is the qualified name of the outermost element of the Header block.

handleFault

public boolean handleFault(MessageContext context)
The handleFault method processes the SOAP faults based on the SOAP message processing model.

Parameters: context MessageContext parameter provides access to the SOAP message

Returns: boolean Indicates the processing mode

Throws: javax.xml.rpc.JAXRPCException indicates handler specific runtime error. If JAXRPCException is thrown by a handleFault method, the HandlerChain terminates the further processing of this handler chain. On the server side, the HandlerChain generates a SOAP fault that indicates that the message could not be processed for reasons not directly attributable to the contents of the message itself but rather to a runtime error during the processing of the message. On the client side, the JAXRPCException is propagated to the client code.

handleRequest

public boolean handleRequest(MessageContext context)
The handleRequest method processes the request message.

Parameters: context MessageContext parameter provides access to the request message.

Returns: boolean boolean Indicates the processing mode

Throws: javax.xml.rpc.JAXRPCException indicates a handler-specific runtime error. If JAXRPCException is thrown by a handleRequest method, the HandlerChain terminates the further processing of this handler chain. On the server side, the HandlerChain generates a SOAP fault that indicates that the message could not be processed for reasons not directly attributable to the contents of the message itself but rather to a runtime error during the processing of the message. On the client side, the exception is propagated to the client code javax.xml.rpc.soap.SOAPFaultException indicates a SOAP fault. The Handler implementation class has the the responsibility of setting the SOAP fault in the SOAP message in either handleRequest and/or handleFault method. If SOAPFaultException is thrown by a server-side request handler's handleRequest method, the HandlerChain terminates the further processing of the request handlers in this handler chain and invokes the handleFault method on the HandlerChain with the SOAP message context. Next, the HandlerChain invokes the handleFault method on handlers registered in the handler chain, beginning with the Handler instance that threw the exception and going backward in execution. The client-side request handler's handleRequest method should not throw the SOAPFaultException.

handleResponse

public boolean handleResponse(MessageContext context)
The handleResponse method processes the response SOAP message.

Parameters: context MessageContext parameter provides access to the response SOAP message

Returns: boolean Indicates the processing mode

Throws: javax.xml.rpc.JAXRPCException indicates a handler specific runtime error. If JAXRPCException is thrown by a handleResponse method, the HandlerChain terminates the further processing of this handler chain. On the server side, the HandlerChain generates a SOAP fault that indicates that the message could not be processed for reasons not directly attributable to the contents of the message itself but rather to a runtime error during the processing of the message. On the client side, the runtime exception is propagated to the client code.

init

public abstract void init(HandlerInfo config)
The init method enables the Handler instance to initialize itself. The init method passes the handler configuration as a HandlerInfo instance. The HandlerInfo is used to configure the Handler (for example: setup access to an external resource or service) during the initialization.

In the init method, the Handler class may get access to any resources (for example; access to a logging service or database) and maintain these as part of its instance variables. Note that these instance variables must not have any state specific to the SOAP message processing performed in the various handle method.

Parameters: config HandlerInfo configuration for the initialization of this handler config

Throws: javax.xml.rpc.JAXRPCException if initialization of the handler fails