24.3. 为代码添加注解

24.3.1. JAX-WS Annotations 概述

JAX-WS 注释指定用于将 SEI 映射到完全指定的服务定义的元数据。注解中提供的信息包括:

  • 服务的目标命名空间。
  • 用于保存请求消息的类名称
  • 用于保存响应消息的类名称
  • 如果某个操作是单向操作
  • 服务使用的绑定风格
  • 用于任何自定义例外的类名称
  • 服务使用的命名空间
注意

大多数注解都有可识别的默认值,不需要为其提供值。但是,您在注解中提供的更多信息,会指定更好的服务定义。精心指定的服务定义会增加分布式应用程序的所有部分将一起工作的可能性。

24.3.2. 必需的注解

概述

要从 Java 代码创建服务,您只需要向代码添加一个注解。您必须在 SEI 和实施类中添加 @WebService 注释。

@WebService 注解

@WebService 注释由 javax.jws.WebService 接口定义,它被放在接口或要用作服务的类中。@webService 具有中描述的属性 表 24.1 “@webService 属性”

表 24.1. @webService 属性

属性描述

name

指定服务接口的名称。此属性映射到 wsdl:portType 元素的 name 属性,该元素在 WSDL 合同中定义服务的接口。默认为在实施类的名称中添加 PortType[a]

targetNamespace

指定定义该服务的目标命名空间。如果没有指定此属性,则目标命名空间派生自软件包名称。

serviceName

指定已发布的服务的名称。此属性映射到定义所发布服务的 wsdl:service 元素的 name 属性。默认值是使用服务的实施类的名称。

wsdlLocation

指定存储服务的 WSDL 合同的 URL。这必须使用一个相对 URL 指定。默认为部署该服务的 URL。

endpointInterface

指定实施类实施的 SEI 的完整名称。仅在服务实施类中使用 属性时指定此属性。

portName

指定发布该服务的端点的名称。此属性映射到 wsdl:port 元素的 name 属性,用于指定公布的服务的端点详情。默认为在服务的实现类中添加 Port

[a] 从 SEI 生成 WSDL 时,会使用接口名称来代替实施类名称。
注意

不需要为任何 @WebService 注释的属性提供值。但是,建议您提供尽可能多的信息。

为 SEI 标注

SEI 要求您添加 @WebService 注释。由于 SEI 是定义服务的合同,所以您应该在 @WebService 注释的属性中指定服务尽可能多的详细信息。

例 24.3 “带有 @WebService 注解的接口” 显示 例 24.1 “simple SEI” 中带有 @WebService 注释的接口。

例 24.3. 带有 @WebService 注解的接口

package com.fusesource.demo;

import javax.jws.*;

@WebService(name="quoteUpdater",
            targetNamespace="http://demos.redhat.com",
	        serviceName="updateQuoteService",
            wsdlLocation="http://demos.redhat.com/quoteExampleService?wsdl",
            portName="updateQuotePort")
public interface quoteReporter
{
  public Quote getQuote(String ticker);
}

例 24.3 “带有 @WebService 注解的接口” 中的 @WebService 注释执行以下操作:

指定定义服务接口的 wsdl:portType 元素的 name 属性的值是 quoteUpdater

指定服务的目标命名空间是 http://demos.redhat.com

指定定义所发布服务的 wsdl:service 元素的值为 updateQuoteService

指定该服务将在 http://demos.redhat.com/quoteExampleService?wsdl 发布其 WSDL 合同。

指定定义公开该服务的 端点的 name 属性的值是 updateQuotePort

为服务实施添加注解

除了使用 @WebService 注释标注 SEI 外,还必须为服务实施类添加 @WebService 注释。当在服务实施类中添加注解时,您只需要指定 endpointInterface 属性。如 例 24.4 “注解的服务实现类” 所示,属性必须设置为 SEI 的全名。

例 24.4. 注解的服务实现类

package org.eric.demo;

import javax.jws.*;

@WebService(endpointInterface="com.fusesource.demo.quoteReporter")
public class stockQuoteReporter implements quoteReporter
{
public Quote getQuote(String ticker)
  {
  ...
  }
}

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
  );
}

24.3.4. Apache CXF Annotations

24.3.4.1. WSDL 文档

@WSDL 文档注释

@WSDL 文档 注释由 org.apache.cxf.annotations.WSDL 文档接口定义。它可以放在 SEI 或 SEI 方法上。

此注解可让您添加文档,然后在 SEI 转换为 WSDL 后在 wsdl:documentation 元素内显示。默认情况下,文档元素显示在端口类型中,但您可以指定放置属性,使文档显示在 WSDL 文件的其他位置。第 24.3.4.2 节 “@WSDL 文档属性” 显示 @WSDL 文档注释支持的属性

24.3.4.2. @WSDL 文档属性

属性描述

value

(必需) 包含文档文本的字符串。

placement

(可选) 指定在 WSDL 文件中显示此文档的位置。有关可能的放置值列表,请参阅 “在 WSDL 合同中放置”一节

faultClass

(可选) 如果放置设置为 FAULT_MESSAGEPORT_TYPE_OPERATION_FAULTBINDING_OPERATION_FAULT,则必须将此属性设置为代表该故障的 Java 类。

@WSDLDocumentationCollection 注解

@WSDLDocumentationCollection 注释由 org.apache.cxf.annotations.WSDLDocumentationCollection 接口定义。它可以放在 SEI 或 SEI 方法上。

此注解用于在单一位置或不同的位置插入多个文档元素。

在 WSDL 合同中放置

要指定在 WSDL 合同中应当出现文档的位置,您可以指定 放置 属性,类型为 WSDLDocumentation.Placement。放置可以具有以下值之一:

  • WSDLDocumentation.Placement.BINDING
  • WSDLDocumentation.Placement.BINDING_OPERATION
  • WSDLDocumentation.Placement.BINDING_OPERATION_FAULT
  • WSDLDocumentation.Placement.BINDING_OPERATION_INPUT
  • WSDLDocumentation.Placement.BINDING_OPERATION_OUTPUT
  • WSDLDocumentation.Placement.DEFAULT
  • WSDLDocumentation.Placement.FAULT_MESSAGE
  • WSDLDocumentation.Placement.INPUT_MESSAGE
  • WSDLDocumentation.Placement.OUTPUT_MESSAGE
  • WSDLDocumentation.Placement.PORT_TYPE
  • WSDLDocumentation.Placement.PORT_TYPE_OPERATION
  • WSDLDocumentation.Placement.PORT_TYPE_OPERATION_FAULT
  • WSDLDocumentation.Placement.PORT_TYPE_OPERATION_INPUT
  • WSDLDocumentation.Placement.PORT_TYPE_OPERATION_OUTPUT
  • WSDLDocumentation.Placement.SERVICE
  • WSDLDocumentation.Placement.SERVICE_PORT
  • WSDLDocumentation.Placement.TOP
@WSDL 文档示例

第 24.3.4.3 节 “使用 @WSDL 文档” 展示如何将 @WSDL 文档 注释添加到 SEI 和其方法之一。

24.3.4.3. 使用 @WSDL 文档

@WebService
@WSDLDocumentation("A very simple example of an SEI")
public interface HelloWorld {
    @WSDLDocumentation("A traditional form of greeting")
    String sayHi(@WebParam(name = "text") String text);
}

第 24.3.4.4 节 “使用文档生成的 WSDL” 中显示的 WSDL(在 第 24.3.4.3 节 “使用 @WSDL 文档” 中)生成时,文档 元素的默认位置分别是 PORT_TYPEPORT_TYPE_OPERATION

24.3.4.4. 使用文档生成的 WSDL

<wsdl:definitions ... >
  ...
  <wsdl:portType name="HelloWorld">
    <wsdl:documentation>A very simple example of an SEI</wsdl:documentation>
    <wsdl:operation name="sayHi">
      <wsdl:documentation>A traditional form of greeting</wsdl:documentation>
      <wsdl:input name="sayHi" message="tns:sayHi">
    </wsdl:input>
      <wsdl:output name="sayHiResponse" message="tns:sayHiResponse">
    </wsdl:output>
    </wsdl:operation>
  </wsdl:portType>
  ...
</wsdl:definitions>
@WSDL 文档Collection 的示例

第 24.3.4.5 节 “使用 @WSDL 文档Collection” 展示如何将 @WSDLDocumentationCollection 注释添加到 SEI。

24.3.4.5. 使用 @WSDL 文档Collection

@WebService
@WSDLDocumentationCollection(
    {
        @WSDLDocumentation("A very simple example of an SEI"),
        @WSDLDocumentation(value = "My top level documentation",
                           placement = WSDLDocumentation.Placement.TOP),
        @WSDLDocumentation(value = "Binding documentation",
                           placement = WSDLDocumentation.Placement.BINDING)
    }
)
public interface HelloWorld {
    @WSDLDocumentation("A traditional form of Geeky greeting")
    String sayHi(@WebParam(name = "text") String text);
}

24.3.4.6. 消息的 schema 验证

@SchemaValidation 注释

@SchemaValidation 注释由 org.apache.cxf.annotations.SchemaValidation 接口定义。它可以放在 SEI 和独立 SEI 方法上。

此注解打开发送到此端点的 XML 消息的 schema 验证。当您怀疑出现传入 XML 消息格式的问题时,这可用于测试目的。默认情况下禁用验证,因为它对性能有显著影响。

模式验证类型

架构验证 behaviour 由 type 参数控制,其值是 org.apache.cxf.annotations.SchemaValidation.SchemaValidationType 类型的枚举。第 24.3.4.7 节 “架构验证类型值” 显示可用验证类型的列表。

24.3.4.7. 架构验证类型值

类型描述

IN

对客户端和服务器上的传入消息应用架构验证。

OUT

将架构验证应用到客户端和服务器上的传出消息。

两者

对客户端和服务器上的传入和传出消息应用架构验证。

NONE

禁用所有 schema 验证。

REQUEST(请求)

将模式验证应用到 Request 消息,从而导致验证应用到传出客户端消息和传入的服务器消息。

RESPONSE

将模式验证应用到响应消息,从而导致验证应用到传入客户端消息和传出服务器消息。

示例

以下示例演示了如何根据 MyService SEI 为端点启用消息的 schema 验证。请注意,注解如何作为一个整体应用到 SEI,以及 SEI 中的个别方法。

@WebService
@SchemaValidation(type = SchemaValidationType.BOTH)
public interface MyService {
    Foo validateBoth(Bar data);

    @SchemaValidation(type = SchemaValidationType.NONE)
    Foo validateNone(Bar data);

    @SchemaValidation(type = SchemaValidationType.IN)
    Foo validateIn(Bar data);

    @SchemaValidation(type = SchemaValidationType.OUT)
    Foo validateOut(Bar data);

    @SchemaValidation(type = SchemaValidationType.REQUEST)
    Foo validateRequest(Bar data);

    @SchemaValidation(type = SchemaValidationType.RESPONSE)
    Foo validateResponse(Bar data);
}

24.3.4.8. 指定数据绑定

@DataBinding 注解

@DataBinding 注解由 org.apache.cxf.annotations.DataBinding 接口定义。它放置在 SEI 上。

此注释用于将数据绑定与 SEI 关联,以替换默认的 JAXB 数据块。@DataBinding 注解的值必须是提供数据绑定 ClassName.class 的类。

支持的数据绑定

Apache CXF 目前支持以下数据绑定:

  • org.apache.cxf.jaxb.JAXBDataBinding

    (默认) 标准 JAXB 数据绑定。

  • org.apache.cxf.sdo.SDODataBinding

    Service Data Objects(SDO)数据绑定基于 Apache Tuscany SDO 实现。如果要在 Maven 构建上下文中使用此数据绑定,则需要在 cxf-rt-databinding-sdo 工件中添加依赖项。

  • org.apache.cxf.aegis.databinding.AegisDatabinding

    如果要在 Maven 构建上下文中使用此数据绑定,则需要在 cxf-rt-databinding-aegis 工件中添加依赖项。

  • org.apache.cxf.xmlbeans.XmlBeansDataBinding

    如果要在 Maven 构建上下文中使用此数据绑定,则需要在 cxf-rt-databinding-xmlbeans 工件中添加依赖项。

  • org.apache.cxf.databinding.source.SourceDataBinding

    这个数据绑定属于 Apache CXF 内核。

  • org.apache.cxf.databinding.stax.StaxDataBinding

    这个数据绑定属于 Apache CXF 内核。

示例

第 24.3.4.9 节 “设置数据绑定” 展示如何将 SDO 绑定与 HelloWorld SEI 关联

24.3.4.9. 设置数据绑定

@WebService
@DataBinding(org.apache.cxf.sdo.SDODataBinding.class)
public interface HelloWorld {
    String sayHi(@WebParam(name = "text") String text);
}

24.3.4.10. 压缩信息

@GZIP 注解

@GZIP 注释由 org.apache.cxf.annotations.GZIP 接口定义。它放置在 SEI 上。

启用 GZIP 压缩信息。GZIP 是一个协商的增强。也就是说,客户端的初始请求将不会被 gzip 压缩,但会添加 Accept 标头;如果服务器支持 GZIP 压缩,其响应将被 gzip 压缩,任何后续请求也会被压缩。

第 24.3.4.11 节 “@GZIP Properties” 显示 @GZIP 注释支持的可选属性。

24.3.4.11. @GZIP Properties

属性描述

threshold

超过此属性指定大小的消息 不会被 gzip 压缩。默认为 -1(无限制)。

@FastInfoset

@FastInfoset 注释由 org.apache.cxf.annotations.FastInfoset 接口定义。它放置在 SEI 上。

为该消息启用 FastInfoset 格式。fastinfoset 是 XML 的二进制编码格式,旨在优化消息大小和 XML 消息处理性能。如需了解更多详细信息,请参阅 Fast Infoset 中的以下 Sun 文章。

fastinfoset 是一个协商的增强。也就是说,来自客户端的初始请求不会采用 FastInfoset 格式,但会添加 Accept 标头。如果服务器支持 FastInfoset,响应将位于 FastInfoset 中,任何后续请求也会被添加。

第 24.3.4.12 节 “@fastinfoset Properties” 显示 @FastInfoset 注释支持的可选属性。

24.3.4.12. @fastinfoset Properties

属性描述

force

强制使用 FastInfoset 格式的布尔值属性,而不是协商。当为 true 时,强制使用 FastInfoset 格式,否则协商。默认为 false

@GZIP 示例

第 24.3.4.13 节 “启用 GZIP” 显示如何为 HelloWorld SEI 启用 GZIP 压缩。

24.3.4.13. 启用 GZIP

@WebService
@GZIP
public interface HelloWorld {
    String sayHi(@WebParam(name = "text") String text);
}
@FastInfoset 的考试

第 24.3.4.14 节 “启用 FastInfoset” 显示如何为 HelloWorld SEI 启用 FastInfoset 格式。

24.3.4.14. 启用 FastInfoset

@WebService
@FastInfoset
public interface HelloWorld {
    String sayHi(@WebParam(name = "text") String text);
}

24.3.4.15. 在端点上启用日志记录

@logging 注解

@Logging 注释由 org.apache.cxf.annotations.Logging 接口定义。它放置在 SEI 上。

此注解为与 SEI 关联的所有端点启用日志记录。第 24.3.4.16 节 “@logging 属性” 显示此注解中可以设置的可选属性。

24.3.4.16. @logging 属性

属性描述

limit

指定在日志中截断信息的大小限制。默认为 64K。

inLocation

指定记录传入信息的位置。可以是 < stderr>、& lt;stdout& gt;、<logger > 或文件名。默认为 &lt ;logger>

outLocation

指定记录传出消息的位置。可以是 < stderr>、& lt;stdout& gt;、<logger > 或文件名。默认为 &lt ;logger>

示例

第 24.3.4.17 节 “使用注解进行日志配置” 演示了如何为 HelloWorld SEI 启用日志记录,其中传入消息发送到 < stdout> 和传出消息到 < logger>

24.3.4.17. 使用注解进行日志配置

@WebService
@Logging(limit=16000, inLocation="<stdout>")
public interface HelloWorld {
    String sayHi(@WebParam(name = "text") String text);
}

24.3.4.18. 在端点中添加属性和策略

摘要

属性和策略都可用于将配置数据与端点关联。它们之间的基本区别在于属性是 Apache CXF 特定的配置机制,而 策略 则是标准的 WSDL 配置机制。策略通常来自 WS 规格和标准,它们通常通过定义 W dl:policy 元素(在 WSDL 合同中出现)来设置。相反,属性是特定于 Apache CXF 的,它们通常通过在 Apache CXF Spring 配置文件中定义 jaxws:properties 元素进行设置。

不过,也可以使用注释在 Java 中定义属性设置和 WSDL 策略设置,如下所述。

24.3.4.19. 添加属性

@EndpointProperty 注释

@EndpointProperty 注释由 org.apache.cxf.annotations.EndpointProperty 接口定义。它放置在 SEI 上。

此注解为端点添加特定于 Apache CXF 的配置设置。endpoint 属性也可以在 Spring 配置文件中指定。例如,若要在端点上配置 WS-Security,您可以使用 Spring 配置文件中的 jaxws:properties 元素添加端点属性,如下所示:

<beans xmlns="http://www.springframework.org/schema/beans"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:jaxws="http://cxf.apache.org/jaxws"
   ... >

   <jaxws:endpoint
      id="MyService"
      address="https://localhost:9001/MyService"
      serviceName="interop:MyService"
      endpointName="interop:MyServiceEndpoint"
      implementor="com.foo.MyService">

      <jaxws:properties>
         <entry key="ws-security.callback-handler" value="interop.client.UTPasswordCallback"/>
         <entry key="ws-security.signature.properties" value="etc/keystore.properties"/>
         <entry key="ws-security.encryption.properties" value="etc/truststore.properties"/>
         <entry key="ws-security.encryption.username" value="useReqSigCert"/>
      </jaxws:properties>

   </jaxws:endpoint>
</beans>

另外,您可以通过在 SEI 中添加 @EndpointProperty 注解来指定 Java 中的上述配置设置,如 第 24.3.4.20 节 “使用 @EndpointProperty Annotations 配置 WS-Security” 所示。

24.3.4.20. 使用 @EndpointProperty Annotations 配置 WS-Security

@WebService
@EndpointProperty(name="ws-security.callback-handler" value="interop.client.UTPasswordCallback")
@EndpointProperty(name="ws-security.signature.properties" value="etc/keystore.properties")
@EndpointProperty(name="ws-security.encryption.properties" value="etc/truststore.properties")
@EndpointProperty(name="ws-security.encryption.username" value="useReqSigCert")
public interface HelloWorld {
    String sayHi(@WebParam(name = "text") String text);
}
@EndpointProperties annotation

@EndpointProperties 注释由 org.apache.cxf.annotations.EndpointProperties 接口定义。它放置在 SEI 上。

此注释提供了一种将多个 @EndpointProperty 注释分组到列表中的方法。使用 @EndpointProperties 时,可以重新编写 第 24.3.4.20 节 “使用 @EndpointProperty Annotations 配置 WS-Security”,如 第 24.3.4.21 节 “使用 @EndpointProperties 注解配置 WS-Security” 所示。

24.3.4.21. 使用 @EndpointProperties 注解配置 WS-Security

@WebService
@EndpointProperties(
  {
  @EndpointProperty(name="ws-security.callback-handler" value="interop.client.UTPasswordCallback"),
  @EndpointProperty(name="ws-security.signature.properties" value="etc/keystore.properties"),
  @EndpointProperty(name="ws-security.encryption.properties" value="etc/truststore.properties"),
  @EndpointProperty(name="ws-security.encryption.username" value="useReqSigCert")
})
public interface HelloWorld {
    String sayHi(@WebParam(name = "text") String text);
}

24.3.4.22. 添加策略

@policy 注释

@Policy 注释由 org.apache.cxf.annotations.Policy 接口定义。它可以放在 SEI 或 SEI 方法上。

此注释用于将 WSDL 策略与 SEI 或 SEI 方法关联。该策略通过提供 URI 来引用包含标准 wsdl:policy 元素的 XML 文件。如果从 SEI 生成 WSDL 合同(例如,使用 java2ws 命令行工具),您可以指定是否要将这个策略包含在 WSDL 中。

第 24.3.4.23 节 “@policy 属性” 显示 @Policy 注释支持的属性。

24.3.4.23. @policy 属性

属性描述

uri

(必需) 文件的位置,包含策略定义。

includeInWSDL

(可选) 在生成 WSDL 时,是否将策略包含在生成的合同中。默认为 true

placement

(可选) 指定在 WSDL 文件中显示此文档的位置。有关可能的放置值列表,请参阅 “在 WSDL 合同中放置”一节

faultClass

(可选) 如果放置设置为 BINDING_OPERATION_FAULTPORT_TYPE_OPERATION_FAULT,则必须设置此属性来指定这个策略应用到哪个故障。该值是代表故障的 Java 类。

@policies 注释

@Policies 注释由 org.apache.cxf.annotations.Policies 接口定义。它可以放在 SEI 或thse SEI 方法上。

此注释提供了一种将多个 @Policy 注释分组到列表中的方法。

在 WSDL 合同中放置

要指定在 WSDL 合同中应出现策略的位置,您可以指定 放置 属性,即 Policy.Placement 类型。放置可以具有以下值之一:

Policy.Placement.BINDING
Policy.Placement.BINDING_OPERATION
Policy.Placement.BINDING_OPERATION_FAULT
Policy.Placement.BINDING_OPERATION_INPUT
Policy.Placement.BINDING_OPERATION_OUTPUT
Policy.Placement.DEFAULT
Policy.Placement.PORT_TYPE
Policy.Placement.PORT_TYPE_OPERATION
Policy.Placement.PORT_TYPE_OPERATION_FAULT
Policy.Placement.PORT_TYPE_OPERATION_INPUT
Policy.Placement.PORT_TYPE_OPERATION_OUTPUT
Policy.Placement.SERVICE
Policy.Placement.SERVICE_PORT
@Policy 示例

以下示例演示了如何将 WSDL 策略与 HelloWorld SEI 关联,以及如何将策略与 sayHi 方法关联。策略本身存储在文件系统中的 XML 文件中,该文件在 注解policies 目录下。

@WebService
@Policy(uri = "annotationpolicies/TestImplPolicy.xml",
        placement = Policy.Placement.SERVICE_PORT),
@Policy(uri = "annotationpolicies/TestPortTypePolicy.xml",
        placement = Policy.Placement.PORT_TYPE)
public interface HelloWorld {
    @Policy(uri = "annotationpolicies/TestOperationPTPolicy.xml",
            placement = Policy.Placement.PORT_TYPE_OPERATION),
    String sayHi(@WebParam(name = "text") String text);
}
@Policies 示例

您可以使用 @Policies 注释将多个 @Policy 注释分组到列表中,如下例所示:

@WebService
@Policies({
    @Policy(uri = "annotationpolicies/TestImplPolicy.xml",
            placement = Policy.Placement.SERVICE_PORT),
    @Policy(uri = "annotationpolicies/TestPortTypePolicy.xml",
            placement = Policy.Placement.PORT_TYPE)
})
public interface HelloWorld {
    @Policy(uri = "annotationpolicies/TestOperationPTPolicy.xml",
            placement = Policy.Placement.PORT_TYPE_OPERATION),
    String sayHi(@WebParam(name = "text") String text);
}