A.7. JAX-WS Common API Reference

Web 服务端点和客户端之间共享多个 JAX-WS 开发概念。其中包括处理程序框架、消息上下文和错误处理。

处理程序框架

处理程序框架通过在客户端运行时和端点（服务器组件）绑定的 JAX-WS 协议实施。代理和 Dispatch 实例统称为绑定供应商，每个实例都使用协议绑定将其抽象功能绑定到特定的协议。

客户端和服务器端处理程序组织成一个有序的列表，称为处理程序链。每次发送或收到消息时，都会调用处理程序链中的处理程序。入站消息由处理程序处理，然后绑定提供程序处理它们。出站消息在绑定提供程序处理后由处理程序处理。

通过消息上下文调用处理程序，提供访问和修改入站和出站消息的方法，以及管理一组属性。消息上下文属性有助于各个处理程序之间的通信，以及处理程序与客户端和服务实施之间的通信。不同类型的处理程序通过不同类型的消息上下文调用。

消息上下文

MessageContext 界面是所有 JAX-WS 消息上下文的超级接口。它通过 额外的方法和常量扩展 Map<String,Object> 来管理一组属性，使处理程序链中的处理程序能够共享相关状态。例如，处理程序可能使用 put 方法将 属性插入到消息上下文中。之后，处理程序链中的一个或多个处理程序可使用 get 方法获取消息。

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

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

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

错误处理

应用程序可能会引发 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 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");
}

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 规范。