A.7. Jakarta XML Web 服务通用 API 参考

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

处理程序框架

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

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

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

消息上下文

MessageContext 界面是所有 Jakarta XML Web Services 消息上下文的超级界面。它通过 额外的方法和常量扩展 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");
}

Jakarta XML Web 服务注释

Jakarta XML Web Services API 提供的注释在 Jakarta XML Web Services Specification 2.3 规范 2.3 规范 中定义，这些注释位于 javax.xml.ws 软件包中。

JWS API 提供的注解在 Web Services Metadata 中定义，遵循 Jakarta Web Services Metadata 规范 2.1 规范。这些注释位于 javax.jws 软件包中。