Chapter 44. Maven Tooling Reference
44.1. Plug-in Setup
Abstract
before you can use the Apache CXF plug-ins, you must first add the proper dependencies and repositories to your POM.
Dependencies
You need to add the following dependencies to your project’s POM:
the JAX-WS frontend
<dependency> <groupId>org.apache.cxf</groupId> <artifactId>cxf-rt-frontend-jaxws</artifactId> <version>version</version> </dependency>
the HTTP transport
<dependency> <groupId>org.apache.cxf</groupId> <artifactId>cxf-rt-transports-http</artifactId> <version>version</version> </dependency>
the Undertow transport
<dependency> <groupId>org.apache.cxf</groupId> <artifactId>cxf-rt-transports-http-undertow</artifactId> <version>version</version> </dependency>
44.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.11.fuse-710022-redhat-00001</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.
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.
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.
Option | Interpretation |
---|---|
[option]`-fe | -frontend frontend` |
Specifies the front end used by the code generator. Possible values are | [option]`-db |
-databinding databinding` |
Specifies the data binding used by the code generator. Possible values are: |
|
Specifies the WSDL version expected by the tool. Default is |
| Specifies zero, or more, package names to use for the generated code. Optionally specifies the WSDL namespace to package name mapping. |
|
Specifies one or more JAXWS or JAXB binding files. Use a separate |
| Specifies 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. |
|
Used with |
| Specifies the URL of an XML catalog to use for resolving imported schemas and WSDL documents. |
| Specifies the directory into which the generated code files are written. |
| Compiles generated Java files. |
| Specifies the directory into which the compiled class files are written. |
|
Generates the JAR file that contains all the client classes and the WSDL. The specified |
| Generates starting point code for a client mainline. |
| Generates starting point code for a server mainline. |
| Generates starting point code for an implementation object. |
|
Generates all starting point code: types, service proxy, service interface, server mainline, client mainline, implementation object, and an Ant |
|
Generates the Ant |
| Automatically resolve naming conflicts without requiring the use of binding customizations. |
|
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 |
| 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). |
| Enables or disables processing of extended soap header message binding. Default is false. |
| Turns off generating types. |
| Enables or disables the loading of the default namespace package name mapping. Default is true. |
| Enables or disables the loading of the default excludes namespace mapping. Default is true. |
|
Specifies 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 |
| Instructs the tool to use the Apache CXF proprietary WS-Addressing type instead of the JAX-WS 2.1 compliant mapping. |
[option]`-validate [=all | basic |
none]` | Instructs the tool to validate the WSDL document before attempting to generate any code. |
| Instructs the tool to not overwrite any existing files. |
|
Specifies the value of the |
| Displays the version number for the tool. |
[option]`-verbose | -V` |
Displays comments during the code generation process. |
|
Suppresses comments during the code generation process. |
|
If |
|
List of subsequently generated Java class methods to allow for client-side asynchronous calls; similar to |
|
List of subsequently generated Java class methods to have wrapper style (see below), similar to |
|
List of subsequently generated Java class methods to enable mime:content mapping, similar to |
|
How to generate suid of fault exceptions. Possible values are: |
|
Specifies the Charset encoding to use when generating Java code. |
|
Superclass for fault beans generated from |
|
Specifies a base interface for the generated SEI interfaces. For example, this option can be used to add the Java 7 |
|
[a]
Currently, Apache CXF only provides WSDL 1.1 support for the code generator.
|
44.3. java2ws
Abstract
generates a WSDL document from Java code
Synopsis
<plugin> <groupId>org.apache.cxf</groupId> <artifactId>cxf-java2ws-plugin</artifactId> <version>version</version> <executions> <execution> <id>process-classes</id> <phase>process-classes</phase> <configuration> <className>className</className> <option>...</option> ... </configuration> <goals> <goal>java2ws</goal> </goals> </execution> </executions> </plugin>
Description
The java2ws
task takes a service endpoint implementation (SEI) and generates the support files used to implement a Web service. It can generate the following:
- a WSDL document
- the server code needed to deploy the service as a POJO
- client code for accessing the service
- wrapper and fault beans
Required configuration
The plug-in requires that the className
configuration element is present. The element’s value is the fully qualified name of the SEI to be processed.
Optional configuration
The configuration element’s listed in the following table can be used to fine tune the WSDL generation.
Element | Description |
---|---|
|
Specifies front end to use for processing the SEI and generating the support classes. |
|
Specifies the data binding used for processing the SEI and generating the support classes. The default when using the JAX-WS front end is |
|
Instructs the tool to generate a WSDL document when set to |
|
Instructs the tool to generate the wrapper bean and the fault beans when set to |
|
Instructs the tool to generate client code when set to |
|
Instructs the tool to generate server code when set to |
| Specifies the name of the generated WSDL file. |
| Specifies the classpath searched when processing the SEI. |
|
Specifies that the generated WSDL document is to include a SOAP 1.2 binding when set to |
| Specifies the target namespace to use in the generated WSDL file. |
|
Specifies the value of the generated |