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 方法获取消息。

属性作为 APPLICATIONHANDLER 限定。所有属性都可用于特定端点的消息交换模式(MEP)实例的所有处理程序。例如,如果逻辑处理程序将 属性放入消息上下文中,该属性也可用于 MEP 实例执行期间链中的任何协议处理程序。

注意

异步消息交换模式(MEP)允许在 HTTP 连接级别异步发送和接收消息。您可以通过在请求上下文中设置其他属性来启用它。

作用于 APPLICATION 级别的属性也可用于客户端应用和服务端点实施。属性 的默认作用域HANDLER

逻辑和 SOAP 消息使用不同的上下文。

逻辑消息上下文
调用逻辑处理程序时,它们会收到类型为 LogicalMessageContext 的消息上下文。LogicalMessageContext 使用获取和修改消息有效负载的方法扩展 MessageContext。它不提供对消息特定协议方面的访问权限。协议绑定定义通过逻辑消息上下文可以获得消息的哪些组件。SOAP 绑定中部署的逻辑处理器可以访问 SOAP 正文的内容,但不能访问 SOAP 标头。另一方面,XML/HTTP 绑定定义逻辑处理程序可以访问消息的整个 XML 有效负载。
SOAP 消息上下文
调用 SOAP 处理程序时,它们将接收 SOAPMessageContextSOAPMessageContext 使用获取和修改 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 规范

Red Hat logoGithubRedditYoutubeTwitter

学习

尝试、购买和销售

社区

关于红帽文档

通过我们的产品和服务,以及可以信赖的内容,帮助红帽用户创新并实现他们的目标。

让开源更具包容性

红帽致力于替换我们的代码、文档和 Web 属性中存在问题的语言。欲了解更多详情,请参阅红帽博客.

關於紅帽

我们提供强化的解决方案,使企业能够更轻松地跨平台和环境(从核心数据中心到网络边缘)工作。

© 2024 Red Hat, Inc.