Java API for XML Web Service

Java™ API for XML-based Web Service(JAX-WS,也称为 JSR-224)是下一代 Web Service 编程模型,它扩展了 Java API for XML-based RPC (JAX-RPC) 编程模型提供的基础。通过 JAX-WS,并使用动态代理和 Java 注释,借助于 Java 应用程序的更不依赖于平台的特征,简化 Web Service 和客户机的开发。此产品中包括的 Web Service 工具支持 JAX-WS 2.0、2.1 和 2.2。

JAX-WS 是一种新的编程模型,它通过支持将基于注释的标准模型用于开发 Web Service 应用程序和客户机来简化应用程序开发。JAX-WS 编程标准在战略上调整了自身以适合当前朝着更以文档为中心的消息传递模型发展的业界趋势,并且替换了由 JAX-RPC 定义的远程过程调用编程模型。虽然此产品仍然支持 JAX-RPC 编程模型和应用程序,但是 JAX-RPC 具有局限性并且不支持许多当前的以文档为中心的服务。JAX-WS 是用于开发 Web Service 的战略性编程模型,并且是 Java EE 5 平台的必需部分。

JAX-WS 编程标准的实现提供用于开发 Web Service 和客户机的以下增强功能:
Java 应用程序的更好的不依赖于平台的特征
通过使用 JAX-WS,借助于 Java 应用程序的更好的不依赖于平台的特征,简化 Web Service 和客户机的开发。JAX-WS 利用动态代理,而 JAX-RPC 则使用所生成的存根。动态代理客户机根据所生成或提供的服务端点接口 (SEI) 调用 Web Service。动态代理客户机类似于 JAX-RPC 编程模型中的存根客户机。虽然 JAX-WS 动态代理客户机与 JAX-RPC 存根客户机都基于从 WSDL 文件生成的服务端点接口 (SEI),但仍存在一个主要差别。动态代理客户机在运行时使用 Java 5 动态代理功能动态生成,而基于 JAX-RPC 的存根客户机是由工具生成的不可移植的 Java 文件。与 JAX-RPC 存根客户机不同,动态代理客户机不要求您在应用程序服务器上运行客户机之前针对不同的供应商重新生成存根,因为生成的接口不需要特定供应商信息。 有关使用动态代理客户机的更多信息,请参阅 JAX-WS 2.0 规范的第 4 章。
注释

JAX-WS 支持对带有元数据的 Java 类进行注释,以指示 Java 类是 Web Service。JAX-WS 支持使用基于“用于 Java 编程语言的元数据设施”(JSR 175) 规范和“用于 Java 平台的 Web Service 元数据”(JSR 181) 规范的注释以及 JAX-WS 2.0 规范所定义的注释。在 Java 源代码和 Java 类中使用注释可以简化 Web Service 的开发,其实现方式是定义一些通常从部署描述符文件和 WSDL 文件中获取的附加信息,或者将元数据从 XML 和 WSDL 文件映射到源工件。

例如,可在 Java 源代码中嵌入一个简单的 @WebService 标记来将 Bean 显示为 Web Service。

@WebService

public class QuoteBean implements StockQuote {

       public float getQuote(String sym) { ... }

}

@WebService 注释告诉服务器运行时环境将该 Bean 上的所有公用方法显示为 Web Service。其他详细程度级别可通过在各方法或参数上添加其他注释来控制。使用注释可以更容易将 Java 工件显示为 Web Service。另外,当使用一些自顶向下映射工具从 WSDL 文件创建工件时,注释包括在源代码和 Java 类中,作为与源文件一起捕获元数据的方法。

以异步方式调用 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()) {
		// do something while we wait
}

// no cast needed, thanks to generics
	       Score score = response.get();
</Score>
使用资源注入

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() 方法的特定方法调用相关联)。

以下示例演示将 @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 利用 JAXB API 和工具作为 Java 对象与 XML 文档之间的映射的绑定技术。JAX-WS 工具依赖 JAXB 工具对 Java 对象与 XML 文档之间的双向映射执行缺省数据绑定。JAXB 数据绑定替换 JAX-RPC 规范描述的数据绑定。

WebSphere® Application Server V7.0 支持 JAXB 2.1 规范。JAX-WS 2.1 需要 JAXB 2.1 以进行数据绑定。JAXB 2.1 提供了增强功能(例如改进的编译支持以及对 @XMLSeeAlso 注释的支持)以及完整的模式 1.0 支持。

WebSphere Application Server V8.0 或更高版本以及 WebSphere Application Server Liberty 概要文件 V8.5.5 支持 JAXB 2.2 规范。 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 不会向消息添加任何额外内容。分派客户机支持使用回调或轮询机制的异步调用。 </soap:Body></soap:Header></soap:Envelope></soap:Header></soap:Envelope></soap:Body>

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.0。XML Source 使用户能够将 javax.xml.transform.Source(它表示 Source 对象中要传递至运行时的数据)传递到运行时。SAAJ 1.3 现在能够通过接口传递整个 SOAP 文档而不仅仅是有效内容。这通过客户机通过接口传递 SAAJ SOAPMessage 对象实现。JAX-WS 利用 JAXB 2.0 支持作为 Java 与 XML 之间的数据绑定技术选项。
SOAP 1.2 支持
已向 JAX-WS 2.0 添加对 SOAP 1.2 的支持。JAX-WS 支持 SOAP 1.1 和 SOAP 1.2。SOAP 1.2 更明确地定义了 SOAP 处理模型,该模型中移除了许多在缺少 Web Service 互操作性 (WS-I) 概要文件的情况下有时会导致互操作性问题的不确定性。SOAP 1.2 应可降低不同供应商之间 SOAP 1.2 实现发生互操作性问题的机率。请不要与旧版本进行互操作。
对方法参数和返回类型的支持
JAX-WS 2.2 支持方法参数和返回类型。在 JAX-WS Web Service 操作中,您可以使用操作参数和可选返回类型来定义 Web Service 操作。如果操作参数和返回类型定义了空的 targetNamespace 属性(即,使用 @WebParam 或 @WebResult 注释为 targetNamespace 属性指定 "" 值),那么 JAX-WS 运行时环境将按以下方式表现:
  • 如果操作为文档类型,那么参数类型为 WRAPPED 并且参数未映射至头。将使用操作参数和返回类型来映射空的名称空间。
  • 如果参数类型不为 WRAPPED,那么会使用通过使用 @WebParam 或 @WebResult 注释指定的 targetNamespace 参数的值。

JAX-WS 2.1.6

从 Java 类创建 JAX-WS Web Service 时,该类的公共方法会作为操作予以公开并变为 Web Service 的 WSDL 约定的一部分。这些方法和操作之间的映射主要由 JSR-181 和 JSR-250 进行管理。 通过这些规则,将在符合以下条件时公开 Java 类中的公共方法及其层次结构(上至但不包括 java.lang.Object):
  • 使用 @WebMethod 或 @WebMethod(exclude=false) 对该方法添加注释,并且包含的类具有 @WebService 注释
  • 该方法不具有 @WebMethod 注释,但包含的类具有 @WebService 注释并且未使用 @WebMethod 或 @WebMethod(exclude=false) 对任何其他方法添加注释
JAX-WS 2.1.6 变更了如何在 Web Service 接口上公开 Java 类的方法的规则。现在,将在符合以下条件时公开 Java 类中的公共方法及其层次结构(上至但不包括 java.lang.Object):
  • 该方法具有 @WebMethod 或 @WebMethod(exclude=false) 注释。
  • 该方法不具有 @WebMethod 注释,但包含的类具有 @WebService 注释。
示例:
public class Base
{
  @WebMethod(exclude=false)
  public void superExposed(String s) {}
  public String supernoanno(String s) {}
}

@WebService
public class BeanImpl extends Base
{
  @WebMethod(exclude=false)
  public void exposed(String s) {}
  public String nonpublic(String s) {}
}
在 JAX-WS 2.1.6 之前,只有已公开的方法才是 public void exposed(String s)。在 JAX-WS 2.1.6 及更高版本中,将公开以下方法:
public void exposed(String s)
public String nonpublic(String s)
public void superExposed(String s)

WebSphere Application Server V7.0.0.7 和更高版本通过 IBM® JDK 6 SR6 包括了这些更改。要启用工作台以提供关于如何使用 JAX-WS 2.1.6 的指南,请转至窗口 > 首选项 > 常规 > 服务策略 > WebSphere 编程模型 > JAX-WS,然后将 JAX-WS 2.1.6 方法公开指南设置设定为 true

JAX-WS 2.2

支持 JAX-WS V2.2 和 Web Service for Java EE (JSR 109) V1.3 规范的服务器运行时环境为:
  • WebSphere Application Server Liberty 概要文件 V8.5.5
  • WebSphere Application Server V8.5
  • WebSphere Application Server V8.0

JAX-WS 2.2 规范将取代 JAX-WS 2.1 规范并包括此规范的功能。JAX-WS 2.2 添加了使用与 WebServiceFeature 相关的注释(例如,@MTOM、@Addressing 和 @RespectBinding 注释)的客户端支持。JAX-WS 2.1 先前已在服务器上添加对于这些注释的支持。此外,Web Service for Java EE 1.3 规范引入了对于这些与 WebServiceFeature 相关的注释的支持,还支持使用部署描述符元素在客户机和服务器上配置这些功能。JAX-WS 2.2 要求使用 Java XML 绑定体系结构 (JAXB) V2.2 来进行数据绑定。

有关 JAX-WS 的更多信息,请参阅正式 JSR-224 规范:JSR 224:Java API for XML-Based Web Service (JAX-WS) 2.0

指示主题类型的图标 概念主题
信息中心的条款和条件 | 反馈

时间戳记图标 最近一次更新时间: 2014 年 4 月 17 日

文件名:cjaxws.html