24.3. 注解代码

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

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

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

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

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

第 24.3.4.3 节 “使用 @WSDL 文档” 演示了如何向 SEI 和其中一个方法添加 @WSDL 文档 注释。

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

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

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

模式验证行为由 type 参数控制，其值是 org.apache.cxf.annotations.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 是一个协商的增强。也就是说，不会对客户端的初始请求进行 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 Properties” 显示您可以在此注解中设置的可选属性。

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

@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>

或者，您可以通过在 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 Annotation 配置 WS-Security” 所示。

@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 注释支持的属性。

@Policies 注释由 org.apache.cxf.annotations.Policies 接口定义。它可以放置在 SEI 或第 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 文件中，在 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);
}

您可以使用 @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);
}