Red Hat Summit 红帽全球峰会支持控制台（Console）开发人员开始试用联系人

24.3. 注解代码

24.3.1. JAX-WS 注释概述
复制链接

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

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

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

24.3.2. 所需的注解
复制链接

概述
复制链接

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

@WebService 注释
复制链接

@WebService 注释由 javax.jws.WebService 接口定义，它放置在旨在用作服务的接口或类上。@WebService 具有中描述的属性 表 24.1 “@WebService Properties”

Expand
表 24.1. @WebService Properties
属性描述

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 Annotation 的接口” 显示 例 24.1 “简单 SEI” 中定义的接口，它带有 @WebService 注释。

例 24.3. 带有 @WebService Annotation 的接口

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);
}
Copy to Clipboard Toggle word wrap

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

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

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

指定定义 published 服务的 wsdl:service 元素 的名称 值是 updateQuoteService。

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

指定定义公开服务端点的 wsdl:port 元素的 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)
  {
  ...
  }
}
Copy to Clipboard Toggle word wrap

24.3.3. 可选注解
复制链接

摘要

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

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

概述
复制链接

使用注解定义绑定属性

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

@SOAPBinding 注释
复制链接

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

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

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

Expand
表 24.2. @SOAPBinding Properties
属性值描述

style

样式.DOCUMENT （默认）

Style.RPC

指定 SOAP 消息的样式。如果指定了 RPC 样式，则 SOAP 正文中的每个消息部分都是参数或返回值，并显示在 soap:body 元素中的 wrapper 元素中。wrapper 元素中的 message 部分对应于操作参数，且必须按照与操作中的参数相同的顺序。如果指定了 DOCUMENT 样式，则 SOAP 正文的内容必须是有效的 XML 文档，但它的格式不如严格约束。

使用

use.LITERAL （默认）

use.ENCODED[a]

指定 SOAP 消息的数据如何流化。

parameterStyle [b]

ParameterStyle.BARE

ParameterStyle.WRAPPED （默认）

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

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

记录裸机风格的参数
复制链接

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

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

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

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

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

文档嵌套参数
复制链接

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

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

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

Example
复制链接

例 24.5 “使用 SOAP Binding Annotation 指定 Document Bare SOAP Binding” 显示一个使用文档 bare SOAP 消息的 SEI。

例 24.5. 使用 SOAP Binding Annotation 指定 Document 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
{
  ...
}
Copy to Clipboard Toggle word wrap

概述
复制链接

使用注解定义操作属性

当运行时将 Java 方法定义映射到 XML 操作定义中时，它提供了如下详细信息：

  • 在 XML 中交换的消息是什么
  • 如果消息可以以一种方式优化
  • 定义消息的命名空间

@WebMethod 注释
复制链接

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

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

Expand
表 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 请求消息时使用。

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

Expand
表 24.4. @RequestWrapper Properties
属性描述

localName

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

targetNamespace

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

className

指定实施 wrapper 元素的 Java 类的全名。

注意

仅需要 className 属性。

重要

如果方法也标上 @SOAPBinding 注释，其 parameterStyle 属性设为 ParameterStyle.BARE，则此注释将被忽略。

@ResponseWrapper 注释
复制链接

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

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

Expand
表 24.5. @ResponseWrapper Properties
属性描述

localName

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

targetNamespace

指定定义 XML wrapper 元素的命名空间。默认值为 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 注释的属性。

Expand
表 24.6. @WebFault Properties
属性描述

name

指定 fault 元素的本地名称。

targetNamespace

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

faultName

指定实现例外的 Java 类的全名。

重要

name 属性是必需的。

@Oneway 注释
复制链接

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

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

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

Example
复制链接

例 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);
}
Copy to Clipboard Toggle word wrap

概述
复制链接

使用注解定义参数属性

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

@WebParam 注释
复制链接

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

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

Expand
表 24.7. @WebParam Properties
属性值描述

name

 

指定在生成的 WSDL 文档中显示的参数名称。对于 RPC 绑定，这是代表参数的 wsdl:part 的名称。对于文档绑定，这是代表 参数的 XML 元素的本地名称。根据 JAX-WS 规范，默认值为 argN，其中 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 注释的属性。

Expand
表 24.8. @WebResult Properties
属性描述

name

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

targetNamespace

指定返回值的命名空间。它仅用于返回值映射到 XML 元素的文档绑定。默认为使用服务的命名空间。

header

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

partName

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

Example
复制链接

例 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
  );
}
Copy to Clipboard Toggle word wrap

24.3.4. Apache CXF 注解
复制链接

24.3.4.1. WSDL 文档
复制链接

@WSDL 文档注释
复制链接

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

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

24.3.4.2. @WSDL 文档属性
复制链接

Expand
属性描述

value

（必需） 包含文档文本的字符串。

placement

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

faultClass

（可选） 如果将放置设置为 FAULT_MESSAGE、PORT_TYPE_OPERATION_FAULT 或 BINDING_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 文档” 演示了如何向 SEI 和其中一个方法添加 @WSDL 文档 注释。

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);
}
Copy to Clipboard Toggle word wrap

当 WSDL 在 第 24.3.4.4 节 “使用文档生成的 WSDL” 中显示时，从 第 24.3.4.3 节 “使用 @WSDL 文档” 中的 SEI 生成，文档 元素的默认位置分别是 PORT_TYPE 和 PORT_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>
Copy to Clipboard Toggle word wrap
@WSDLDocumentationCollection 示例
复制链接

第 24.3.4.5 节 “使用 @WSDLDocumentationCollection” 演示了如何将 @WSDLDocumentationCollection 注释添加到 SEI。

24.3.4.5. 使用 @WSDLDocumentationCollection
复制链接

@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);
}
Copy to Clipboard Toggle word wrap

24.3.4.6. 消息架构验证
复制链接

@SchemaValidation 注释
复制链接

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

此注解打开发送到此端点的 XML 消息的架构验证。当您怀疑传入的 XML 消息格式存在问题时，这可用于测试目的。默认情况下禁用验证，因为它对性能有严重影响。

模式验证类型
复制链接

模式验证行为由 type 参数控制，其值是 org.apache.cxf.annotations.SchemaValidation.SchemaValidationType 类型的枚举。第 24.3.4.7 节 “模式验证类型值” 显示可用验证类型的列表。

24.3.4.7. 模式验证类型值
复制链接

Expand
类型描述

IN

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

OUT

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

两者都

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

NONE

禁用所有模式验证。

REQUEST （请求）

将架构验证应用到 Request 消息-即，导致验证应用到传出客户端消息和传入的服务器消息。

响应

将架构验证应用到响应消息（即，验证应用到传入客户端消息）和传出服务器消息。

Example
复制链接

以下示例演示了如何根据 MyService SEI 为端点启用架构消息验证。请注意，注解如何作为一个整体应用到 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);
}
Copy to Clipboard Toggle word wrap

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 内核。

Example
复制链接

第 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);
}
Copy to Clipboard Toggle word wrap

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
复制链接

Expand
属性描述

threshold

小于此属性指定大小的消息 不会被 gzipped。默认为 -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
复制链接

Expand
属性描述

force

强制使用 FastInfoset 格式的布尔值属性，而不是 negotiating。为 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);
}
Copy to Clipboard Toggle word wrap
exampe @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);
}
Copy to Clipboard Toggle word wrap

24.3.4.15. 在端点上启用日志记录
复制链接

@logging 注解
复制链接

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

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

24.3.4.16. @logging Properties
复制链接

Expand
属性描述

limit

指定大小限制，超过日志中消息被截断。默认为 64K。

inLocation

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

outLocation

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

Example
复制链接

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

24.3.4.17. 使用注解进行日志记录配置
复制链接

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

24.3.4.18. 在端点中添加属性和策略
复制链接

摘要

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

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

24.3.4.19. 添加属性
复制链接

@EndpointProperty 注释
复制链接

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

此注解在端点中添加特定于 Apache CXF 的配置设置。端点属性也可以在 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>
Copy to Clipboard Toggle word wrap

或者，您可以通过在 SEI 中添加 @EndpointProperty 注解来指定 Java 前面的配置设置，如 第 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);
}
Copy to Clipboard Toggle word wrap
@EndpointProperties 注释
复制链接

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

此注释提供了将多个 @EndpointProperty 注解分组到列表中的方法。使用 @EndpointProperties 时，可以重新写入 第 24.3.4.20 节 “使用 @EndpointProperty Annotations 配置 WS-Security”，如 第 24.3.4.21 节 “使用 @EndpointProperties Annotation 配置 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);
}
Copy to Clipboard Toggle word wrap

24.3.4.22. 添加策略
复制链接

@policy 注释
复制链接

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

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

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

24.3.4.23. @policy Properties
复制链接

Expand
属性描述

uri

（必需） 包含策略定义的文件的位置。

includeInWSDL

（可选） 在生成 WSDL 时，是否在生成的合同中包含策略。默认为 true。

placement

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

faultClass

（可选） 如果将放置设置为 BINDING_OPERATION_FAULT 或 PORT_TYPE_OPERATION_FAULT，则必须设置此属性来指定此策略应用到哪些错误。值是代表 fault 的 Java 类。

@policies 注释
复制链接

@Policies 注释由 org.apache.cxf.annotations.Policies 接口定义。它可以放置在 SEI 或第 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
Copy to Clipboard Toggle word wrap
@Policy 示例
复制链接

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

@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);
}
Copy to Clipboard Toggle word wrap
@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);
}
Copy to Clipboard Toggle word wrap
返回顶部
Red Hat logoGithubredditYoutubeTwitter

学习

尝试、购买和销售

社区

关于红帽文档

通过我们的产品和服务，以及可以信赖的内容，帮助红帽用户创新并实现他们的目标。 了解我们当前的更新.

让开源更具包容性

红帽致力于替换我们的代码、文档和 Web 属性中存在问题的语言。欲了解更多详情，请参阅红帽博客.

關於紅帽

我们提供强化的解决方案，使企业能够更轻松地跨平台和环境（从核心数据中心到网络边缘）工作。

Theme

© 2025 Red Hat