24.3.3. 可选注解

概述

使用 Annotations 定义 Binding Properties

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

@SOAPBinding 注解

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

您可以在 SEI 和任何 SEI 的方法上放置 @SOAPBinding 注释。在方法上使用时，优先使用方法的 @SOAPBinding 注解设置。

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

表 24.2. @SOAPBinding Properties
属性	值	描述
`style`	样式.DOCUMENT （默认） Style.RPC	指定 SOAP 消息的样式。如果指定了 RPC 样式，则 SOAP 正文中的每个消息部分都是参数或返回值，并出现在 `soap:body` 元素中的 wrapper 元素中。wrapper 元素中的消息部分与操作参数对应，且必须与操作中的参数相同的顺序出现。如果指定了 DOCUMENT 样式，SOAP 正文的内容必须是有效的 XML 文档，但其表单不是严格限制的。
`use`	使用.LITERAL （默认）使用.ENCODED^[a]	指定 SOAP 消息的数据如何进行流处理。
`parameterStyle` ^[b]	ParameterStyle.BARE ParameterStyle.WRAPPED （默认）	指定在 WSDL 合同中与消息部分对应的方法参数如何放入 SOAP 消息正文。如果指定了 BARE，则每个参数都作为消息 root 的子元素放入消息正文中。如果指定了 WRAPPED，则所有输入参数都嵌套到请求消息上的单个元素中，并且所有输出参数都嵌套在响应消息中的单个元素中。
^[a] 目前不支持使用.ENCODED。 ^[b] 如果将 `风格` 设置为 RPC，则必须使用 WRAPPED 参数风格。

文档裸机参数

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

您可以使用 @SOAPBinding 注释将其风格设置为 Style.DOCUMENT，并将其 parameterStyle 属性设置为 ParameterStyle.BARE，将其 parameterStyle 属性设为 ParameterStyle.BARE。

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

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

注意

任何使用 @WebParam 注释或 @WebResult 注释放置到 SOAP 标头的参数都不会计算出允许的参数数量。

文档嵌套参数

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

要指定您要使用嵌套的 document\literal 样式的 @SOAPBinding 注解，将其 样式 属性设置为 Style.DOCUMENT，且 参数Style 属性设为 ParameterStyle.WRAPPED。

您可以使用 “@RequestWrapper 注释”一节注解和 “@ResponseWrapper 注释”一节注解来控制如何生成 wrappers。

示例

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

例 24.5. 使用 SOAP 绑定注解指定文档 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 注释提供在 wsdl:operation 元素中通常会表示的信息，描述方法要关联的操作。

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

表 24.3. @WebMethod Properties
属性	描述
`operationName`	指定关联的 `wsdl:operation` 元素 `的名称`。默认值为方法的名称。
`action`	指定为方法生成的 `soap:operation` 元素的 `soapAction` 属性的值。默认值为空字符串。
`exclude`	指定方法是否应该排除在服务接口中。默认值为 false。

@RequestWrapper 注释

@RequestWrapper 注释由 javax.xml.ws.RequestWrapper 接口定义。它被放置在 SEI 中的方法上。@RequestWrapper 注释指定用于启动消息交换方法参数的 wrapper bean 的 Java 类。它还指定在 marshalling 和 unmarshalling 和 unmarshalling 时使用的元素名称和命名空间。

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

表 24.4. @RequestWrapper Properties
属性	描述
`localName`	指定请求消息 XML 表示中的 wrapper 元素的本地名称。默认值为方法的名称，或者 “@WebMethod 注释”一节注解的 `operationName` 属性的值。
`targetNamespace`	指定定义 XML 打包程序元素的命名空间。默认值为 SEI 的目标命名空间。
`className`	指定实现 wrapper 元素的 Java 类的完整名称。

注意

只有 className 属性才是必需的。

重要

如果方法还标有 @SOAPBinding 注释，并且其 parameterStyle 属性设为 ParameterStyle.BARE，则会忽略此注解。

@ResponseWrapper 注释

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

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

表 24.5. @ResponseWrapper Properties
属性	描述
`localName`	指定响应消息 XML 表示中的 wrapper 元素的本地名称。默认值为附加 Response 的方法的名称，或者附加了 Response 的 “@WebMethod 注释”一节注解的 `operationName` 属性的值。
`targetNamespace`	指定定义 XML 打包程序元素的命名空间。默认值为 SEI 的目标命名空间。
`className`	指定实现 wrapper 元素的 Java 类的完整名称。

注意

只有 className 属性才是必需的。

重要

如果方法还标上 @SOAPBinding 注释，其参数 Style 属性被设置为 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);
}

概述

使用注释定义参数属性

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

@WebParam 注释

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

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

表 24.7. @WebParam Properties
属性	值	描述
`name`		指定参数的名称，因为它出现在生成的 WSDL 文档中。对于 RPC 绑定，这是代表参数的 `wsdl:part` 的名称。对于文档绑定，这是代表参数的 XML 元素的本地名称。根据 JAX-WS 规格，默认值为 `arg N` ，其中 N 替换为零的参数索引（例如 arg0、arg1 等）。
`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
  );
}

概述