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 合同中应当出现文档的位置，您可以指定 放置 属性，类型为 WSDLDocumentation.Placement。放置可以具有以下值之一：

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

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

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

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

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

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

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

第 24.3.4.11 节 “@GZIP Properties” 显示 @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 节 “启用 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 的配置设置。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” 所示。

@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 方法关联。该策略通过提供 URI 来引用包含标准 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 文件中，该文件在 注解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);
}