搜索

24.3. 为代码添加注解

download PDF

24.3.1. JAX-WS Annotations 概述

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

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

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

24.3.2. 所需的注解

概述

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

@WebService 注释

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

表 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 注释的接口” 显示 例 24.1 “简单 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 合同。

指定定义服务所公开的端点的 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)
  {
  ...
  }
}

24.3.3. 可选注解

摘要

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

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

概述

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

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 合同中应显示的位置,您可以指定 placement 属性,即 WSDL 文档。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 文档” 中的 SEI 生成时,文档 元素的默认放置分别为 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 节 “使用 @WSDLDocumentationCollection” 介绍如何向 SEI 添加 @WSDL 文档Collection 注释。

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

24.3.4.6. Messages 模式验证

@SchemaValidation annotation

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

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

模式验证类型

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

24.3.4.7. 模式验证类型值

类型描述

IN

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

OUT

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

两者

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

NONE

所有架构验证都被禁用。

REQUEST (请求)

应用架构验证以请求消息 - 也就是说,使验证应用到传出客户端消息和传入服务器消息。

RESPONSE

将架构验证应用到响应消息 - 也就是说,使验证应用到传入的客户端消息,以及传出服务器消息。

示例

以下示例演示了如何根据 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);
}

24.3.4.8. 指定数据绑定

@DataBinding annotation

@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 是一个协商的增强。也就是说,客户端的初始请求不会被压缩,但会添加 Accept 标头;如果服务器支持 GZIP 压缩,则响应将被 gzip 压缩,并且任何后续请求也会被压缩。

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

24.3.4.11. @GZIP 属性

属性描述

threshold

比此属性指定的大小小的消息 不会被 压缩。默认为 -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 格式而非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);
}
@FastInfoset 的考查

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

24.3.4.14. Enabling 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 规范和标准,并且通常通过定义 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>

另外,您还可以在 Java 中指定上述配置设置,方法是在 SEI 中添加 @EndpointProperty 注解,如 第 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 方法关联。通过提供引用包含标准 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 文件中,该文件存储在 annotations 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);
}
Red Hat logoGithubRedditYoutubeTwitter

学习

尝试、购买和销售

社区

关于红帽文档

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

让开源更具包容性

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

關於紅帽

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

© 2024 Red Hat, Inc.