44.2. cxf-codegen-plugin

摘要

从 WSDL 文档生成符合 JAX-WS 的 Java 代码

概述

基本示例

以下 POM 提取显示了如何配置 Maven cxf-codegen-plugin 来处理 myService.wsdl WSDL 文件的简单示例:

<plugin>
  <groupId>org.apache.cxf</groupId>
  <artifactId>cxf-codegen-plugin</artifactId>
  <version>3.3.6.fuse-7_11_1-00015-redhat-00002</version>
  <executions>
    <execution>
      <id>generate-sources</id>
      <phase>generate-sources</phase>
      <configuration>
        <sourceRoot>target/generated/src/main/java</sourceRoot>
        <wsdlOptions>
          <wsdlOption>
            <wsdl>src/main/resources/wsdl/myService.wsdl</wsdl>
          </wsdlOption>
        </wsdlOptions>
      </configuration>
      <goals>
        <goal>wsdl2java</goal>
      </goals>
    </execution>
  </executions>
</plugin>

基本配置设置

在前面的示例中,您可以自定义以下配置设置

configuration/sourceRoot
指定要存储生成的 Java 文件的目录。默认为 target/generated-sources/cxf
configuration/wsdlOptions/wsdlOption/wsdl
指定 WSDL 文件的位置。

描述

wsdl2java 任务采用 WSDL 文档,并从中生成经过完整注解的 Java 代码以实施服务。WSDL 文档必须具有有效的 portType 元素,但不需要包含 绑定 元素 或服务 元素。使用可选参数,您可以自定义生成的代码。

WSDL 选项

配置插件需要至少一个 wsdlOptions 元素。wsdlOptions 元素的 wsdl child 是必需的,并指定了由插件处理的 WSDL 文档。除了 wsdl 元素外,wsdlOptions 元素也可取多个可自定义 WSDL 文档的处理方式的子项。

插件配置中可以列出多个 wsdlOptions 元素。每一元素配置单个 WSDL 文档以用于处理。

默认选项

defaultOptions 元素是一个可选元素。它可用于设置所有指定的 WSDL 文档中使用的选项。

重要

如果在 wsdlOptions 元素中重复某个选项,wsdlOptions 元素中的值会优先使用。

指定代码生成选项

要指定通用代码生成选项(与 Apache CXF wsdl2java 命令行工具支持的交换机),您可以添加 extraargs 元素作为 wsdlOption 元素的子项。例如,您可以添加 -impl 选项和 -verbose 选项,如下所示:

...
<configuration>
  <sourceRoot>target/generated/src/main/java</sourceRoot>
  <wsdlOptions>
    <wsdlOption>
      <wsdl>${basedir}/src/main/resources/wsdl/myService.wsdl</wsdl>
      <!-- you can set the options of wsdl2java command by using the <extraargs> -->
      <extraargs>
        <extraarg>-impl</extraarg>
        <extraarg>-verbose</extraarg>
      </extraargs>
    </wsdlOption>
  </wsdlOptions>
</configuration>
...

如果交换机使用参数,您可以使用后续 extraarg 元素来指定这些参数。例如,要指定 jibx 数据绑定,您可以配置插件,如下所示:

...
<configuration>
  <sourceRoot>target/generated/src/main/java</sourceRoot>
  <wsdlOptions>
    <wsdlOption>
      <wsdl>${basedir}/src/main/resources/wsdl/myService.wsdl</wsdl>
      <extraargs>
        <extraarg>-databinding</extraarg>
        <extraarg>jibx</extraarg>
      </extraargs>
    </wsdlOption>
  </wsdlOptions>
</configuration>
...

指定绑定文件

要指定一个或多个 JAX-WS 绑定文件的位置,您可以添加 bindingFiles 元素作为 wsdlOption的子项,例如:

...
<configuration>
  <wsdlOptions>
    <wsdlOption>
      <wsdl>${basedir}/src/main/resources/wsdl/myService.wsdl</wsdl>
      <bindingFiles>
        <bindingFile>${basedir}/src/main/resources/wsdl/async_binding.xml</bindingFile>
      </bindingFiles>
    </wsdlOption>
  </wsdlOptions>
</configuration>
...

为特定的 WSDL 服务生成代码

要指定生成代码的 WSDL 服务的名称,您可以将 serviceName 元素添加为 wsdlOption 的子项(默认值是,在 WSDL 文档中为每个服务生成代码:

...
<configuration>
  <wsdlOptions>
    <wsdlOption>
      <wsdl>${basedir}/src/main/resources/wsdl/myService.wsdl</wsdl>
      <serviceName>MyWSDLService</serviceName>
    </wsdlOption>
  </wsdlOptions>
</configuration>
...

为多个 WSDL 文件生成代码

要为多个 WSDL 文件生成代码,只需为 WSDL 文件插入额外的 wsdlOption 元素。如果要指定适用于所有 WSDL 文件的一些常用选项,请将 common 选项放在 defaultOptions 元素中,如下所示:

<configuration>
  <defaultOptions>
      <bindingFiles>
          <bindingFile>${basedir}/src/main/jaxb/bindings.xml</bindingFile>
      </bindingFiles>
      <noAddressBinding>true</noAddressBinding>
  </defaultOptions>
  <wsdlOptions>
      <wsdlOption>
          <wsdl>${basedir}/src/main/resources/wsdl/myService.wsdl</wsdl>
          <serviceName>MyWSDLService</serviceName>
      </wsdlOption>
      <wsdlOption>
          <wsdl>${basedir}/src/main/resources/wsdl/myOtherService.wsdl</wsdl>
          <serviceName>MyOtherWSDLService</serviceName>
      </wsdlOption>
  </wsdlOptions>
</configuration>

也可以使用通配符匹配指定多个 WSDL 文件。在这种情况下,使用 wsdlRoot 元素指定包含 WSDL 文件的目录,然后使用 include 元素选择所需的 WSDL 文件,它支持使用 * 字符进行通配符。例如,要从 src/main/resources/wsdl root 目录中选择以 Service.wsdl 结尾的所有 WSDL 文件,您可以配置插件,如下所示:

<configuration>
  <defaultOptions>
      <bindingFiles>
          <bindingFile>${basedir}/src/main/jaxb/bindings.xml</bindingFile>
      </bindingFiles>
      <noAddressBinding>true</noAddressBinding>
  </defaultOptions>
  <wsdlRoot>${basedir}/src/main/resources/wsdl</wsdlRoot>
  <includes>
      <include>*Service.wsdl</include>
  </includes>
</configuration>

从 Maven 存储库下载 WSDL

要直接从 Maven 存储库下载 WSDL 文件,请添加 wsdlArtifact 元素作为 wsdlOption 元素的子项,并指定 Maven 工件的协调,如下所示:

...
<configuration>
  <wsdlOptions>
    <wsdlOption>
      <wsdlArtifact>
        <groupId>org.apache.pizza</groupId>
        <artifactId>PizzaService</artifactId>
        <version>1.0.0</version>
      </wsdlArtifact>
    </wsdlOption>
  </wsdlOptions>
</configuration>
...

encoding

(需要 JAXB 2.2) 来指定用于生成的 Java 文件的字符编码(Charset),添加 编码 元素作为 配置元素 的子级,如下所示:

...
<configuration>
  <wsdlOptions>
    <wsdlOption>
      <wsdl>${basedir}/src/main/resources/wsdl/myService.wsdl</wsdl>
    </wsdlOption>
  </wsdlOptions>
  <encoding>UTF-8</encoding>
</configuration>
...

对一个单独的进程进行分叉

您可以通过添加 fork 元素作为配置元素的子项,将 codegen 插件配置为生成代码的单独 JVM。fork 元素可设置为以下值之一:

once
派生一个新 JVM,以处理 codegen 插件配置中指定的所有 WSDL 文件。
always
派生一个新 JVM,以处理 codegen 插件配置中指定的每个 WSDL 文件。
false
(默认) 禁用分叉。

如果 codegen 插件配置为对一个独立的 JVM(即 fork 选项被设置为非错误值)进行分叉,您可以通过 additionalJvmArgs 元素为 fork 的 JVM 指定额外的 JVM 参数。例如,以下片段将 codegen 插件配置为 fork 一个 JVM,它限制为只从本地文件系统访问 XML 模式(通过设置 javax.xml.accessExternalSchema 系统属性):

...
<configuration>
  <wsdlOptions>
    <wsdlOption>
      <wsdl>${basedir}/src/main/resources/wsdl/myService.wsdl</wsdl>
    </wsdlOption>
  </wsdlOptions>
  <fork>once</fork>
  <additionalJvmArgs>-Djavax.xml.accessExternalSchema=jar:file,file</additionalJvmArgs>
</configuration>
...

选项参考

下表描述了用于管理代码生成过程的选项。

选项解释

-fe|-frontend frontend

指定代码生成器使用的前端。可能的值有 jaxwsjaxws21cxfjaxws21 frontend 用于生成 JAX-WS 2.1 兼容代码。cxf frontend(可以选择性地使用 jaxws frontend)为 Service 类提供额外的构造器。通过此构造器,您可以方便地指定用于配置该服务的总线实例。默认为 jaxws

-db|-databinding databinding

指定代码生成器使用的数据绑定。可能的值有: jaxbxmlbeanssdosdo-staticsdo-dynamic)和 jibx。默认为 jaxb

-wv wsdlVersion

指定工具预期的 WSDL 版本。默认为 1.1[a]

-p wsdlNamespace=PackageName

指定用于生成代码的零次或多个软件包名称。(可选)将 WSDL 命名空间指定到软件包名称映射。

-b bindingName

指定一个或多个 JAXB 绑定文件。为每个绑定文件使用单独的 -b 标志。

-sn serviceName

指定要为其生成代码的 WSDL 服务的名称。默认值是在 WSDL 文档中为每个服务生成代码。

-reserveClass classname

-autoNameResolution 一起使用时,为 wsdl-to-java 定义在生成类时使用的 wsdl-to-java 的类名称。这个选项多次用于多个类。

-catalog catalogUrl

指定用于解析导入的 schema 和 WSDL 文档的 XML 目录的 URL。

-d 输出目录

指定将生成的代码文件写入的目录。

-compile

编译生成的 Java 文件。

-classdir complile-class-dir

指定将编译类文件写入的目录。

-clientjar jar-file-name

生成包含所有客户端类和 WSDL 的 JAR 文件。指定这个选项时指定的 wsdlLocation 无法正常工作。

-client

为客户端主线生成起始点代码。

-server

为服务器主线生成起始点代码。

-impl

为实现对象生成起始点代码。

-all

生成所有起始点代码:类型、服务代理、服务接口、服务器主线、客户端主线、实施对象和 Ant build.xml 文件。

-ant

生成 Ant build.xml 文件。

-autoNameResolution

自动解决命名冲突,无需使用绑定自定义。

-defaultValues=DefaultValueProvider

指示工具为生成的客户端和生成的实施生成默认值。另外,您还可以提供用于生成默认值的类的名称。默认情况下使用 RandomValueProvider 类。

-nexclude schema-namespace=java-packagename

在生成代码时,忽略指定的 WSDL 架构命名空间。这个选项可多次指定。另外,还可指定排除命名空间中描述的类型使用的 Java 软件包名称。

-exsh (true/false)

启用或禁用扩展 soap 标头消息绑定的处理。默认为 false。

-noTypes

关闭生成类型。

-DNS (true/false)

启用或禁用默认命名空间软件包名称映射的加载。默认为 true。

-Dex (true/false)

启用或禁用默认排除命名空间映射的加载。默认为 true。

-xjcargs

指定在使用 JAXB 数据绑定时要直接传递到 XJC 的以逗号分隔的参数列表。要获取所有可能的 XJC 参数的列表,请使用 -xjc-X

-noAddressBinding

指示 工具使用 Apache CXF 专有 WS-Addressing 类型,而不是与 JAX-WS 2.1 兼容的映射。

-validate [=all|basic|none]

指示 工具在尝试生成任何代码前验证 WSDL 文档。

-keep

指示 工具不会覆盖任何现有的文件。

-wsdlLocation wsdlLocation

指定 @WebService 注释的 wsdlLocation 属性的值。

-v

显示工具的版本号。

-verbose|-V

在代码生成过程中显示注释。

-quiet

在代码生成过程中禁止评论。

-allowElementReferences[=true], -aer[=true]

如果为 true,则忽略在 JAX-WS 2.2 规范第 2.3.1.2(v)部分中提供的规则,不允许在使用 wrapper 风格的映射时引用元素。默认为 false

-asyncMethods[=method1,method2,…​]

随后生成的 Java 类方法列表,以允许客户端异步调用;类似于在 JAX-WS 绑定文件中 启用AsyncMapping

-bareMethods[=method1,method2,…​]

随后生成的 Java 类方法列表具有 wrapper 风格(请参阅以下),类似于 JAX-WS 绑定文件中的 enableWrapperStyle

-mimeMethods[=method1,method2,…​]

随后生成的 Java 类方法列表以启用 mime:content 映射,类似于在 JAX-WS 绑定文件中 启用MIMEContent

-faultSerialVersionUID fault-serialVersionUID

如何生成错误异常的问题。可能的值有:NONE、TIMESTAMPFQCN 或特定数字。默认为 NONE

-encoding encoding

指定生成 Java 代码时要使用的 Charset 编码。

-exceptionSuper

wsdl:fault 元素生成的用于错误 Bean 的超类(默认为 java.lang.Exception)。

-seiSuper interfaceName

为生成的 SEI 接口指定基本接口。例如,此选项可用于将 Java 7 AutoCloseable 接口添加为超级接口。

-mark-generated

@Generated 注释添加到生成的类。

[a] 目前,Apache CXF 仅为代码生成器提供 WSDL 1.1 支持。