24.3. 为代码添加注解

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

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

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

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

要指定文档在 WSDL 合同中应显示的位置，您可以指定 placement 属性，即 WSDL 文档。Placement .放置可以有以下值之一：

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

第 24.3.4.5 节 “使用 @WSDLDocumentationCollection” 介绍如何向 SEI 添加 @WSDL 文档Collection 注释。

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

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

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

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

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

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

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

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

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

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

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

@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.13 节 “启用 GZIP” 演示了如何为 HelloWorld SEI 启用 GZIP 压缩。

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

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

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

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

@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” 所示。

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

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

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

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

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

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

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

要指定策略在 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

以下示例演示了如何将 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 注释将多个 @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);
}