JAX-WS
Java™ API for XML-Based Web Services (JAX-WS) 是下一代 Web Service 编程模型,它补充 Java API for XML-based RPC (JAX-RPC) 编程模型提供的基础。通过使用 JAX-WS,就可通过使用动态代理和 Java 注释,借助于 Java 应用程序的更不依赖于平台的特征,简化 Web Service 和客户机的开发。
JAX-WS 是一种编程模型,它通过支持将基于注释的标准模型用于开发 Web Service 应用程序和客户机来简化应用程序开发。JAX-WS 技术在战略上调整了自身以适合当前朝着更以文档为中心的消息传递模型发展的业界趋势,并且替换了由 JAX-RPC 定义的远程过程调用编程模型。虽然 JAX-RPC 编程模型和应用程序仍然受本产品支持,但是 JAX-RPC 具有局限性并且不支持各种复杂的以文档为中心的服务。JAX-WS 是用于开发 Web Service 的战略性编程模型,并且是 Java Platform, Enterprise Edition 6 (Java EE 6) 的必需部分。JAX-WS 也称为 JSR 224。
JAX-WS 2.2 规范将取代 JAX-WS 2.1 规范并包括此规范的功能。JAX-WS 2.2 添加了使用与 WebServiceFeature 相关的注释(例如,@MTOM、@Addressing 和 @RespectBinding 注释)的客户端支持。JAX-WS 2.1 先前已在服务器上添加对于这些注释的支持。现在,还可以通过将 WS-Policy 断言添加至 WSDL 文档来实现对客户机或服务启用和配置 WS-Addressing 支持。此外,Web Services for Java EE 1.3 规范引入了对于这些与 WebServiceFeature 相关的注释的支持,还支持使用部署描述符元素在客户机和服务器上配置这些功能。JAX-WS 2.2 要求使用 Java XML 绑定体系结构 (JAXB) V2.2 来进行数据绑定。
JAX-WS 编程标准的实现提供用于开发 Web Service 和客户机的以下增强功能:
- Java 应用程序的增强的平台独立性。
通过使用 JAX-WS API,借助 Java 应用程序的增强的平台独立性简化了 Web Service 和客户机的开发。JAX-WS 利用动态代理机制来向可插入提供程序提供正式的委派模型。这是通过 JAX-RPC 获得的增强功能,它依赖于生成特定于供应商的存根以进行调用。
- 注释
JAX-WS 支持对带有元数据的 Java 类进行注释,以指示 Java 类是 Web Service。JAX-WS 支持使用基于“用于 Java 编程语言的元数据设施”(JSR 175) 规范和“用于 Java 平台的 Web Service 元数据”(JSR 181) 规范的注释以及 JAX-WS 2.2 规范所定义的注释。在 Java 源代码和 Java 类中使用注释可以简化 Web Service 的开发。使用注释来定义通常在部署描述符文件和 WSDL 文件中指定的信息或用于将元数据从 XML 和 WSDL 文件映射到源工件中的信息。
例如,可在 Java 源代码中嵌入一个简单的 @WebService 标记来将 Bean 显示为 Web Service。
@WebService 注释告诉服务器运行时环境将该 Bean 上的所有公用方法显示为 Web Service。其他详细程度级别可通过在各方法或参数上添加其他注释来控制。使用注释可以更容易将 Java 工件显示为 Web Service。另外,当使用一些自顶向下映射工具从 WSDL 文件创建工件时,注释包括在源代码和 Java 类中,作为与源文件一起捕获元数据的方法。@WebService public class QuoteBean implements StockQuote { public float getQuote(String sym) { ... } }
使用注释也可改善在团队结构中 Web Service 的开发,因为您不需要如 JAX-RPC Web Service 所需那样,在单个或公共部署描述符中定义每个 Web Service。将注释与 JAX-WS Web Service 配合使用允许并行开发服务和必需的元数据。
对于 JAX-WS Web Service,可以选择是否使用 webservices.xml 部署描述符,这是因为您可以使用注释来指定该部署描述符文件所包含的所有信息。可以使用部署描述符文件来扩充或覆盖现有 JAX-WS 注释。您在 webservices.xml 部署描述符中定义的任何信息将覆盖由注释指定的任何相应信息。
例如,如果 JAX-WS Web Service 的服务实现类包含下列各项:- @WebService 注释:
@WebService(wsdlLocation=”http://myhost.com/location/of/the/wsdl/ExampleService.wsdl”)
- webservices.xml 文件指定
WSDL 文档的其他文件名,如下所示:
<webservices> <webservice-description> <webservice-description-name>ExampleService</webservice-description-name> <wsdl-file>META-INF/wsdl/ExampleService.wsdl</wsdl-file> ... </webservice-description> </webservices>
- @WebService 注释:
- 以异步方式调用 Web Service
借助于 JAX-WS,可以同步或异步方式调用 Web Service。以异步方式调用 Web Service 时,JAX-WS 添加了对轮询和回调机制的支持。通过使用轮询模型,客户机可以发出请求和取回响应对象,对响应对象执行轮询以确定服务器是否已响应。当服务器响应时,将检索到实际的响应。通过使用回调模型,客户机提供回调处理程序来接受和处理入站响应对象。轮询模型和回调模型都支持客户机集中于继续处理工作,而不等待响应返回,同时提供一个更动态和更有效的模型来调用 Web Service。
例如,Web Service 接口可包含适用于同步和异步请求的方法。在以下示例中,异步请求用粗体进行了标识:@WebService public interface CreditRatingService { // sync operation Score getCreditScore(Customer customer); // async operation with polling Response<Score> getCreditScoreAsync(Customer customer); // async operation with callback Future<?> getCreditScoreAsync(Customer customer, AsyncHandler<Score> handler); }
使用回调机制的异步调用需要客户机程序员的其他输入。回调是一个包含应用程序代码的对象,在接收到异步响应时将运行该代码。使用以下代码示例来调用异步回调处理程序:CreditRatingService svc = ...; Future<?> invocation = svc.getCreditScoreAsync(customerFred, new AsyncHandler<Score>() { public void handleResponse ( Response<Score> response) { Score score = response.get(); // do work here... } } );
使用以下代码示例来调用异步轮询客户机:CreditRatingService svc = ...; Response<Score> response = svc.getCreditScoreAsync(customerFred); while (!response.isDone()) { // Complete an action while we wait. } // No cast needed, because of generics. Score score = response.get();
- 使用资源注入
JAX-WS 支持资源注入以进一步简化 Web Service 的开发。JAX-WS 使用 Java EE 5 的此关键功能部件将在 Java 运行时环境中创建和初始化公共资源的负担从 Web Service 应用程序转移给应用程序容器环境本身。JAX-WS 支持 JSR-250 中为资源注入和应用程序在其运行时环境中的生命周期定义的一部分注释。
应用程序服务器还支持使用 @Resource 或 @WebServiceRef 注释来声明 JAX-WS 受管客户机以及请求注入 JAX-WS 服务和端口。在字段或方法中使用其中任一注释时,该注释会导致注入 JAX-WS 服务或端口实例。使用这些注释还会导致将注释所指定的类型绑定到 JNDI 名称空间。
@Resource 注释由包括在 Java Platform, Enterprise Edition 5 (Java EE 5) 中的 JSR-250(公共注释)规范定义。通过将 @Resource 注释放置在服务端点实现类中类型为 javax.xml.ws.WebServiceContext 的变量上,可以请求资源注入并收集与该特定端点调用相关的 javax.xml.ws.WebServiceContext 接口。从 WebServiceContext 接口中,您可以收集请求的 MessageContext(该请求与使用 getMessageContext() 方法的特定方法调用相关联)。
@WebServiceRef 注释由 JAX-WS 规范进行定义。
以下示例演示将 @Resource 和 @WebServiceRef 注释用于资源注入:@WebService public class MyService { @Resource private WebServiceContext ctx; @Resource private SampleService svc; @WebServiceRef private SamplePort port; public String echo (String input) { … } }
有关资源注入的更多信息,请参阅 JAX-WS 规范的 5.2.1 和 5.3 节。
- 使用 JAXB 2.2 的数据绑定
JAX-WS 利用 Java XML 绑定体系结构 (JAXB) 2.2 API 和工具作为 Java 对象与 XML 文档之间的映射的绑定技术。JAX-WS 工具依赖 JAXB 工具对 Java 对象与 XML 文档之间的双向映射执行缺省数据绑定。JAXB 数据绑定替换 JAX-RPC 规范描述的数据绑定。
JAX-WS 2.2 要求使用 JAXB 2.2 进行数据绑定。JAXB 2.2 对其注释稍作增强,从而改进了模式的生成并且能够更好地与 JAX-WS 进行集成。
- 动态和静态客户机
JAX-WS 的动态客户机 API 称为 Dispatch client (javax.xml.ws.Dispatch)。Dispatch client 是面向 XML 消息传递的客户机。数据以 PAYLOAD 或 MESSAGE 方式发送。使用 PAYLOAD 方式时,分派客户机只负责提供 <soap:Body> 的内容,JAX-WS 添加 <soap:Envelope> 和 <soap:Header> 元素。使用 MESSAGE 方式时,分派客户机负责提供整个 SOAP 包络,其中包括 <soap:Envelope>、<soap:Header> 和 <soap:Body> 元素。JAX-WS 不会将任何其他内容添加到消息中。Dispatch client 支持使用回调或轮询机制的异步调用。
JAX-WS 的静态客户机编程模型称为代理客户机。代理客户机根据必须提供的服务端点接口 (SEI) 调用 Web Service。
- 支持 MTOM
通过使用 JAX-WS,您可以随 Web Service 请求一起发送二进制附件(例如,图像或文件)。JAX-WS 添加了对二进制数据的优化传输的支持,如消息传输优化机制 (MTOM) 指定那样。
- 多种数据绑定技术
JAX-WS 向最终用户显示以下绑定技术:XML Source、SOAP Attachments API for Java (SAAJ) 1.3 和 Java XML 绑定体系结构 (JAXB) 2.2。XML Source 使用户能够将 javax.xml.transform.Source(它表示要处理的 Source 对象中的数据)传递到运行时环境。SAAJ 1.3 现在能够通过接口传递整个 SOAP 文档而不仅仅是有效内容。此操作由通过接口传递 SAAJ SOAPMessage 对象的客户机完成。JAX-WS 利用 JAXB 2.2 支持作为 Java 与 XML 之间的数据绑定技术选项。
- SOAP 1.2 支持
已向 JAX-WS 2.0 添加对 SOAP 1.2 的支持。JAX-WS 支持 SOAP 1.1 和 SOAP 1.2,因此您可以随 Web Service 请求一起发送二进制附件(例如,图像或文件)。JAX-WS 添加了对二进制数据的优化传输的支持,如 MTOM 指定那样。
- 开发工具
JAX-WS 提供了 wsgen 和 wsimport 命令行工具,用于为 JAX-WS Web Service 生成可移植工件。创建 JAX-WS Web Service 时,可以从 WSDL 文件或实现 Bean 类开始。如果从实现 Bean 类开始,那么使用 wsgen 命令行工具来生成所有 Web Service 服务器工件,包括 WSDL 文件(如果请求的话)。如果从 WSDL 文件开始,那么使用 wsimport 命令行工具来为服务器或客户机生成所有 Web Service 工件。wsimport 命令行工具处理带有模式定义的 WSDL 文件以生成可移植工件,这些工件包括服务类、服务端点接口类和相应 XML 模式的 JAXB 2.2 类。
- 支持 Web Services for Java EE V1.3
Web Services for Java EE V1.3 规范支持通过使用注释和部署描述符条目对 JAX-WS 服务和客户机配置 MTOM、寻址和 RespectBinding 功能。
- 支持对 WRAPPED 参数类型和返回类型使用空的 targetNamespaceJAX-WS 2.2 支持方法参数和返回类型。在 JAX-WS Web Service 操作中,您可以使用操作参数和可选返回类型来定义 Web Service 操作。如果操作参数和返回类型定义了空的 targetNamespace 属性(即,使用 @WebParam 或 @WebResult 注释为 targetNamespace 属性指定 "" 值),那么 JAX-WS 运行时环境将按以下方式表现:
- 如果操作为文档类型、参数类型为 WRAPPED 并且参数未映射至头,那么会使用操作参数和返回类型来映射空的名称空间。
- 如果参数类型不为 WRAPPED,那么会使用通过使用 @WebParam 或 @WebResult 注释指定的 targetNamespace 参数的值。