1. Overview
The goal of this document is to provide reference documentation for developers utilizing the CXF Codegen Gradle plugin.
1.1. What is CXF Codegen
CXF Codegen is a Gradle plugin port of the Maven plugin. The Gradle plugin offers an API similar to the one offered by the Maven plugin. The API is not a 1:1 port and leans heavily on Gradle idioms and conventions.
1.2. Supported Gradle Versions
The CXF Codegen Gradle plugin supports the following Gradle versions:
-
5.5.1
-
5.6.4
-
6.0.1
-
6.1.1
-
6.2.2
-
6.3
-
6.4.1
-
6.5.1
-
6.6.1
-
6.7.1
-
6.8.3
-
6.9
-
7.0.2
-
7.1.1
-
7.2
-
7.3.3
-
7.4.2
The plugin is fully tested against the above versions to ensure compatibility. View the source of the functional tests for more details.
Gradle’s configuration cache is supported when using Gradle 6.6 or later.
All examples are written for and are tested for Gradle 7.4.2. Depending on your Gradle version, you may need to adapt the example to a syntax that is compatible with your Gradle version. |
2. Plugin Configuration
2.1. Dependency Configuration
The plugin creates a configuration named cxfCodegen
which can be used to add additional dependencies to the classpath
for code generation.
Out-of-the-box, the following dependencies are added (v3.5.2):
-
org.apache.cxf:cxf-core
-
org.apache.cxf:cxf-tools-common
-
org.apache.cxf:cxf-tools-wsdlto-core
-
org.apache.cxf:cxf-tools-wsdlto-databinding-jaxb
-
org.apache.cxf:cxf-tools-wsdlto-frontend-jaxws
-
org.apache.cxf:cxf-tools-wsdlto-frontend-javascript
-
org.apache.cxf:cxf-rt-frontend-simple
is excluded.
-
These are the same dependencies defined in the Maven plugin’s POM.
2.1.1. Managing Dependency Versions
Standard Gradle dependency management can be used to control the included dependency versions.
For example, a resolve rule can be used to downgrade the CXF dependencies:
You will need to ensure the version of CXF dependencies you specify is compatible with the options used. Failure to do so will result in an error during code generation. |
Groovy
configurations.cxfCodegen {
resolutionStrategy.eachDependency {
if (requested.group == "org.apache.cxf") {
useVersion "3.2.0"
because "3.3.0 breaks the build"
}
}
}
Kotlin
configurations.cxfCodegen {
resolutionStrategy.eachDependency {
if (requested.group == "org.apache.cxf") {
useVersion("3.2.0")
because("3.3.0 breaks the build")
}
}
}
3. Generating Java Sources
To generate Java sources from a WSDL, define task of type Wsdl2Java
and configure the toolOptions
. Note that the task is a subclass of JavaExec
.
Additionally, when defining a task:
-
For each task, the generated Java source (the task output) is added to the
main
source sets.-
This can be disabled when creating the task via
addToMainSourceSet.set(false)
-
-
All
Wsdl2Java
task types are aggregated to a single task namedwsdl2java
.
3.1. Minimal Usage
The minimum requirement for generating Java is a single WSDL file.
Groovy
import io.mateo.cxf.codegen.wsdl2java.Wsdl2Java
// ...
tasks.register("example", Wsdl2Java) { (1)
toolOptions { (2)
wsdl.set(file("path/to/example.wsdl")) (3)
}
allJvmArgs = ["-Duser.language=fr", "-Duser.country=CA"] (4)
}
Kotlin
import io.mateo.cxf.codegen.wsdl2java.Wsdl2Java
// ...
tasks.register("example", Wsdl2Java::class) { (1)
toolOptions { (2)
wsdl.set(file("path/to/example.wsdl")) (3)
}
allJvmArgs = listOf("-Duser.language=fr", "-Duser.country=CA") (4)
}
1 | Creates a task named example of type Wsdl2Java . |
2 | Use the toolOptions to configure all available options for code generation. |
3 | Configure the WSDL to use for code generation. |
4 | Configure a custom locale. Remember that Wsdl2Java is a subclass of JavaExec . All configurations you can do to JavaExec can be done here as well. |
The WSDL property is annotated with @InputFile therefore any changes to the WSDL will cause the task to be out-of-date. If your WSDL imports a schema (XSD) or something else, consider adding that file to the
task inputs as well so that it can be considered during Gradle’s up-to-date checks.
|
3.2. Options
There are quite a few options that can be specified that alter the generated Java. These are identical to ones offered by the Maven plugin.
Groovy
tasks.register("example", Wsdl2Java) {
toolOptions {
wsdl.set(file("path/to/example.wsdl"))
outputDir.set(file("$buildDir/generated-java")) (1)
markGenerated.set(true) (2)
packageNames.set(["com.example", "com.foo.bar"]) (3)
asyncMethods.set(["foo", "bar"]) (4)
}
}
Kotlin
tasks.register("example", Wsdl2Java::class) {
toolOptions {
wsdl.set(file("path/to/example.wsdl"))
outputDir.set(file("$buildDir/generated-java")) (1)
markGenerated.set(true) (2)
packageNames.set(listOf("com.example", "com.foo.bar")) (3)
asyncMethods.set(listOf("foo", "bar")) (4)
}
}
1 | Change the directory the generated code files are written to. |
2 | Adds the @Generated annotation to classes. |
3 | Package names to use for the generated code. |
4 | Specifies subsequently generated Java class methods to allow for client-side asynchronous calls, similar to enableAsyncMapping in a JAX-WS binding file. |
There are more options available than what is shown above. View the method summary section in the Javadoc
for Wsdl2JavaOptions
for more details.
3.3. Default Options
You may want to configure options that apply to all tasks. This is easily accomplished using native Gradle functionality.
First define some tasks:
Groovy
tasks.register("first", Wsdl2Java) {
toolOptions {
wsdl.set(file("path/to/first.wsdl"))
}
}
tasks.register("second", Wsdl2Java) {
toolOptions {
wsdl.set(file("path/to/second.wsdl"))
}
}
tasks.register("third", Wsdl2Java) {
toolOptions {
wsdl.set(file("path/to/third.wsdl"))
}
}
Kotlin
tasks {
register("first", Wsdl2Java::class) {
toolOptions {
wsdl.set(file("path/to/first.wsdl"))
}
}
register("second", Wsdl2Java::class) {
toolOptions {
wsdl.set(file("path/to/second.wsdl"))
}
}
register("third", Wsdl2Java::class) {
toolOptions {
wsdl.set(file("path/to/third.wsdl"))
}
}
}
Then configure each one using the configureEach
method on the container:
Groovy
tasks.withType(Wsdl2Java).configureEach {
toolOptions {
markGenerated.set(true)
}
}
Kotlin
tasks.withType(Wsdl2Java::class).configureEach {
toolOptions {
markGenerated.set(true)
}
}
3.4. Java 9+
If you are using Java 9+, you can use the cxfCodegen
configuration to add back the Java EE modules that were deprecated
in Java 9 and eventually removed in Java 11. Refer to JEP 320 for more details.
Groovy
dependencies {
cxfCodegen "jakarta.xml.ws:jakarta.xml.ws-api:2.3.3" (1)
cxfCodegen "jakarta.annotation:jakarta.annotation-api:1.3.5" (2)
}
Kotlin
dependencies {
cxfCodegen("jakarta.xml.ws:jakarta.xml.ws-api:2.3.3") (1)
cxfCodegen("jakarta.annotation:jakarta.annotation-api:1.3.5") (2)
}
1 | Replacement for javax.xml.ws.Service |
2 | Replacement for javax.annotation.Resource |
The above is just an example. Depending on your usage, there may be more dependencies required.
3.5. Logging
Without any additional configuration, when executing any of the created tasks, the following lines will be printed to the console:
SLF4J: Failed to load class "org.slf4j.impl.StaticLoggerBinder".
SLF4J: Defaulting to no-operation (NOP) logger implementation
SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further details.
To enable logging for Apache CXF, include a SLF4J binding and logging framework. A Logback example is shown below.
Groovy
dependencies {
cxfCodegen "ch.qos.logback:logback-classic:1.2.10"
}
Kotlin
dependencies {
cxfCodegen("ch.qos.logback:logback-classic:1.2.10")
}
With the above, you should now start to see a plethora of logs as shown below.
22:14:05.833 [main] DEBUG org.apache.cxf.common.logging.LogUtils - Using org.apache.cxf.common.logging.Slf4jLogger for logging.
22:14:05.967 [main] DEBUG org.apache.cxf.tools.wsdlto.core.PluginLoader - Loading plugin jar:file:~/.gradle/caches/modules-2/files-2.1/org.apache.cxf/cxf-tools-wsdlto-databinding-jaxb/3.4.0/.../cxf-tools-wsdlto-databinding-jaxb-3.4.0.jar!/META-INF/tools-plugin.xml
22:14:06.043 [main] DEBUG org.apache.cxf.tools.wsdlto.core.PluginLoader - Found 1 databindings in <jaxb> plugin.
22:14:06.043 [main] DEBUG org.apache.cxf.tools.wsdlto.core.PluginLoader - Loading <jaxb> databinding from <jaxb> plugin.
22:14:06.043 [main] DEBUG org.apache.cxf.tools.wsdlto.core.PluginLoader - Loading plugin jar:file:~/.gradle/caches/modules-2/files-2.1/org.apache.cxf/cxf-tools-wsdlto-frontend-jaxws/3.4.0/.../cxf-tools-wsdlto-frontend-jaxws-3.4.0.jar!/META-INF/tools-plugin.xml
---- snip
22:14:06.043 [main] DEBUG org.apache.velocity - Initializing Velocity, Calling init()...
22:14:06.043 [main] DEBUG org.apache.velocity - Starting Apache Velocity v2.2
22:14:06.043 [main] DEBUG org.apache.velocity - Default Properties resource: org/apache/velocity/runtime/defaults/velocity.properties
3.5.1. Disable Logs
Logs from Apache CXF can be disabled by specifying a null
logger for each Wsdl2JavaTask
task type as JVM argument.
Groovy
tasks.withType(Wsdl2Java).configureEach {
jvmArgs = ["-Dorg.apache.cxf.Logger=null"]
}
Kotlin
tasks.withType(Wsdl2Java::class).configureEach {
jvmArgs = listOf("-Dorg.apache.cxf.Logger=null")
}
Logs from Apache Velocity unfortunately cannot be disabled. However, you can specify a log configuration that essentially overrides all logging levels. For example, an empty Logback configuration will silence all logs:
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
</configuration>
Groovy
tasks.withType(Wsdl2Java).configureEach {
jvmArgs = ["-Dlogback.configurationFile=logback.xml"]
}
Kotlin
tasks.withType(Wsdl2Java::class).configureEach {
jvmArgs = listOf("-Dlogback.configurationFile=logback.xml")
}