Generate the Model classes from WSDL

quarkus-cxf extension supports generating Java classes from WSDL during Quarkus code generation phase.

Code examples

The code snippets shown in this section come from the client integration test in the source tree of Quarkus CXF. You may want to check it as an executable example.

You need to set up a couple of things for CXF code generation to work:

  • Have io.quarkiverse.cxf:quarkus-cxf dependency in your project

  • For Maven projects, the generate-code goal needs to be present in the configuration of quarkus-maven-plugin:

    pom.xml
                <plugin>
                    <groupId>io.quarkus</groupId>
                    <artifactId>quarkus-maven-plugin</artifactId>
                    <executions>
                        <execution>
                            <goals>
                                <goal>build</goal>
                                <goal>generate-code</goal>
                            </goals>
                        </execution>
                    </executions>
                </plugin>
  • For Gradle projects no additional configurarion of io.quarkus plugin is needed

  • Put your WSDL files under src/main/resources or src/test/resources or any subdirectory thereof.

  • Your WSDL file names must end with .wsdl

  • Set quarkus.cxf.codegen.wsdl2java.includes configuration property to a pattern matching the WSDL files you wish to process. If you want to process all WSDL files under src/main/resources/wsdl or src/test/resources/wsdl, set it as follows:

    application.properties
    quarkus.cxf.codegen.wsdl2java.includes = wsdl/*.wsdl

This will generate Java classes in target/generated-sources/wsdl2java or target/generated-test-sources/wsdl2java directory. They will be automatically picked by the compiler plugin there. Hence we are free to refer to them from our application or test code.

Note that quarkus-cxf code generation uses the wsdl2Java utility from CXF under the hood. wsdl2Java is called separately for each WSDL file selected by includes and excludes.

Passing custom parameters to wsdl2java is possible through various quarkus.cxf.codegen.wsdl2java.* configuration parameters.

If you need different parameters for each WSDL file, you may want to define a separate named parameter set for each one of them. Here is an example:

application.properties
# Parameters for foo.wsdl
quarkus.cxf.codegen.wsdl2java.foo-params.includes = wsdl/foo.wsdl
quarkus.cxf.codegen.wsdl2java.foo-params.wsdl-location = wsdl/foo.wsdl
# Parameters for bar.wsdl
quarkus.cxf.codegen.wsdl2java.bar-params.includes = wsdl/bar.wsdl
quarkus.cxf.codegen.wsdl2java.bar-params.wsdl-location = wsdl/bar.wsdl
quarkus.cxf.codegen.wsdl2java.bar-params.xjc = ts

Customize the Java model classes

As we mentioned earlier, the io.quarkiverse.cxf:quarkus-cxf extension embeds the wsdl2java tool and it is invoked during Quarkus code generation phase.

The way how wsdl2java shapes the Java model classes can be customized in two main ways:

JAXB and/or JAXWS binding files

JAXB and/or JAXWS Binding files are two flavors of the same: they both exist for the purpose of enhancing or adjusting some sort of a contract before the Java classes are generated out of it.

While JAXB Binding files are applied to XML Schema (XSD) documents, the JAXWS Binding files are applied to WSDL documents.

Both JAXB and JAXWS Binding files are passed to wsdl2java via quarkus.cxf.codegen.wsdl2java.bindings or quarkus.cxf.codegen.wsdl2java."named-parameter-sets".bindings options.

JAXB Binding files

If you ask, why XML Schemas matter in the context of wsdl2java then the answer is that WSDLs either embed inline XML Schemas or they incude external XML Schema documents. You may customize those using JAXB Binding files.

JAXB Binding file names typically end with .xjb but .xml will work too.

The format of JAXB Binding files is governed by the https://jakarta.ee/xml/ns/jaxb namespace and Jakarta XML Binding 3.0 Schema.

Here is an example that instructs the JAXB schema binding compiler (XJC) to render each XML attribute having type xs:dateTime as java.time.OffsetDateTime:

global-jaxb-bindings.xml
<?xml version="1.0"?>
<jaxb:bindings
        version="3.0"
        xmlns:jaxb="https://jakarta.ee/xml/ns/jaxb"
        xmlns:xs="http://www.w3.org/2001/XMLSchema">
    <jaxb:globalBindings>
        <jaxb:javaType
            name="java.time.OffsetDateTime"
            xmlType="xs:dateTime"
            parseMethod="java.time.OffsetDateTime.parse"
            printMethod="java.lang.String.valueOf"/>
    </jaxb:globalBindings>
</jaxb:bindings>

JAXWS Binding files

The format of JAXWS Binding files is governed by the https://jakarta.ee/xml/ns/jaxws namespace and XML Schema for the Jakarta XML Web Services WSDL customization descriptor.

Check the example in the Asynchronous client guide.

XJC plugins

wsdl2java delegates the process of generating Java classes from XML Schemas to JAXB schema binding compiler (XJC). XJC has a pluggable architecture and a number of plugins exist that can customize the rendering in various ways.

To use those plugins you need to: