40.3. 生成 Stub Code

概述

异步调用方式需要额外的 stub 代码用于 SEI 上定义的专用的异步方法。默认不生成此特殊存根代码。要切换异步功能并生成 requisite stub 代码,您必须使用 WSDL 2.0 规格中映射自定义功能。

自定义可让您修改 Maven 代码生成插件生成 stub 代码的方式。特别是,它可让您修改 WSDL-to-Java 映射,并切换某些功能。在这里,自定义 用于在异步调用功能上切换。使用绑定声明指定自定义,您可以使用 jaxws:bindings 标签进行定义(其中 jaxws 前缀与 http://java.sun.com/xml/ns/jaxws 命名空间相关联)。指定绑定声明的方法有两种:

外部绑定声明
使用外部绑定声明时,jaxws:bindings 元素在独立于 WSDL 合同的文件中定义。您在生成 stub 代码时,将绑定声明文件的位置指定为代码生成器。
内嵌绑定声明
在使用嵌入式绑定声明时,您直接嵌入了 jaxws:bindings 元素,直接包含在 WSDL 合同中,将其视为 WSDL 扩展。在这种情况下,jaxws:bindings 中的设置仅应用于 immediate 父元素。

使用外部绑定声明

例 40.2 “用于同步的绑定声明模板” 中会显示在异步调用中切换的绑定声明文件模板。

例 40.2. 用于同步的绑定声明模板

<bindings xmlns:xsd="http://www.w3.org/2001/XMLSchema"
          xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
          wsdlLocation="AffectedWSDL"
          xmlns="http://java.sun.com/xml/ns/jaxws">
  <bindings node="AffectedNode">
    <enableAsyncMapping>true</enableAsyncMapping>
  </bindings>
</bindings>

其中 AffectedWSDL 指定受此绑定声明影响的 WSDL 合同的 URL。AffectedNode 是一个 XPath 值,用于指定来自 WSDL 合同的节点(或节点)会受到此绑定声明的影响。如果您希望整个 WSDL 合同会受到影响,可以将 AffectedNode 设置为 wsdl:definitionsjaxws:enableAsyncMapping 元素设为 true,以启用异步调用功能。

例如,如果您只想为 GreeterAsync 接口生成异步方法,您可以在前面的绑定声明中指定 <bindings node="wsdl:definitions/wsdl:portType[@name='GreeterAsync']">。

假设绑定声明存储在一个文件中, async_binding.xml 中,您需要设置 POM,如 例 40.3 “消费者代码生成” 所示。

例 40.3. 消费者代码生成

<plugin>
  <groupId>org.apache.cxf</groupId>
  <artifactId>cxf-codegen-plugin</artifactId>
  <version>${cxf.version}</version>
  <executions>
    <execution>
      <id>generate-sources</id>
      <phase>generate-sources</phase>
      <configuration>
        <sourceRoot>outputDir</sourceRoot>
        <wsdlOptions>
          <wsdlOption>
            <wsdl>hello_world.wsdl</wsdl>
            <extraargs>
              <extraarg>-client</extraarg>
              <extraarg>-b async_binding.xml</extraarg>
            </extraargs>
          </wsdlOption>
        </wsdlOptions>
      </configuration>
      <goals>
        <goal>wsdl2java</goal>
      </goals>
    </execution>
  </executions>
</plugin>

-b 选项告知代码生成器查找外部绑定文件。

有关代码生成器的详情请参考 第 44.2 节 “cxf-codegen-plugin”

使用嵌入的绑定声明

您还可以通过将 jaxws:bindings 元素及其关联的 jaxws:enableAsynchMapping 子项直接放入 WSDL,将绑定自定义直接嵌入到 WSDL 中。您还必须为 jaxws 前缀添加命名空间声明。

例 40.4 “用于同步映射的带有嵌入式绑定声明的 WSDL” 显示包含内嵌绑定声明的 WSDL 文件,它激活操作异步映射。

例 40.4. 用于同步映射的带有嵌入式绑定声明的 WSDL

<wsdl:definitions xmlns="http://schemas.xmlsoap.org/wsdl/"
                  ...
                  xmlns:jaxws="http://java.sun.com/xml/ns/jaxws"
                  ...>
  ...
  <wsdl:portType name="GreeterAsync">
    <wsdl:operation name="greetMeSometime">
      <jaxws:bindings> <jaxws:enableAsyncMapping>true</jaxws:enableAsyncMapping> </jaxws:bindings>
      <wsdl:input name="greetMeSometimeRequest"
                  message="tns:greetMeSometimeRequest"/>
      <wsdl:output name="greetMeSometimeResponse"
                   message="tns:greetMeSometimeResponse"/>
    </wsdl:operation>
  </wsdl:portType>
  ...
</wsdl:definitions>

将绑定声明嵌入到 WSDL 文档中时,您可以通过更改声明的位置来控制受声明影响的范围。当声明作为 wsdl:definitions 元素的子项时,代码生成器会为 WSDL 文档中定义的所有操作创建异步方法。如果被放入为 wsdl:portType 元素的子项,则代码生成器会为接口中定义的所有操作创建异步方法。如果被置于一个 wsdl:operation 元素的子项,则代码生成器只为该操作创建异步方法。

在使用嵌入式声明时,不需要将任何特殊选项传递给代码生成器。代码生成器将识别它们并相应地执行。

生成的接口

以这种方式生成存根代码后,GreeterAsync SEI(在文件 GreeterAsync.java中)被定义为 例 40.5 “带有同步调用的方法的服务端点接口”

例 40.5. 带有同步调用的方法的服务端点接口

package org.apache.hello_world_async_soap_http;

import org.apache.hello_world_async_soap_http.types.GreetMeSometimeResponse;
...

public interface GreeterAsync
{
  public Future<?> greetMeSometimeAsync(
        java.lang.String requestType,
        AsyncHandler<GreetMeSometimeResponse> asyncHandler
    );

    public Response<GreetMeSometimeResponse> greetMeSometimeAsync(
        java.lang.String requestType
    );

    public java.lang.String greetMeSometime(
        java.lang.String requestType
    );
}

除了常见的同步方法外,gre etMeSometime() 还会为 greetMeSometime 操作生成两个异步方法:

  • 回调方法公共Future<?&gt;greetMeSomtimeAsyncjava.lang.StringrequestTypeAsyncHandler<GreetMeSomtimeResponse>asyncHandler
  • 轮询方法公共Response<GreetMeSomeTimeResponse&gt;greetMeSometimeAsyncjava.lang.StringrequestType