JAX-WS 注释
Java™ API for XML-Based Web Services (JAX-WS) 通过使用注释来指定与 Web Service 实现相关联的元数据以及简化 Web Service 的开发。注释描述如何将服务器端的服务实现作为 Web Service 进行访问或者客户机端的 Java 类如何访问 Web Service。
JAX-WS 编程标准支持将具有用于定义服务端点应用程序的元数据的 Java 类作为 Web Service 进行注释以及注释客户机可以如何访问 Web Service。JAX-WS 支持使用基于 Metadata Facility for the Java Programming Language(Java 规范请求 (JSR) 175)规范和“用于 Java 平台的 Web Service 元数据”(JSR 181) 规范的注释,还可以使用由 JAX-WS 2.0 和更高版本 (JSR 224) 规范定义的注释(包括 JAXB 注释)。通过使用 JSR 181 标准中的注释,您可以简单地注释服务实现类或服务接口,并且应用程序现在将作为 Web Service 进行启用。在 Java 源代码中使用注释可以简化 Web Service 的开发和部署,其实现方式是定义一些通常从部署描述符文件和 WSDL 文件中获取的附加信息,或者将元数据从 XML 和 WSDL 映射到源工件。
使用注释来配置绑定、处理程序链、端口类型的集合名称、服务以及其他 WSDL 参数。注释可以用在 Java 到 WSDL 和模式的映射中,并且在运行时可以用于控制 JAX-WS 运行时处理和响应 Web Service 调用的方式。
对于 JAX-WS Web Service,可以选择是否使用 webservices.xml 部署描述符,这是因为您可以使用注释来指定该部署描述符文件所包含的所有信息。可以使用部署描述符文件来扩充或覆盖现有 JAX-WS 注释。您在 webservices.xml 部署描述符中定义的任何信息将覆盖由注释指定的任何相应信息。
从 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 注释。
- 您可以在 WAR 文件或 EJB 模块的 META-INF/MANIFEST.MF 中,将 UseWSFEP61ScanPolicy 属性设置为 true。例如:
在该模块的 META-INF/MANIFEST.MF 文件中将此属性设置为 true 时,不论该模块的 Java EE 版本为何,都会在该模块中扫描 JAX-WS 注释。缺省值为 false,并且当此缺省值生效时,只有版本为 Java EE 5 或更高版本的模块才支持 JAX-WS 注释。Manifest-Version: 1.0 UseWSFEP61ScanPolicy: true
- 可以使用管理控制台来设置 com.ibm.websphere.webservices.UseWSFEP61ScanPolicy 定制 Java 虚拟机 (JVM) 属性。请参阅 JVM 定制属性文档,以获取要使用的正确导航路径。要请求在所有模块中扫描注释(不论模块的 Java EE 版本为何),请将定制属性 com.ibm.websphere.webservices.UseWSFEP61ScanPolicy 设为 true。您必须在每个需要更改缺省行为的服务器上更改此设置。
![[z/OS]](../images/ngzos.gif)


- 诸如 Java 类、枚举或接口等类型
- 方法
- 代表 Java 类中局部实例变量的字段
- Java 方法中的参数
注释类 | 注释 | 属性 |
---|---|---|
javax.jws.WebService | @WebService 注释用于将 Java 类标记为实现 Web Service 或者将服务端点接口 (SEI) 标记为实现 Web Service 接口。 要点:
|
|
javax.jws.WebMethod | @WebMethod 注释用于表示作为一项 Web Service 操作的方法。 将此注释应用于客户机或服务器服务端点接口 (SEI) 上的方法,或者应用于服务器端点实现类。 |
|
javax.jws.Oneway | @Oneway 注释用于将某一方法表示为只有输入消息而没有输出消息的 Web Service 单向操作。 将此注释应用于客户机或服务器服务端点接口 (SEI) 上的方法,或者应用于服务器端点实现类。 |
|
javax.jws.WebParam | @WebParam 注释用于定制从单个参数至 Web Service 消息部分和 XML 元素的映射。 将此注释应用于客户机或服务器服务端点接口 (SEI) 上的方法,或者应用于服务器端点实现类。 |
|
javax.jws.WebResult | @WebResult 注释用于定制从返回值至 WSDL 部件或 XML 元素的映射。 将此注释应用于客户机或服务器服务端点接口 (SEI) 上的方法,或者应用于服务器端点实现类。 |
|
javax.jws.HandlerChain | @HandlerChain 注释用于将 Web Service 与外部定义的处理程序链相关联。 只能通过对服务端点接口 (SEI) 或服务器端点实现类使用 @HandlerChain 注释来配置服务器端的处理程序。 但是可以使用多种方法来配置客户机端的处理程序。可以通过对生成的服务类或者 SEI 使用 @HandlerChain 注释来配置客户机端的处理程序。另外,可以按编程方式在服务上注册您自己的 HandlerResolver 接口实现,或者按编程方式在绑定对象上设置处理程序链。 |
|
javax.jws.SOAPBinding | @SOAPBinding 注释用于指定 Web Service 与 SOAP 消息协议之间的映射。 将此注释应用于客户机或服务器服务端点接口 (SEI) 上的类型或方法,或者应用于服务器端点实现类。 方法级别的注释仅限于它可以指定的对象,仅当 style 属性为 DOCUMENT 时才使用该注释。如果未指定方法级别的注释,那么将使用类型的 @SOAPBinding 行为。 |
|
注释类 | 注释 | 属性 |
---|---|---|
javax.xml.ws.Action | @Action 注释用于指定与 Web Service 操作关联的 WS-Addressing 操作。 如果您将此注释与特定方法配合使用,并生成相应的 WSDL 文档,那么会将 WS-Addressing 操作扩展属性添加到与该方法对应的 WSDL 操作的 input 和 output 元素。 要将此属性添加到 WSDL 操作,您还必须在服务器端点实现类上指定 @Addressing 注释。如果不想使用 @Addressing 注释,那么可以提供您自己的已定义 Action 属性的 WSDL 文档。 |
|
javax.xml.ws.BindingType | @BindingType 注释指定在发布此类型的端点时要使用的绑定。 将此注释应用于服务器端点实现类。 要点: 可以通过指定 javax.xml.ws.soap.SOAPBinding.SOAP11HTTP_MTOM_BINDING 或 javax.xml.ws.soap.SOAPBinding.SOAP12HTTP_MTOM_BINDING 作为该注释的值来对 JavaBeans 端点实现类使用 @BindingType 注释以启用 MTOM。
|
|
javax.xml.ws.FaultAction | @FaultAction 注释指定已添加到故障响应中的 WS-Addressing 操作。 此注释必须包含在 @Action 注释中。 如果您将此注释与特定方法配合使用,那么会将 WS-Addressing FaultAction 扩展属性添加到与该方法对应的 WSDL 操作的 fault 元素。 要将此属性添加到 WSDL 操作,您还必须在服务器端点实现类上指定 @Addressing 注释。如果不想使用 @Addressing 注释,那么可以提供您自己的已定义 Action 属性的 WSDL 文档。 |
|
javax.xml.ws.RequestWrapper | @RequestWrapper 注释提供 JAXB 生成的请求包装器 Bean、元素名称和名称空间,用于对在运行时使用的请求包装器 Bean 进行序列化和反序列化。 从 Java 对象开始时,此元素用来解决 document literal 方式下的重载冲突。在这种情况下,只有 className 属性是必需的。 将此注释应用于客户机或服务器服务端点接口 (SEI) 上的方法,或者应用于服务器端点实现类。 |
|
javax.xml.ws.ResponseWrapper | @ResponseWrapper 注释提供 JAXB 生成的响应包装器 Bean、元素名称和名称空间,用于对在运行时使用的响应包装器 Bean 进行序列化和反序列化。 从 Java 对象开始时,此元素用来解决 document literal 方式下的重载冲突。在这种情况下,只有 className 属性是必需的。 将此注释应用于客户机或服务器服务端点接口 (SEI) 上的方法,或者应用于服务器端点实现类。 |
|
javax.xml.ws.RespectBinding | @RespectBinding 注释指定 JAX-WS 实现是否必须将 wsdl:binding 的内容用于端点。 如果指定此注释,那么会执行检查以确保支持 enabled 属性设置为 true 的所有必需 WSDL 可扩展性元素。 将此注释应用于服务器端点实现类上的方法。 |
|
javax.xml.ws.ServiceMode | @ServiceMode 注释指定服务提供程序是需要对整个协议消息具有访问权还是只需对消息有效内容具有访问权。 要点: 仅支持在使用 @WebServiceProvider 注释进行注释的类上使用 @ServiceMode 注释。
|
|
javax.xml.ws.soap.Addressing | @Addressing 注释指定此服务需要启用 WS-Addressing 支持。 将此注释应用于服务器端点实现类上的方法。 |
|
javax.xml.ws.soap.MTOM | @MTOM 注释指定是否使用 MTOM 来发送 SOAP 消息体中的二进制内容。 将此注释应用于服务端点实现类。 |
|
javax.xml.ws.WebFault | @WebFault 注释将 WSDL 故障映射到 Java 异常。对从 WSDL 故障消息引用的全局元素生成的 JAXB 类型进行序列化期间,该注释用来捕获故障的名称。它还可以用来定制从特定于服务的异常到 WSDL 故障的映射。 此注释只能应用于客户机或服务器上的故障实现类。 |
|
javax.xml.ws.WebServiceProvider | @WebServiceProvider 注释表示一个类满足 JAX-WS 提供程序实现类的要求。 要点:
|
|
javax.xml.ws.WebServiceRef | @WebServiceRef 注释用于定义对客户机所调用的 Web Service 的引用。 注:
|
|
javax.xml.ws.WebServiceRefs | @WebServiceRefs 注释会将多个 @WebServiceRef 注释与一个特定类相关联。 注: 仅在特定的类类型中支持 @WebServiceRef 注释。示例为 JAX-WS 端点实现类、JAX-WS 处理程序类、Enterprise JavaBeans 类以及 Servlet 类。支持此注释的类类型与支持 @Resource 注释的类类型相同。请参阅 Java Platform,
Enterprise Edition (Java EE) 5 规范,以获取支持的类类型的完整列表。
|
|
注释类 | 注释 | 属性 |
---|---|---|
javax.annotation.Resource | @Resource 注释标记应用程序所需要的 WebServiceContext 资源。 注:
将此注释应用于 JavaBeans 端点或 Provider 端点的服务器端点实现类上的 WebServiceContext 类型字段,会导致容器将 WebServiceContext 的实例注入所指定的字段。 使用此注释取代 @WebServiceRef 注释时,会应用针对 @WebServiceRef 注释描述的规则。 |
|
javax.annotation.Resources | @Resources 注释会将多个 @Resource 注释与特定的类相关联,并充当多个资源声明的容器。 |
|
javax.annotation.PostConstruct | @PostConstruct 注释标记需要在对类执行依赖性注入之后才运行的方法。 将此注释应用于 JAX-WS 应用程序处理程序或服务器端点实现类。 |
|
javax.annotation.PreDestroy | @PreDestroy 注释标记在容器移除实例时必须运行的方法。 将此注释应用于 JAX-WS 应用程序处理程序或服务器端点实现类。 |
|
注释类 | 注释 | 属性 |
---|---|---|
com.ibm.websphere. wsaddressing. jaxws21. SubmissionAddressing | @SubmissionAddressing 注释指定此服务需要对 2004/08 WS-Addressing 规范启用 WS-Addressing 支持。 此注释是 JAX-WS 2.1 规范的 IBM 实现的一部分。 将此注释应用于服务器端点实现类上的方法。 |
|