24.3.3. 可选注解

摘要

虽然 @WebService 注释足以启用 Java 接口或 Java 类，但它不完全描述服务将如何作为服务提供商公开。JAX-WS 编程模型使用许多可选注释来添加有关服务的详细信息，如其使用的绑定到 Java 代码。您可以将这些注解添加到服务的 SEI 中。

您在 SEI 中提供的更多详情是开发人员实施可使用它所定义的功能的应用程序。它还使 WSDL 文档更具体由工具生成。

概述

使用 Annotations 定义绑定属性

如果您正在为您的服务使用 SOAP 绑定，您可以使用 JAX-WS 注解来指定多个绑定属性。这些属性直接与您在服务的 WSDL 合同中指定的属性对应。某些设置（如参数风格）可以限制如何实施方法。这些设置也可以影响在注解方法参数时使用哪些注解。

@SOAPBinding 注解

@SOAPBinding 注解由 javax.jws.SOAp.SOAPBinding 接口定义。它提供有关服务在部署时使用的 SOAP 绑定的详细信息。如果没有指定 @SOAPBinding 注解，则会使用嵌套的 doc/literal SOAP 绑定来发布服务。

您可以将 @SOAPBinding 注释放在 SEI 上，以及任何 SEI 的方法。在方法中使用时，将方法的 @SOAPBinding 注释设置具有优先权。

表 24.2 “@SOAPBinding 属性” 显示 @SOAPBinding 注释的属性。

表 24.2. @SOAPBinding 属性

属性值描述

样式

样式.DOCUMENT（默认）

样式.RPC

指定 SOAP 消息的样式。如果指定了 RPC 样式，则 SOAP 正文中的每个消息部分都是参数或返回值，并出现在 soap:body 元素中的 wrapper 元素中。wrapper 元素中的消息部分对应于操作参数，且必须与操作中的参数的顺序相同。如果指定了 DOCUMENT 风格，则 SOAP 正文的内容必须是有效的 XML 文档，但其表单并没有严格限制。

使用

使用.LITERAL（默认）

use.ENCODED[a]

指定传输 SOAP 消息的数据。

parameterStyle [b]

ParameterStyle.BARE

ParameterStyle.WRAPPED（默认）

指定与 WSDL 合同中的消息部分对应的方法参数如何放入 SOAP 消息正文。如果指定了 BARE，则会将每个参数放在邮件正文中，作为消息根的子元素。如果指定了 WRAPPED，则所有输入参数都嵌套到请求消息上的单个元素中，所有输出参数都会嵌套到响应消息中的单个元素中。

[a] 目前不支持 use.ENCODED。
[b] 如果将 风格 设置为 RPC，则必须使用 WRAPPED 参数样式。

文档裸机风格参数

文档裸机风格是 Java 代码与服务生成的 XML 代码之间最直接映射。使用这种风格时，从操作参数列表中定义的输入和输出参数直接生成 schema 类型。

您需要使用 @SOAPBinding 注释将其样式设置为 Style.DOCUMENT，其 parameterStyle 属性设为 ParameterStyle.BARE 来指定您要使用裸机文档\literal 样式的样式。

要确保在使用裸机参数时操作不会违反使用文档风格的限制，您的操作必须遵循以下条件：

  • 操作不能有多个输入或输入/输出参数。
  • 如果操作具有非 void 的返回类型，它不能具有任何输出或输入/输出参数。
  • 如果操作的返回类型为 void，则不能有多个输出或输入/输出参数。
注意

使用 @WebParam 注释或 @WebResult 注释放入 SOAP 标头中的任何参数都不会根据允许的参数数目进行计数。

文档嵌套参数

文档嵌套风格允许更多 RPC，如 Java 代码和服务的 XML 表示之间的映射。使用这种风格时，方法的 parameter 列表中的参数会被绑定嵌套到单个元素中。这样做的缺点是，它在 Java 实施之间引入了一个额外的间接层，以及如何将消息放置在线路上。

要指定您要使用嵌套文档\literal 样式的 @SOAPBinding 注释，其 样式 属性设置为 Style.DOCUMENT，并将其 parameterStyle 属性设置为 ParameterStyle.WRAPPED。

您可以对使用 “@RequestWrapper 注释”一节 注解和 “@ResponseWrapper 注释”一节 注解生成的打包程序有一些控制。

示例

例 24.5 “使用 SOAP Binding 注解指定文档 Bare SOAP Binding” 显示使用文档裸机 SOAP 消息的 SEI。

例 24.5. 使用 SOAP Binding 注解指定文档 Bare SOAP Binding

package org.eric.demo;

import javax.jws.*;
import javax.jws.soap.*;
import javax.jws.soap.SOAPBinding.*;

@WebService(name="quoteReporter")
@SOAPBinding(parameterStyle=ParameterStyle.BARE)
public interface quoteReporter
{
  ...
}

概述

使用注释定义操作属性

当运行时将 Java 方法定义映射到 XML 操作定义时，它提供详情，例如：

  • 在 XML 中交换的信息类似如下
  • 如果消息可以优化为一条方法消息
  • 定义消息的命名空间

@WebMethod 注释

@WebMethod 注释由 javax.jws.WebMethod 接口定义。它放置在 SEI 中的方法中。@WebMethod 注释提供了通常在 ws:operation 元素中 代表的信息，用于描述与该方法关联的操作。

表 24.3 “@WebMethod 属性” 描述 @WebMethod 注释的属性。

表 24.3. @WebMethod 属性

属性描述

operationName

指定关联的 wsdl:operation 元素 的名称。默认值为方法的名称。

action

指定方法生成的 soap:operation 元素的 soapAction 属性的值。默认值为空字符串。

exclude

指定是否应该将方法排除在服务接口中。默认值为 false。

@RequestWrapper 注释

@RequestWrapper 注释由 javax.xml.ws.RequestWrapper 接口定义。它放置在 SEI 中的方法中。@RequestWrapper 注释指定 Java 类，用于实施请求消息交换方法参数的 wrapperan。它还指定了在处理请求消息时运行时使用的元素名称和命名空间。

表 24.4 “@RequestWrapper Properties” 描述 @RequestWrapper 注释的属性。

表 24.4. @RequestWrapper Properties

属性描述

localName

指定请求消息 XML representation 中的 wrapper 元素的本地名称。默认值可以是方法的名称，也可以是 “@WebMethod 注释”一节 注解的 operationName 属性的值。

targetNamespace

指定定义 XML wrapper 元素的命名空间。默认值为 SEI 的目标命名空间。

className

指定实施 wrapper 元素的 Java 类的完整名称。

注意

只有 className 属性才是必需的。

重要

如果方法也带有 @SOAPBinding 注释，其 parameterStyle 属性设为 ParameterStyle.BARE，则忽略此注解。

@ResponseWrapper 注释

@ResponseWrapper 注释由 javax.xml.ws.ResponseWrapper 接口定义。它放置在 SEI 中的方法中。@ResponseWrapper 指定在消息交换中为方法参数实施打包程序的 Java 类。它还指定在处理响应消息和解包时运行时使用的元素名称和命名空间。

表 24.5 “@ResponseWrapper Properties” 描述 @ResponseWrapper 注释的属性。

表 24.5. @ResponseWrapper Properties

属性描述

localName

指定响应消息 XML representation 中的 wrapper 元素的本地名称。默认值是附加 Response 的方法的名称，或者 “@WebMethod 注释”一节 注解的 operationName 属性的值附加了 Response。

targetNamespace

指定定义 XML 打包程序元素的命名空间。默认值为 SEI 的目标命名空间。

className

指定实施 wrapper 元素的 Java 类的完整名称。

注意

只有 className 属性才是必需的。

重要

如果方法也带有 @SOAPBinding 注释，其 parameterStyle 属性设为 ParameterStyle.BARE，则忽略此注解。

@WebFault 注释

@WebFault 注释由 javax.xml.ws.WebFault 接口定义。它会被置于您的 SEI 引发的异常。@WebFault 注释用于将 Java 异常映射到 wsdl:fault 元素。这些信息用于将例外置于可由服务及其消费者处理的表示中。

表 24.6 “@WebFault Properties” 描述 @WebFault 注释的属性。

表 24.6. @WebFault Properties

属性描述

name

指定 fault 元素的本地名称。

targetNamespace

指定定义 fault 元素的命名空间。默认值为 SEI 的目标命名空间。

faultName

指定实施异常的 Java 类的全名。

重要

name 属性是必需的。

@Oneway 注解

@Oneway 注释由 javax.jws.Oneway 接口定义。它放置在 SEI 中不需要来自该服务的响应的方法。@Oneway 注释告知运行时，它可以通过不等待响应而优化方法执行，而且不会保留任何资源来处理响应。

此注解只能在满足以下条件的方法中使用：

  • 它们返回 void
  • 它们没有实现 Holder 接口的参数
  • 它们不会抛出任何例外，可以传回给消费者

示例

例 24.6 “带有注解的方法 SEI” 显示标有其方法的 SEI。

例 24.6. 带有注解的方法 SEI

package com.fusesource.demo;

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

@WebService(name="quoteReporter")
public interface quoteReporter
{
  @WebMethod(operationName="getStockQuote")
  @RequestWrapper(targetNamespace="http://demo.redhat.com/types",
                  className="java.lang.String")
  @ResponseWrapper(targetNamespace="http://demo.redhat.com/types",
                   className="org.eric.demo.Quote")
  public Quote getQuote(String ticker);
}

概述

使用 Annotations 定义参数属性

SEI 中的方法参数对应于 wsdl:message 元素及其 wsdl:part 元素。JAX-WS 提供注解，供您描述为方法参数生成的 wsdl:part 元素。

@WebParam 注释

@WebParam 注释由 javax.jws.WebParam 接口定义。它放置在 SEI 中定义的方法的参数中。如果参数将被放入 SOAP 标头，则 @WebParam 注释可以指定参数方向，以及生成的 wsdl:part 的其他属性。

表 24.7 “@WebParam 属性” 描述 @WebParam 注释的属性。

表 24.7. @WebParam 属性

属性值描述

name

 

指定参数的名称，因为它出现在生成的 WSDL 文档中。对于 RPC 绑定，这是代表 参数的 wsdl:part 的名称。对于文档绑定，这是代表 参数的 XML 元素的本地名称。根据 JAX-WS 规范，默认值为 arg N ，其中 N 替换为基于零的参数索引（如 arg0、arg0 等）。

targetNamespace

 

指定参数的命名空间。它只适用于参数映射到 XML 元素的文档绑定。默认值是使用服务的命名空间。

模式

mode.IN（默认）[a]

mode.OUT

Mode.INOUT

指定参数方向。

header

false（默认）

true

指定参数是否作为 SOAP 标头的一部分传递。

partName

 

指定 参数的 wsdl:part 元素的 name 属性的值。此属性用于文档风格的 SOAP 绑定。

[a] 任何实现 Holder 接口的参数默认映射到 Mode.INOUT。

@WebResult 注解

@WebResult 注释由 javax.jws.WebResult 接口定义。它放置在 SEI 中定义的方法中。@WebResult 注释允许您指定为方法返回值生成的 wsdl:part 的属性。

表 24.8 “@WebResult Properties” 描述 @WebResult 注释的属性。

表 24.8. @WebResult Properties

属性描述

name

指定返回值的名称，因为它出现在生成的 WSDL 文档中。对于 RPC 绑定，这是代表返回值的 wsdl:part 的名称。对于文档绑定，这是代表返回值的 XML 元素的本地名称。默认值为 return。

targetNamespace

指定返回值的命名空间。它仅用于记录绑定，其中返回值映射到 XML 元素。默认值是使用服务的命名空间。

header

指定返回值是否作为 SOAP 标头的一部分传递。

partName

指定返回值的 wsdl:part 元素的 name 属性的值。此属性用于文档风格的 SOAP 绑定。

示例

例 24.7 “完全注解的 SEI” 显示已完全注解的 SEI。

例 24.7. 完全注解的 SEI

package com.fusesource.demo;

import javax.jws.*;
import javax.xml.ws.*;
import javax.jws.soap.*;
import javax.jws.soap.SOAPBinding.*;
import javax.jws.WebParam.*;

@WebService(targetNamespace="http://demo.redhat.com",
            name="quoteReporter")
@SOAPBinding(style=Style.RPC, use=Use.LITERAL)
public interface quoteReporter
{
  @WebMethod(operationName="getStockQuote")
  @RequestWrapper(targetNamespace="http://demo.redhat.com/types",
                  className="java.lang.String")
  @ResponseWrapper(targetNamespace="http://demo.redhat.com/types",
                   className="org.eric.demo.Quote")
  @WebResult(targetNamespace="http://demo.redhat.com/types",
             name="updatedQuote")
  public Quote getQuote(
                        @WebParam(targetNamespace="http://demo.redhat.com/types",
                                  name="stockTicker",
                                  mode=Mode.IN)
                        String ticker
  );
}