E.2. cxf-codegen-plugin

Abstract

Generates JAX-WS compliant Java code from a WSDL document

Overview

Basic example

The following POM extract shows a simple example of how to configure the Maven cxf-codegen-plugin to process the myService.wsdl WSDL file:
<plugin>
  <groupId>org.apache.cxf</groupId>
  <artifactId>cxf-codegen-plugin</artifactId>
  <version>3.1.5.redhat-630187</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>

Basic configuration settings

In the preceding example, you can customize the following configuration settings
configuration/sourceRoot
Specifies the directory where the generated Java files will be stored. Default is target/generated-sources/cxf.
configuration/wsdlOptions/wsdlOption/wsdl
Specifies the location of the WSDL file.

Description

The wsdl2java task takes a WSDL document and generates fully annotated Java code from which to implement a service. The WSDL document must have a valid portType element, but it does not need to contain a binding element or a service element. Using the optional arguments you can customize the generated code.

WSDL options

At least one wsdlOptions element is required to configure the plug-in. The wsdlOptions element's wsdl child is required and specifies a WSDL document to be processed by the plug-in. In addition to the wsdl element, the wsdlOptions element can take a number of children that can customize how the WSDL document is processed.
Tip
More than one wsdlOptions element can be listed in the plug-in configuration. Each element configures a single WSDL document for processing.

Default options

The defaultOptions element is an optional element. It can be used to set options that are used across all of the specified WSDL documents.
Important
If an option is duplicated in the wsdlOptions element, the value in the wsdlOptions element takes precedent.

Specifying code generation options

To specify generic code generation options (corresponding to the switches supported by the Apache CXF wsdl2java command-line tool), you can add the extraargs element as a child of a wsdlOption element. For example, you can add the -impl option and the -verbose option as follows:
...
<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>
...
If a switch takes arguments, you can specify these using subsequent extraarg elements. For example, to specify the jibx data binding, you can configure the plug-in as follows:
...
<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>
...

Specifying binding files

To specify the location of one or more JAX-WS binding files, you can add the bindingFiles element as a child of wsdlOption—for example:
...
<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>
...

Generating code for a specific WSDL service

To specify the name of the WSDL service for which code is to be generated, you can add the serviceName element as a child of wsdlOption (the default behaviour is to generate code for every service in the WSDL document)—for example:
...
<configuration>
  <wsdlOptions>
    <wsdlOption>
      <wsdl>${basedir}/src/main/resources/wsdl/myService.wsdl</wsdl>
      <serviceName>MyWSDLService</serviceName>
    </wsdlOption>
  </wsdlOptions>
</configuration>
...

Generating code for multiple WSDL files

To generate code for multiple WSDL files, simply insert additional wsdlOption elements for the WSDL files. If you want to specify some common options that apply to all of the WSDL files, put the common options into the defaultOptions element as shown:
<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>
It is also possible to specify multiple WSDL files using wildcard matching. In this case, specify the directory containing the WSDL files using the wsdlRoot element and then select the required WSDL files using an include element, which supports wildcarding with the * character. For example, to select all of the WSDL files ending in Service.wsdl from the src/main/resources/wsdl root directory, you could configure the plug-in as follows:
<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>

Downloading WSDL from a Maven repository

To download a WSDL file directly from a Maven repository, add a wsdlArtifact element as a child of the wsdlOption element and specify the coordinates of the Maven artifact, as follows:
...
<configuration>
  <wsdlOptions>
    <wsdlOption>
      <wsdlArtifact>
        <groupId>org.apache.pizza</groupId>
        <artifactId>PizzaService</artifactId>
        <version>1.0.0</version>
      </wsdlArtifact>
    </wsdlOption>
  </wsdlOptions>
</configuration>
...

Encoding

(Requires JAXB 2.2) To specify the character encoding (Charset) used for the generated Java files, add an encoding element as a child of the configuration element, as follows:
...
<configuration>
  <wsdlOptions>
    <wsdlOption>
      <wsdl>${basedir}/src/main/resources/wsdl/myService.wsdl</wsdl>
    </wsdlOption>
  </wsdlOptions>
  <encoding>UTF-8</encoding>
</configuration>
...

Forking a separate process

You can configure the codegen plug-in to fork a separate JVM for code generation, by adding the fork element as a child of the configuration element. The fork element can be set to one of the following values:
once
Fork a single new JVM to process all of the WSDL files specified in the codegen plug-in's configuration.
always
Fork a new JVM to process each WSDL file specified in the codegen plug-in's configuration.
false
(Default) Disables forking.
If the codegen plug-in is configured to fork a separate JVM (that is, the fork option is set to a non-false value), you can specify additional JVM arguments to the forked JVM through the additionalJvmArgs element. For example, the following fragment configures the codegen plug-in to fork a single JVM, which is restricted to access XML schemas from the local file system only (by setting the javax.xml.accessExternalSchema system property):
...
<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>
...

Options reference

The options used to manage the code generation process are reviewed in the following table.
OptionInterpretation
-fe|-frontend frontendSpecifies the front end used by the code generator. Possible values are jaxws, jaxws21, and cxf. The jaxws21 frontend is used to generate JAX-WS 2.1 compliant code. The cxf frontend, which can optionally be used instead of the jaxws frontend, provides an extra constructor for Service classes. This constructor conveniently enables you to specify the Bus instance for configuring the service. Default is jaxws.
-db|-databinding databindingSpecifies the data binding used by the code generator. Possible values are: jaxb, xmlbeans, sdo (sdo-static and sdo-dynamic), and jibx. Default is jaxb.
-wv wsdlVersionSpecifies the WSDL version expected by the tool. Default is 1.1.[a]
-p [wsdlNamespace=]PackageNameSpecifies zero, or more, package names to use for the generated code. Optionally specifies the WSDL namespace to package name mapping.
-b bindingNameSpecifies one or more JAXWS or JAXB binding files. Use a separate -b flag for each binding file.
-sn serviceNameSpecifies the name of the WSDL service for which code is to be generated. The default is to generate code for every service in the WSDL document.
-reserveClass classname
Used with -autoNameResolution, defines a class names for wsdl-to-java not to use when generating classes. Use this option multiple times for multiple classes.
-catalog catalogUrlSpecifies the URL of an XML catalog to use for resolving imported schemas and WSDL documents.
-d output-directorySpecifies the directory into which the generated code files are written.
-compileCompiles generated Java files.
-classdir complile-class-dirSpecifies the directory into which the compiled class files are written.
-clientjar jar-file-name
Generates the JAR file that contains all the client classes and the WSDL. The specified wsdlLocation does not work when this option is specified.
-clientGenerates starting point code for a client mainline.
-serverGenerates starting point code for a server mainline.
-implGenerates starting point code for an implementation object.
-allGenerates all starting point code: types, service proxy, service interface, server mainline, client mainline, implementation object, and an Ant build.xml file.
-antGenerates the Ant build.xml file.
-autoNameResolution
Automatically resolve naming conflicts without requiring the use of binding customizations.
-defaultValues[=DefaultValueProvider]Instructs the tool to generate default values for the generated client and the generated implementation. Optionally, you can also supply the name of the class used to generate the default values. By default, the RandomValueProvider class is used.
-nexclude schema-namespace[=java-packagename]Ignore the specified WSDL schema namespace when generating code. This option may be specified multiple times. Also, optionally specifies the Java package name used by types described in the excluded namespace(s).
-exsh (true/false)Enables or disables processing of extended soap header message binding. Default is false.
-noTypesTurns off generating types.
-dns (true/false)Enables or disables the loading of the default namespace package name mapping. Default is true.
-dex (true/false)Enables or disables the loading of the default excludes namespace mapping. Default is true.
-xjcargsSpecifies a comma separated list of arguments to be passed to directly to the XJC when the JAXB data binding is being used. To get a list of all possible XJC arguments use the -xjc-X.
-noAddressBindingInstructs the tool to use the Apache CXF proprietary WS-Addressing type instead of the JAX-WS 2.1 compliant mapping.
-validate [=all|basic|none]Instructs the tool to validate the WSDL document before attempting to generate any code.
-keepInstructs the tool to not overwrite any existing files.
-wsdlLocation wsdlLocationSpecifies the value of the @WebService annotation's wsdlLocation property.
-vDisplays the version number for the tool.
-verbose|-VDisplays comments during the code generation process.
-quietSuppresses comments during the code generation process.
-allowElementReferences[=true], -aer[=true]
If true, disregards the rule given in section 2.3.1.2(v) of the JAX-WS 2.2 specification disallowing element references when using wrapper-style mapping. Default is false.
-asyncMethods[=method1,method2,...]
List of subsequently generated Java class methods to allow for client-side asynchronous calls; similar to enableAsyncMapping in a JAX-WS binding file.
-bareMethods[=method1,method2,...]
List of subsequently generated Java class methods to have wrapper style (see below), similar to enableWrapperStyle in JAX-WS binding file.
-mimeMethods[=method1,method2,...]
List of subsequently generated Java class methods to enable mime:content mapping, similar to enableMIMEContent in JAX-WS binding file.
-faultSerialVersionUID fault-serialVersionUID
How to generate suid of fault exceptions. Possible values are: NONE, TIMESTAMP, FQCN, or a specific number. Default is NONE.
-encoding encodingSpecifies the Charset encoding to use when generating Java code.
-exceptionSuper
Superclass for fault beans generated from wsdl:fault elements (defaults to java.lang.Exception).
-seiSuper interfaceNameSpecifies a base interface for the generated SEI interfaces. For example, this option can be used to add the Java 7 AutoCloseable interface as a super interface.
-mark-generated
Adds the @Generated annotation to the generated classes.
[a] Currently, Apache CXF only provides WSDL 1.1 support for the code generator.