第 17 章 配置 JAX-WS 端点

摘要

JAX-WS 端点使用三个 Spring 配置元素之一进行配置。正确的元素取决于您要配置的端点类型以及您要使用的功能。对于使用 jaxws:client 元素的用户。对于服务供应商，您可以使用 jaxws:endpoint 元素或 jaxws:server 元素。

用于定义端点的信息通常在端点的合同中定义。您可以使用配置元素覆盖合同中的信息。您还可以使用配置元素来提供合同中未提供的信息。

您必须使用配置元素激活 WS-RM 等高级功能。这可以通过向端点配置元素提供子元素来完成。请注意，当处理使用 Java 先行方法开发的端点时，SEI 可能会在端点合同中缺少有关绑定和传输要使用的绑定和传输信息的信息。

17.1. 配置服务供应商

17.1.1. 配置服务提供程序的元素

Apache CXF 有两个元素可用于配置服务提供商：

这两个元素之间的差异在很大程度上是运行时的内部。jaxws:endpoint 元素将属性注入 org.apache.cxf.jaxws.EndpointImpl 对象，以支持服务端点。jaxws:server 元素将属性注入 org.apache.cxf.jaxws.support.JaxWsServerFactoryBean 对象来支持端点。EndpointImpl 对象将配置数据传递给 JaxWsServerFactoryBean 对象。JaxWsServerFactoryBean 对象用于创建实际服务对象。因为任何一个配置元素都会配置服务端点，因此您可以根据您喜欢的语法进行选择。

17.1.2. 使用 jaxws:endpoint Element

概述

jaxws:endpoint 元素是配置 JAX-WS 服务提供商的默认元素。其属性和子项指定实例化服务提供商所需的所有信息。许多属性都映射到服务合同中的信息。子进程用于配置拦截器和其他高级功能。

识别正在配置的端点

要使运行时将配置应用到正确的服务提供商，它必须能够识别它。识别服务供应商的基本方法是指定实施端点的类。这可以通过使用 jaxws:endpoint 元素的 implementor 属性来完成。

对于不同端点共享常见实现的实例，可以为每个端点提供不同的配置。在配置中，有两种方法可用于区分特定端点：

  • serviceName 属性和 endpointName 属性的组合

    serviceName 属性指定定义服务端点的 wsdl:service 元素。endpointName 属性指定定义服务端点的特定 wsdl:port 元素。这两个属性都以 QNames 指定，格式为 ns:name。ns 是元素的命名空间，name 是元素的 name 属性的值。

    注意

    如果 wsdl:service 元素只有一个 wsdl:port 元素，则可以省略 endpointName 属性。

  • name 属性

    name 属性指定定义服务端点的特定 wsdl:port 元素的 QName。QName 以 {ns}localPart格式提供。ns 是 wsdl:port 元素的命名空间，localPart 是 wsdl:port 元素的 name 属性的值。

属性

jaxws:endpoint 元素的属性配置端点的基本属性。这些属性包括端点的地址、实施端点的类，以及托管端点的 总线。

表 17.1 “使用 jaxws:endpoint 元素配置 JAX-WS 服务提供商的属性” 描述 jaxws:endpoint 元素的属性。

表 17.1. 使用 jaxws:endpoint 元素配置 JAX-WS 服务提供商的属性

属性描述

id

指定唯一标识符，其他配置元素可用于引用端点。

implementor

指定实施该服务的类。您可以使用类名称或对 Spring bean 配置实施类的 ID 引用来指定实施类。此类必须在 classpath 上。

implementorClass

指定实施该服务的类。当为 implementor 属性提供的值是一个对使用 Spring AOP 进行嵌套的 bean 的引用时，此属性很有用。

address

指定 HTTP 端点的地址。这个值会覆盖服务合同中指定的值。

wsdlLocation

指定端点 WSDL 合同的位置。WSDL 合同的位置相对于部署该服务的文件夹。

endpointName

指定服务的 wsdl:port 元素的 name 属性的值。它被指定为 QName，格式为 ns:name，其中 ns 是 wsdl:port 元素的命名空间。

serviceName

指定服务的 wsdl:service 元素的 name 属性的值。它被指定为 QName，格式为 ns:name，其中 ns 是 wsdl:service 元素的命名空间。

publish

指定是否应自动发布该服务。如果它被设置为 false，则开发人员必须明确发布 第 31 章 发布服务 中描述的端点。

bus

指定 Spring bean 配置用于管理服务端点的总线的 ID。这在将多个端点配置为使用一组通用的功能时很有用。

bindingUri

指定服务使用的消息绑定 ID。第 23 章 Apache CXF Binding ID 中提供了有效绑定 ID 列表。

name

指定服务的 wsdl:port 元素的字符串 QName。它使用格式 {ns}localPart 指定为 QName。ns 是 wsdl:port 元素的命名空间，localPart 是 wsdl:port 元素的 name 属性的值。

abstract

指定 bean 是抽象 bean。抽象 bean 作为 concrete bean 定义的父项，它们不会被实例化。默认值为 false。把它设置为 true 会指示 bean 工厂不要实例化 bean。

depends-on

指定端点在实例化前依赖的 Bean 列表。

createdFromAPI

指定使用 Apache CXF API 创建的用户，如 Endpoint.publish （） 或 Service.getPort （）。

默认值为 false。

把它设置为 true 执行以下操作：

  • 通过将 .jaxws-endpoint 附加到其 ID 来更改 bean 的内部名称
  • 使 bean 抽象

publishedEndpointUrl

放入生成的 WSDL 地址 元素中的 URL。如果没有指定这个值，则使用 address 属性的值。当 "public" URL 不与部署该服务的 URL 不同时，此属性很有用。

除了 表 17.1 “使用 jaxws:endpoint 元素配置 JAX-WS 服务提供商的属性” 中列出的属性外，您可能需要使用多个 xmlns:shortName 属性来声明 endpointName 和 serviceName 属性使用的命名空间。

示例

例 17.1 “简单 JAX-WS 端点配置” 显示 JAX-WS 端点的配置，用于指定端点发布的地址。这个示例假设您想将默认值用于所有其他值，或者实施在注解中指定了值。

例 17.1. 简单 JAX-WS 端点配置

<beans ...
  xmlns:jaxws="http://cxf.apache.org/jaxws"
  ...
  schemaLocation="...
    http://cxf.apache.org/jaxws http://cxf.apache.org/schemas/jaxws.xsd
    ...">
  <jaxws:endpoint id="example"
                  implementor="org.apache.cxf.example.DemoImpl"
                  address="http://localhost:8080/demo" />
</beans>

例 17.2 “带有服务名称的 JAX-WS 端点配置” 显示 JAX-WS 端点的配置，其合同中包含两个服务定义。在这种情况下，您必须使用 serviceName 属性指定要实例化的服务定义。

例 17.2. 带有服务名称的 JAX-WS 端点配置

<beans ...
  xmlns:jaxws="http://cxf.apache.org/jaxws"
  ...
  schemaLocation="...
    http://cxf.apache.org/jaxws http://cxf.apache.org/schemas/jaxws.xsd
    ...">

  <jaxws:endpoint id="example2"
                  implementor="org.apache.cxf.example.DemoImpl"
                  serviceName="samp:demoService2"
                  xmlns:samp="http://org.apache.cxf/wsdl/example" />

</beans>

xmlns:samp 属性指定定义 WSDL 服务 元素的命名空间。

17.1.3. 使用 jaxws:server Element

概述

jaxws:server 元素是配置 JAX-WS 服务提供商的元素。它将配置信息注入到 org.apache.cxf.jaxws.support.JaxWsServerFactoryBean 中。这是特定于 Apache CXF 的对象。如果您使用纯 Spring 方法来构建您的服务，则不会强制使用 Apache CXF 特定的 API 与服务交互。

jaxws:server 元素的属性和子项指定实例化服务提供商所需的所有信息。属性指定实例化端点所需的信息。子进程用于配置拦截器和其他高级功能。

识别正在配置的端点

要让运行时将配置应用到正确的服务提供商，它必须能够识别它。识别服务供应商的基本方法是指定实施端点的类。这通过使用 jaxws:server 元素的 serviceBean 属性来实现。

对于不同端点共享常见实现的实例，可以为每个端点提供不同的配置。在配置中，有两种方法可用于区分特定端点：

  • serviceName 属性和 endpointName 属性的组合

    serviceName 属性指定定义服务端点的 wsdl:service 元素。endpointName 属性指定定义服务端点的特定 wsdl:port 元素。这两个属性都以 QNames 指定，格式为 ns:name。ns 是元素的命名空间，name 是元素的 name 属性的值。

    注意

    如果 wsdl:service 元素只有一个 wsdl:port 元素，则可以省略 endpointName 属性。

  • name 属性

    name 属性指定定义服务端点的特定 wsdl:port 元素的 QName。QName 以 {ns}localPart格式提供。ns 是 wsdl:port 元素的命名空间，localPart 是 wsdl:port 元素的 name 属性的值。

属性

jaxws:server 元素的属性配置端点的基本属性。这些属性包括端点的地址、实施端点的类，以及托管端点的 总线。

表 17.2 “使用 jaxws:server 元素配置 JAX-WS 服务提供商的属性” 描述 jaxws:server 元素的属性。

表 17.2. 使用 jaxws:server 元素配置 JAX-WS 服务提供商的属性

属性描述

id

指定唯一标识符，其他配置元素可用于引用端点。

serviceBean

指定实施该服务的类。您可以使用类名称或对 Spring bean 配置实施类的 ID 引用来指定实施类。此类必须在 classpath 上。

serviceClass

指定实施该服务的类。当为 implementor 属性提供的值是一个对使用 Spring AOP 进行嵌套的 bean 的引用时，此属性很有用。

address

指定 HTTP 端点的地址。这个值将覆盖服务合同中指定的值。

wsdlLocation

指定端点 WSDL 合同的位置。WSDL 合同的位置相对于部署该服务的文件夹。

endpointName

指定服务的 wsdl:port 元素的 name 属性的值。它被指定为 QName，格式为 ns:name，其中 ns 是 wsdl:port 元素的命名空间。

serviceName

指定服务的 wsdl:service 元素的 name 属性的值。它被指定为 QName，格式为 ns:name，其中 ns 是 wsdl:service 元素的命名空间。

publish

指定是否应自动发布该服务。如果它被设置为 false，则开发人员必须明确发布 第 31 章 发布服务 中描述的端点。

bus

指定 Spring bean 配置用于管理服务端点的总线的 ID。这在将多个端点配置为使用一组通用的功能时很有用。

bindingId

指定服务使用的消息绑定 ID。第 23 章 Apache CXF Binding ID 中提供了有效绑定 ID 列表。

name

指定服务的 wsdl:port 元素的字符串 QName。它使用 {ns}localPart 格式来指定为 QName，其中 ns 是 wsdl:port 元素的命名空间，localPart 是 wsdl:port 元素的 name 属性的值。

abstract

指定 bean 是抽象 bean。抽象 bean 作为 concrete bean 定义的父项，它们不会被实例化。默认值为 false。把它设置为 true 会指示 bean 工厂不要实例化 bean。

depends-on

指定端点在实例化端点之前实例化的 Bean 列表。

createdFromAPI

指定使用 Apache CXF API 创建的用户，如 Endpoint.publish （） 或 Service.getPort （）。

默认值为 false。

把它设置为 true 执行以下操作：

  • 通过将 .jaxws-endpoint 附加到其 ID 来更改 bean 的内部名称
  • 使 bean 抽象

除了 表 17.2 “使用 jaxws:server 元素配置 JAX-WS 服务提供商的属性” 中列出的属性外，您可能需要使用多个 xmlns:shortName 属性来声明 endpointName 和 serviceName 属性使用的命名空间。

示例

例 17.3 “简单 JAX-WS 服务器配置” 显示 JAX-WS 端点的配置，用于指定端点发布的地址。

例 17.3. 简单 JAX-WS 服务器配置

<beans ...
  xmlns:jaxws="http://cxf.apache.org/jaxws"
  ...
  schemaLocation="...
    http://cxf.apache.org/jaxws http://cxf.apache.org/schemas/jaxws.xsd
    ...">
  <jaxws:server id="exampleServer"
                  serviceBean="org.apache.cxf.example.DemoImpl"
                  address="http://localhost:8080/demo" />
</beans>

17.1.4. 在服务提供程序中添加功能

概述

jaxws:endpoint 和 jaxws:server 元素提供实例化服务提供商所需的基本配置信息。要为您的服务提供商添加功能或执行高级配置，您必须在配置中添加子元素。

通过子元素，您可以执行以下操作：

元素

表 17.3 “用于配置 JAX-WS 服务提供程序的元素” 描述 jaxws:endpoint 支持的子元素。

表 17.3. 用于配置 JAX-WS 服务提供程序的元素

element描述

jaxws:handlers

指定用于处理消息的 JAX-WS 处理程序列表。有关 JAX-WS 处理程序实施的更多信息，请参阅 第 43 章 编写处理程序。

jaxws:inInterceptors

指定处理入站请求的拦截器列表。更多信息请参阅 第 VII 部分 “开发 Apache CXF Interceptors”。

jaxws:inFaultInterceptors

指定处理入站错误信息的拦截器列表。更多信息请参阅 第 VII 部分 “开发 Apache CXF Interceptors”。

jaxws:outInterceptors

指定处理出站回复的拦截器列表。更多信息请参阅 第 VII 部分 “开发 Apache CXF Interceptors”。

jaxws:outFaultInterceptors

指定处理出站错误消息的拦截器列表。更多信息请参阅 第 VII 部分 “开发 Apache CXF Interceptors”。

jaxws:binding

指定 bean 配置端点使用的消息绑定。使用 org.apache.cxf.binding.BindingFactory 接口的实现来配置消息绑定。[a]

jaxws:dataBinding [b]

指定实施端点使用的数据绑定的类。这可以通过一个嵌入式 bean 定义来指定。

jaxws:executor

指定用于该服务的 Java executor。这可以通过一个嵌入式 bean 定义来指定。

jaxws:features

指定配置 Apache CXF 高级功能的 Bean 列表。您可以提供 bean 参考列表或嵌入式 Bean 列表。

jaxws:invoker

指定服务使用的 org.apache.cxf.service.Invoker 接口的实施。 [c]

jaxws:properties

指定传递给端点的属性的 Spring 映射。这些属性可用于控制启用 MTOM 支持等功能。

jaxws:serviceFactory

指定用来实例化该服务的 JaxWsServiceFactoryBean 对象的 bean。

[a] SOAP 绑定使用 soap:soapBinding bean 配置。
[b] jaxws:endpoint 元素不支持 jaxws:dataBinding 元素。
[c] Invoker 实施控制如何调用服务。例如，它控制每个请求是否由服务实施的新实例处理，或者是否在调用期间保留状态。

17.1.5. 在 JAX-WS 端点上启用 Schema Validation

概述

您可以设置 schema-validation-enabled 属性，以在 jaxws:endpoint 元素或 jaxws:server 元素中启用 schema 验证。启用架构验证后，检查客户端和服务器之间发送的消息是否符合该架构。默认情况下，模式验证处于关闭状态，因为它对性能有严重影响。

示例

要在 JAX-WS 端点上启用架构验证，请在 jaxws:endpoint 元素或 jaxws:server 元素的 jaxws:properties 子元素中设置 schema-validation-enabled 属性。例如，要在 jaxws:endpoint 元素中启用 schema 验证： 

<jaxws:endpoint name="{http://apache.org/hello_world_soap_http}SoapPort"
    wsdlLocation="wsdl/hello_world.wsdl"
    createdFromAPI="true">
    <jaxws:properties>
        <entry key="schema-validation-enabled" value="BOTH" />
    </jaxws:properties>
</jaxws:endpoint>

有关 schema-validation-enabled 属性允许的值列表，请参考 第 24.3.4.7 节 “模式验证类型值”。