A.7. JAX-WS Common API Reference
Web 服务端点和客户端之间共享多个 JAX-WS 开发概念。其中包括处理程序框架、消息上下文和错误处理。
处理程序框架
处理程序框架通过在客户端运行时和端点(服务器组件)绑定的 JAX-WS 协议实施。代理和 Dispatch
实例统称为绑定供应商,每个实例都使用协议绑定将其抽象功能绑定到特定的协议。
客户端和服务器端处理程序组织成一个有序的列表,称为处理程序链。每次发送或收到消息时,都会调用处理程序链中的处理程序。入站消息由处理程序处理,然后绑定提供程序处理它们。出站消息在绑定提供程序处理后由处理程序处理。
通过消息上下文调用处理程序,提供访问和修改入站和出站消息的方法,以及管理一组属性。消息上下文属性有助于各个处理程序之间的通信,以及处理程序与客户端和服务实施之间的通信。不同类型的处理程序通过不同类型的消息上下文调用。
- 逻辑处理程序
-
逻辑处理程序仅对消息上下文属性和消息有效负载执行操作。逻辑处理程序是独立于协议的,不能影响消息的特定协议部分。逻辑处理程序实施接口
javax.xml.ws.handler.LogicalHandler
. - 协议处理程序
-
协议处理程序对消息上下文属性和特定于协议的消息执行操作。协议处理程序特定于特定的协议,可以访问和更改消息的特定协议方面。协议处理程序实施派生自
javax.xml.ws.handler.Handler
的任何接口,但javax.xml.ws.handler.LogicalHandler
. - 服务端点处理程序
在服务端点上,处理程序利用
@HandlerChain
注释来定义。处理程序链文件的位置可以是externalForm
中的绝对java.net.URL
,也可以是来自源文件或类文件的相对路径。@WebService @HandlerChain(file = "jaxws-server-source-handlers.xml") public class SOAPEndpointSourceImpl { ... }
- 服务客户端处理程序
在 JAX-WS 客户端上,处理程序通过使用
@HandlerChain 注释(
如服务端点)定义,或者使用 JAX-WS 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);
需要调用
setHandlerChain
方法。
消息上下文
MessageContext
界面是所有 JAX-WS 消息上下文的超级接口。它通过 额外的方法和常量扩展 Map<String,Object>
来管理一组属性,使处理程序链中的处理程序能够共享相关状态。例如,处理程序可能使用 put 方法将
属性插入到消息上下文中。之后,处理程序链中的一个或多个处理程序可使用 get
方法获取消息。
属性作为 APPLICATION
或 HANDLER 限定
。所有属性都可用于特定端点的消息交换模式(MEP)实例的所有处理程序。例如,如果逻辑处理程序将 属性放入消息上下文中,该属性也可用于 MEP 实例执行期间链中的任何协议处理程序。
异步消息交换模式(MEP)允许在 HTTP 连接级别异步发送和接收消息。您可以通过在请求上下文中设置其他属性来启用它。
作用于 APPLICATION
级别的属性也可用于客户端应用和服务端点实施。属性 的默认作用域
是 HANDLER
。
逻辑和 SOAP 消息使用不同的上下文。
- 逻辑消息上下文
-
调用逻辑处理程序时,它们会收到类型为
LogicalMessageContext
的消息上下文。LogicalMessageContext
使用获取和修改消息有效负载的方法扩展MessageContext
。它不提供对消息特定协议方面的访问权限。协议绑定定义通过逻辑消息上下文可以获得消息的哪些组件。SOAP 绑定中部署的逻辑处理器可以访问 SOAP 正文的内容,但不能访问 SOAP 标头。另一方面,XML/HTTP 绑定定义逻辑处理程序可以访问消息的整个 XML 有效负载。 - SOAP 消息上下文
-
调用 SOAP 处理程序时,它们将接收
SOAPMessageContext
。SOAPMessageContext
使用获取和修改 SOAP 消息有效负载的方法扩展MessageContext
。
错误处理
应用程序可能会引发 SOAPFaultException
或特定于应用程序的用户异常。对于后者,如果它们还不是部署的一部分,则在运行时生成所需的故障打包程序 Bean。
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"); }
JAX-WS Annotations
JAX-WS API 提供的注释在 JSR-224 中定义。这些注释位于 javax.xml.ws
软件包中。与 XML Web 服务的 Jakarta EE 等效于 Jakarta XML Web 服务规范 2.3 规范。
JWS API 提供的注释在 JSR-181 中定义。这些注释位于 javax.jws
软件包中。Web Services 元数据的 Jakarta EE 等效于 Jakarta Web Services 元数据规范 2.1 规范。