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

Gradle Version Support

To keep the plugin as simple as possible, there will not be any extensive version specific workarounds for older versions of Gradle or any Gradle version for that matter. Trivial or simple workarounds are fine.

However, the recommended minimum Gradle version is Gradle 6 (6.8 or later). This recommended minimum aligns with Spring Boot Gradle Plugin 2.6.3, but without the strict requirement.

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.

Incremental Build

The JavaExec supports up-to-date checks (aka incremental build). As mentioned above, Wsdl2Java is a subclass of JavaExec and as a result, also supports up-to-date checks.

However, depending on how your WSDLs are structured, you may encounter scenarios where tasks are out-of-date.

Additionally, when defining a task:

  1. For each task, the generated Java source (the task output) is added to the main source sets.

    1. This can be disabled when creating the task via addToMainSourceSet.set(false)

  2. All Wsdl2Java task types are aggregated to a single task named wsdl2java.

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:

logback.xml
<?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")
}