使用注释来开发 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 注释信息。
过程
结果
您已定义了表示 Web Service 应用程序的服务端点实现。请参阅 JAX-WS 注释文档以了解有关受支持的 JAX-WS 注释的更多信息。
样本 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
}
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 工件”的相关信息。