使用注释来开发 JAX-WS Web Service

Java™ API for XML-Based Web Services (JAX-WS) 支持两种不同的服务端点实现类型:标准 Web Service 端点接口,以及使服务能够在 XML 消息级别工作的新的 Provider 接口。通过在服务端点实现或客户机上使用注释,您可以将服务端点定义为 Web Service。

关于此任务

此任务是开发 JAX-WS Web Service 的必需步骤。

JAX-WS 技术支持基于标准服务端点接口和提供程序接口来实现 Web Service。JAX-WS 端点类似于 Java API for XML-based RPC (JAX-RPC) 规范中的端点实现。与 JAX-RPC 不同的是,对服务端点接口 (SEI) 的需求对于 JAX-WS Web Service 是可选的。没有相关联 SEI 的 JAX-WS 服务会视为具有隐式 SEI;而具有相关联 SEI 的服务会视为具有显式 SEI。JAX-WS 所需的服务端点接口较 JAX-RPC 所需的服务端点接口更通用。借助 JAX-WS,SEI 不需要扩展 JAX-RPC 规范所需的 java.rmi.Remote 接口。

JAX-WS 编程模型还使用通过元数据对 Java 类进行注释的支持,以将服务端点实现定义为 Web Service 以及定义客户机如何访问 Web Service。JAX-WS 基于 Java 编程语言 (JSR 175) 规范的元数据工具、Java 平台 (JSR 181) 规范的 Web Service 元数据以及由 JAX-WS 2.0 (JSR 224) 规范定义的注释(包括 Java XML 绑定体系结构 (JAXB) 注释)来支持注释。使用注释,服务端点实现可以独立描述 Web Service,而不需要 WSDL 文件。注释可以提供配置服务端点实现或 Web Service 客户机所需要的所有 WSDL 信息。可以对客户机和服务器所使用的服务端点接口,或者服务器端服务实现类指定注释。

有关支持的标准和规范的详细信息,请参阅 Web Service 规范与 API 文档。

如果从现有 Java 类开始开发 JAX-WS Web Service(称为自底向上方法),那么必须使用 @WebService (javax.jws.WebService) 注释或 @WebServiceProvider (javax.xml.ws.Provider) 注释来对类进行注释,以便在最初将类定义为 Web Service。@WebService 注释将服务定义为基于 SEI 的端点,而 @WebServiceProvider 注释将服务定义为基于提供程序的端点。

开发基于 SEI 的 JAX-WS Web Service

对于基于 SEI 的端点,服务端点接口 (SEI) 都会声明由特定 Web Service 提供的业务方法,而不论 SEI 是 Java 类还是 Java 接口。Web Service 客户机可以对 JAX-WS 端点调用的仅有方法是显式或隐式 SEI 中定义的业务方法。

所有基于 SEI 的端点都必须在实现类中包含 @WebService 注释。如果服务实现使用显式 SEI,那么 @WebService 注释上的 endpointInterface 属性必须引用该接口。如果服务实现未使用显式 SEI,那么服务会由实现类隐式地描述,因此是隐式 SEI。

使用 Provider 接口来开发 JAX-WS Web Service

JAX-WS 编程模型为提供程序端点引进了 Provider 接口 javax.xml.ws.Provider,作为基于 SEI 的端点的动态替代项。Provider 接口支持对 Web Service 使用更大程度的面向消息传递的方法。使用 Provider 接口,可以创建实现简单接口的 Java 类以生成通用服务实现类。Provider 接口定义了一种方法(即 invoke 方法),在处理各种消息或消息有效内容时,该方法使用泛型来控制输入和输出类型。必须使用 @WebServiceProvider (javax.xml.ws.WebServiceProvider) 注释对所有提供程序端点进行注释。如果服务实现是实现 javax.xml.ws.Provider 接口,那么不能指定 @WebService 注释。

从 WebSphere® Application Server V7.0 开始,将扫描 Java EE 5 应用程序模块(Web 应用程序模块 V2.5 或更高版本,或者 EJB 模块 V3.0 或更高版本)以获取用于标识 JAX-WS 服务和客户机的注释。然而,缺省情况下,考虑到性能方面的因素,不会扫描 Java EE 5 之前的应用程序模块(Web 应用程序模块 V2.4 或更早版本,或者 EJB 模块 V2.1 或更早版本)来获取 JAX-WS 注释。在 V6.1 Feature Pack for Web Services 中,缺省行为是在安装应用程序期间扫描 Java EE 5 之前的 Web 应用程序模块以识别 JAX-WS 服务,以及扫描 Java EE 5 之前的 Web 应用程序模块和 EJB 模块以查找服务客户机。因为 WebSphere Application Server V7.0 和更高版本的缺省行为是不在应用程序安装或服务器启动期间扫描 Java EE 5 之前的模块以获取注释,所以为了保持与先前发行版中功能部件包的向后兼容性,您必须在 Web 应用程序归档 (WAR) 文件或 EJB 模块的 META-INF/MANIFEST.MF 中配置 UseWSFEP61ScanPolicy 属性,或在服务器上定义 Java 虚拟机定制属性 com.ibm.websphere.webservices.UseWSFEP61ScanPolicy 以请求在应用程序安装和服务器启动期间进行扫描。要了解有关注释扫描的更多信息,请参阅 JAX-WS 注释信息。

过程

  1. 确定是要使用 SEI 端点还是 Provider 接口来定义 Web Service。 如果要使用以 Java 为中心的高级抽象来隐藏在 Java 对象及其 XML 表示之间进行转换的详细信息,请考虑使用基于 SEI 的端点来开发 Web Service。但是,如果您想要 Web Service 在 XML 消息级别进行更多的操作,请考虑使用基于提供程序的端点。
  2. 注释服务端点。
    1. 使用 javax.jws.WebService 注释来对基于 SEI 的端点进行注释。
      • 对于基于 SEI 的端点,请使用 javax.jws.WebService 注释对实现类进行注释。可以选择通过定义 @WebService.endpointInterface 属性来指定此端点是显式 SEI,从而显式地引用服务端点接口。在这种情况下,所引用的 Java 接口都必须包含 javax.jws.WebService 注释。如果 endpointInterface 属性未定义或者是空的,那么会将实现 Bean 视为隐式 SEI。可以对服务端点接口的方法添加 @WebMethod 注释以定制 Java 到 WSDL 映射。不论是否指定了 @WebMethod 注释,所有公用方法都视为公开的方法。在包含 exclude 属性的服务端点接口上使用 @WebMethod 注释是不正确的。
      • 如果使用隐式 SEI,那么可以对如何通过选择使用 @WebMethod 注释来公开方法,施行更细粒度的控制。有关更详细的说明,请参阅“在基于 SEI 的 JAX-WS Web Service 中公开方法”信息。
    2. 使用 javax.xml.ws.WebServiceProvider 注释来对基于提供程序的端点进行注释。
      • 对于基于提供程序的端点,请使用 javax.xml.ws.WebServiceProvider 注释来对实现类进行注释。与无界类(例如 Provider<T>)相比,只能在实现强类型化 javax.xml.ws.Provider.interface 类(例如 Provider<Source>Provider<SOAPMessage>)的类上指定此注释。强类型化类是一个与特定输入和输出 Java 类型相关联的类,例如 SourceSOAPMessage
        @WebServiceProvider(
                serviceName="StringProviderService", 
                wsdlLocation="META-INF/echostring.wsdl", 
                targetNamespace="http://stringprovider.sample.test.org")
      • (可选)根据 JAX-WS 2.2 规范,如果定义的是基于提供程序的端点,那么提供程序实现返回空值,不需要响应。如果 javax.xml.ws.WebServiceProvider 注释未指定 WSDL,而提供程序 invoke() 方法返回空值,那么 JAX-WS 运行时环境的缺省行为是要返回由 SOAPEnvelope(包含空的 SOAPBody)组成的响应。如果想要 JAX-WS 运行时环境将这种情况解释为“仅请求”操作且不返回响应,那么可以将 JVM 属性 jaxws.provider.interpretNullAsOneway 设置为 True
  3. 了解并应用在基于 SEI 的 JAX-WS Web Service 中将方法公开为操作的最佳实践。

    由于多个 Web Service 规范之间在将哪些方法公开为基于 SEI 的端点的 Web Service 操作方面存在不确定性,因此您可以通过遵循最佳实践来确保不论使用何种 JAX-WS 实现,行为都是一致的。

结果

您已定义了表示 Web Service 应用程序的服务端点实现。请参阅 JAX-WS 注释文档以了解有关受支持的 JAX-WS 注释的更多信息。

样本 JavaBeans 服务端点实现和接口

以下示例说明了简单的显式 JavaBeans 服务端点实现以及相关联的服务端点接口:
/** This is an excerpt from the service implementation file, EchoServicePortTypeImpl.java. 
package com.ibm.was.wssample.echo;
import java.io.ByteArrayInputStream;
import java.io.ByteArrayOutputStream;

import javax.xml.bind.JAXBContext;
import javax.xml.bind.Marshaller;
import javax.xml.bind.Unmarshaller;
import javax.xml.transform.stream.StreamSource;

@javax.jws.WebService(serviceName = "EchoService", endpointInterface = 
"com.ibm.was.wssample.echo.EchoServicePortType", targetNamespace="http://com/ibm/was/wssample/echo/", 
portName="EchoServicePort")
public class EchoServicePortTypeImpl implements EchoServicePortType {

                public EchoServicePortTypeImpl() {
                }

                public String echo(String obj) {
                        String str;
                        ....
                        str = obj;
                        ....
                        
                        return str;

                }

}
/**  This is a sample EchoServicePortType.java service interface. */

import javax.jws.WebMethod;
import javax.jws.WebService;
import javax.xml.ws.*;


@WebService(name = "EchoServicePortType", targetNamespace = "http://com/ibm/was/wssample/echo/", 
wsdlLocation="WEB-INF/wsdl/Echo.wsdl")
public interface EchoServicePortType {


    /** ...the method process ...*/
        @WebMethod

}
以下示例说明了 Java 类的简单提供程序服务端点接口:
package jaxws.provider.source;

import javax.xml.ws.Provider;
import javax.xml.ws.WebServiceProvider;
import javax.xml.transform.Source;

@WebServiceProvider()
public class SourceProvider implements Provider<Source> {

    public Source echo(Source data) {
        return data;
    }
}

在提供程序实现示例中,在通用 <Source> 方法中指定了 javax.xml.transform.Source 类型。通用 <Source> 方法指定输入和输出类型都是 Source 对象。

下一步做什么

根据 JavaBeans 开发 JAX-WS 应用程序的 Java 工件。要了解更多信息,请参阅“为 JAX-WS 应用程序生成 Java 工件”的相关信息。


指示主题类型的图标 任务主题



时间戳记图标 最近一次更新时间: last_date
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=cord&product=was-nd-mp&topic=twbs_devjaxwsendpt
文件名:twbs_devjaxwsendpt.html