Handler (Java EE 5)

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.

Version:

1.0

Author:

Rahul Sharma

public boolean handleRequest(MessageContext context)
handleRequest 方法可处理请求消息。

context	MessageContext 参数提供对请求消息的访问。
return	boolean 指示处理模式 返回 true 指示连续处理请求处理程序链。HandlerChain 负责调用下一个实体。下一个实体可能是 HandlerChain 中的下一个处理程序；如果此处理程序是链中的最后一个处理程序，则下一个实体是服务端点对象。 返回 false 表示阻塞请求处理程序链。在这种情况下，进一步处理请求处理程序链将被阻塞，目标服务端点未分发。JAX-RPC 运行时系统负责使用 SOAPMessageContext 调用响应处理程序链的下一个处理程序。Handler 实现类负责使用 handleRequest 和/或 handleResponse 方法设置相应的响应 SOAP 消息。在默认处理模型中，响应处理程序链从同一个 Handler 实例（该实例返回 false）开始处理，按执行顺序的反方向进行。
Throws	JAXRPCException: 此异常指示特定于处理程序的运行时错误。如果 handleRequest 方法抛出 JAXRPCException，则 HandlerChain 将终止此处理程序链的进一步处理。在服务器端，HandlerChain 生成一个 SOAP 错误，指示导致消息无法处理的原因不是消息本身的内容，而是处理消息过程中出现的运行时错误。在客户端，异常传播到客户端代码
Throws	SOAPFaultException: 指示 SOAP 错误。Handler 实现类负责使用 handleRequest 和/或 handleFault 方法设置 SOAP 消息中的 SOAP 错误。如果服务器端请求处理程序的 handleRequest 方法抛出 SOAPFaultException，则 HandlerChain 将终止此处理程序链中请求处理程序的进一步处理，并对 SOAP 消息上下文中的 HandlerChain 调用 handleFault 方法。接下来，HandlerChain 对处理程序链中已注册的处理程序调用 handleFault，从抛出异常的 Handler 实例开始，按执行顺序的反方向进行。客户端请求处理程序的 handleRequest 方法不应抛出 SOAPFaultException。

英文文档：

handleRequest

boolean handleRequest(MessageContext context)

The handleRequest method processes the request message.

Parameters:

context - MessageContext parameter provides access to the request message.

Returns:

boolean Indicates the processing mode

• Return true to indicate continued processing of the request handler chain. The HandlerChain takes the responsibility of invoking the next entity. The next entity may be the next handler in the HandlerChain or if this handler is the last handler in the chain, the next entity is the service endpoint object.
• Return false to indicate blocking of the request handler chain. In this case, further processing of the request handler chain is blocked and the target service endpoint is not dispatched. The JAX-RPC runtime system takes the responsibility of invoking the response handler chain next with the SOAPMessageContext. The Handler implementation class has the the responsibility of setting the appropriate response SOAP message in either handleRequest and/or handleResponse method. In the default processing model, the response handler chain starts processing from the same Handler instance (that returned false) and goes backward in the execution sequence.

Throws:

JAXRPCException - This exception indicates 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

SOAPFaultException - This 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.

public boolean handleResponse(MessageContext context)
handleResponse 方法可处理响应 SOAP 消息。

context	MessageContext 参数提供对响应 SOAP 消息的访问
return	指示处理模式的 boolean 值 返回 true 指示继续处理响应处理程序链。HandlerChain 对处理程序链中的下一个 Handler 调用 handleResponse 方法。 返回 false 指示阻塞响应处理程序链。在这种情况下，不调用处理程序链中的其他响应处理程序。
Throws	JAXRPCException: 指示特定于处理程序的运行时错误。如果 handleResponse 方法抛出 JAXRPCException，则 HandlerChain 将终止此处理程序链的进一步处理。在服务器端，HandlerChain 生成一个 SOAP 错误，指示导致消息无法处理的原因不是消息本身的内容，而是处理消息过程中出现的运行时错误。在客户端，运行时异常传播到客户端代码。

英文文档：

handleResponse

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

• Return true to indicate continued processing ofthe response handler chain. The HandlerChain invokes the handleResponse method on the next Handler in the handler chain.
• Return false to indicate blocking of the response handler chain. In this case, no other response handlers in the handler chain are invoked.

Throws:

JAXRPCException - Indicates 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.

public boolean handleFault(MessageContext context)
handleFault 方法根据 SOAP 消息处理模型处理 SOAP 错误。

context	MessageContext 参数提供对 SOAP 消息的访问
return	指示处理模式的 boolean 值 返回 true 指示继续处理 SOAP 错误。HandlerChain 对处理程序链中的下一个 Handler 调用 handleFault 方法。 返回 false 指示结束 SOAP 错误的处理。在这种情况下，不调用处理程序链中的其他处理程序。
Throws	JAXRPCException: 指示特定于处理程序的运行时错误。如果 handleFault 方法抛出 JAXRPCException，则 HandlerChain 将终止此处理程序链的进一步处理。在服务器端，HandlerChain 生成一个 SOAP 错误，指示导致消息无法处理的原因不是消息本身的内容，而是处理消息过程中出现的运行时错误。在客户端，JAXRPCException 传播到客户端代码。

英文文档：

handleFault

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

• Return true to indicate continued processing of SOAP Fault. The HandlerChain invokes the handleFault method on the next Handler in the handler chain.
• Return false to indicate end of the SOAP fault processing. In this case, no other handlers in the handler chain are invoked.

Throws:

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.

public void init(HandlerInfo config)
init 方法使 Handler 实例能够初始化自身。init 方法将处理程序配置作为 HandlerInfo 实例传递。HandlerInfo 用于在初始化期间配置 Handler（例如：建立对外部资源或服务的访问）。

使用 init 方法，Handler 可以访问任何资源（例如，访问日志服务或数据库），并将这些资源作为其实例变量的一部分维护。注意，这些实例变量不得具有任何特定于各种处理方法所执行的 SOAP 消息处理的状态。

HandlerInfo	初始化此处理程序的配置
Throws	JAXRPCException: 如果初始化处理程序失败

英文文档：

init

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:

HandlerInfo - Configuration for the initialization of this handler

Throws:

JAXRPCException - If initialization of the handler fails

public void destroy()
destroy 方法指示 Handler 实例的生命周期结束。Handler 实现类应该释放其资源，并在 destroy 方法的实现中执行 cleanup 操作。

Throws

JAXRPCException: 如果销毁过程中发生错误

英文文档：

destroy

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:

JAXRPCException - If any error during destroy

public javax.xml.namespace.QName[] getHeaders()
获取可以由此处理程序实例处理的头块。

return

此处理程序实例处理的头块的 QName 所组成的数组。QName 是头块最外面的元素的限定名称。

英文文档：

getHeaders

QName[] getHeaders()

Gets the header blocks that can be 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.

Copyright 2007 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.