Skip to content

Using JAXB2 Basics Plugins

Jump to bottom Edit New page
Laurent Schoelens edited this page Nov 13, 2023 · 3 revisions

Introduction

JAXB RI provides a schema compiler called XJC. One of the most important features of XJC is extensibility. You can implement your own XJC plugins to enhance, modify or customize the generated code. See this blog entry for a short introduction.

Using JAXB plugins in your builds

In order to use JAXB plugins in your builds, you essentially need to make two things:

  • Add the plugin library available into the XJC classpath (including all the required dependencies).
  • Turn on the extension option.
  • Activate (and possibly configure) the plugin by adding corresponding command-line arguments.

Following section describe how this can be done with Ant and Maven. Check Sample Projects for working examples.

Using JAXB plugins with Maven

In Maven builds, you have to list your JAXB plugin artifacts in configuration/plugins/plugin elements (you don't need to define the dependencies, Maven will take care of dependency resolution). JAXB plugins are activated and configured via the configuration/args/arg elements.

Configuration for targeting JAXB 2

Here is a sample for JAXB 2 (javax namespace) project

<project ...>
  ...
  <build>
    <plugins>
    ...
      <plugin>
        <groupId>org.jvnet.jaxb</groupId>
        <artifactId>jaxb-maven-plugin</artifactId>
        <executions>
          <execution>
            <goals>
              <goal>generate</goal>
            </goals>
          </execution>
        </executions>
        <configuration>
          <extension>true</extension>
          <args>
            <arg>-XtoString</arg>
            <arg>-Xequals</arg>
            <arg>-XhashCode</arg>
            <arg>-Xcopyable</arg>
          </args>
          <plugins>
            <plugin>
              <groupId>org.jvnet.jaxb</groupId>
              <artifactId>jaxb2-basics</artifactId>
              <version>[Align with jaxb-maven-plugin version]</version>
            </plugin>
          </plugins>
        </configuration>
      </plugin>
    </plugins>
  </build>
  ...
</project>

Adding jaxb2-basics-runtime dependency to your project (#jaxb2-basics-runtime)

Some of the JAXB2 Basics plugins (like hashCode, equals, toString, copyable, mergeable) have a runtime dependency to org.jvnet.jaxb:jaxb2-basics-runtime. This means you will need to include jaxb2-basics-runtime into the dependencies of your project:

<project>
  ...
  <dependencies>
    <dependency>
      <groupId>org.jvnet.jaxb</groupId>
      <artifactId>jaxb2-basics-runtime</artifactId>
      <version>...</version>
    </dependency>
    ...
  </dependencies>
  ...
</project>

Configuration for targeting JAXB 3 +

Here is a sample for JAXB 3+ (jakarta namespace) project

<project ...>
  ...
  <build>
    <plugins>
    ...
      <plugin>
        <groupId>org.jvnet.jaxb</groupId>
        <artifactId>jaxb-maven-plugin</artifactId>
        <executions>
          <execution>
            <goals>
              <goal>generate</goal>
            </goals>
          </execution>
        </executions>
        <configuration>
          <extension>true</extension>
          <args>
            <arg>-XtoString</arg>
            <arg>-Xequals</arg>
            <arg>-XhashCode</arg>
            <arg>-Xcopyable</arg>
          </args>
          <plugins>
            <plugin>
              <groupId>org.jvnet.jaxb</groupId>
              <artifactId>jaxb-plugins</artifactId>
              <version>[Align with jaxb-maven-plugin version]</version>
            </plugin>
          </plugins>
        </configuration>
      </plugin>
    </plugins>
  </build>
  ...
</project>

Adding jaxb-plugins-runtime dependency to your project

Some of the JAXB Basics plugins (like hashCode, equals, toString, copyable, mergeable) have a runtime dependency to org.jvnet.jaxb:jaxb-plugins-runtime. This means you will need to include jaxb-plugins-runtime into the dependencies of your project:

<project>
  ...
  <dependencies>
    <dependency>
      <groupId>org.jvnet.jaxb</groupId>
      <artifactId>jaxb-plugins-runtime</artifactId>
      <version>...</version>
    </dependency>
    ...
  </dependencies>
  ...
</project>

Using JAXB plugins with Ant

Assume your libraries (*.jar files) are placed in the lib directory. Below is the possible code generation target of an Ant build script:

<target name="generate-sources">
  <!-- Define the xjc task -->
  <taskdef name="xjc" classname="org.jvnet.jaxb2_commons.xjc.XJC2Task">
    <!-- XJC2 Task classpath -->
    <classpath>
      <fileset dir="${basedir}/lib">
        <include name="activation-*.jar"/>
        <include name="jaxb-api-*.jar"/>
        <include name="jaxb-impl-*.jar"/>
        <include name="jsr173_api-*.jar"/>
        <include name="stax-api-*.jar"/>

        <include name="jaxb-xjc-*.jar"/>
        <include name="jaxb2-basics-ant-*.jar"/>
      </fileset>
    </classpath>
  </taskdef>
  <mkdir dir="${basedir}/target/generated-sources/xjc"/>
  <!-- Generate the code -->
  <xjc destdir="${basedir}/target/generated-sources/xjc" extension="true">
    <arg line="
      -Xequals
      -XhashCode
      -XtoString
      -Xcopyable"/>
    <binding dir="${basedir}/src/main/resources">
       <include name="**/*.xjb"/>
    </binding>
    <schema dir="${basedir}/src/main/resources">
       <include name="**/*.xsd"/>
    </schema>
    <!-- Plugins -->
    <classpath>
      <fileset dir="${basedir}/lib">
        <!-- JAXB2 Basics library -->
        <include name="jaxb2-basics-*.jar"/>
        <!-- JAXB2 Basics library dependencies -->
        <include name="jaxb2-basics-runtime-*.jar"/>
        <include name="jaxb2-basics-tools-*.jar"/>
        <include name="commons-beanutils-*.jar"/>
        <include name="commons-lang-*.jar"/>
        <include name="commons-logging-*.jar"/>
      </fileset>
    </classpath>
  </xjc>
</target>

In Ant builds, plugin libraries are provided to XJC via the xjc/classpath element. Note that I had to list the plugin library (jaxb2-basics-*.jar) as well as all of its dependencies (jaxb2-basics-runtime-*.jar and so on).

Plugins are activated using the line attribute of the xjc/arg element:

<xjc destdir="${basedir}/target/generated-sources/xjc" extension="true">
  <arg line="
    -Xequals
    -XhashCode
    -XtoString
    -Xcopyable"/>
  <!-- ... -->
</xjc>

You can also use this element to provide configuration to the plugins that you use:

<arg line="
  -XtoString
  -XtoString-toStringBuilder=com.acme.foo.MyStringBuilder"/>

If using Ant with JAXB3, just adapt artifact names according the [migration guide]

Using JAXB plugins with CXF

Apache CXF is an open source services framework. CXF helps you build and develop services using frontend programming APIs, like JAX-WS and JAX-RS. These services can speak a variety of protocols such as SOAP, XML/HTTP, RESTful HTTP, or CORBA and work over a variety of transports such as HTTP, JMS or JBI.

One of the features of Apache CXF is WSDL-to-Java code generation with the cxf-codegen-plugin for Maven. You can use JAXB2 Basics plugins for cxf-codegen-plugin to augment your generated code - for instance to generate equals or hashCode methods, add missing collection setters, make your generated classes extend certain super-classes or implement certain interfaces and so on.

This guide describes how JAXB2 Basics plugins can be used with Apache CXF.

Integrating JAXB2 Basics plugins into your CXF builds

In brief, the steps to integrate JAXB2 Basics plugins into your CXF builds are as follows:

  • Add jaxb2-basics (for JAXB2) or jaxb-plugins (for JAXB3+) dependency to cxf-codegen-plugin
  • Turn on JAXB Basics plugins using extraargs
  • (If necessary) add jaxb2-basics-runtime (for JAXB2) or jaxb-plugins-runtime (for JAXB3+) dependency to your project
  • (If necessary} add your customizations to the binding files

Since version 0.6.0 JAXB2 Basics artifacts are distributed via the central Maven repository.

Adding jaxb2-basics dependency to cxf-codegen-plugin (JAXB 2)

In order to be able to use JAXB2 Basics plugins, you first have to make them available to CXF by adding the dependency to the cxf-codegen-plugin : Here is a fragment of pom.xml/build/plugins

<plugin>
  <groupId>org.apache.cxf</groupId>
  <artifactId>cxf-codegen-plugin</artifactId>
  <executions>
    <execution>
      <id>generate-sources</id>
      <phase>generate-sources</phase>
      <goals>
        <goal>wsdl2java</goal>
      </goals>
    </execution>
  </executions>
  <configuration>
    <wsdlOptions>
      <wsdlOption>
        <wsdl>${basedir}/src/main/wsdl/CustomerService.wsdl</wsdl>
        <bindingFiles>
          <bindingFile>${basedir}/src/main/wsdl/binding.xml</bindingFile>
          <bindingFile>${basedir}/src/main/wsdl/binding.xjb</bindingFile>
        </bindingFiles>
        <extraargs>
          <extraarg>-xjc-XhashCode</extraarg>
          <extraarg>-xjc-Xequals</extraarg>
        </extraargs>
      </wsdlOption>
    </wsdlOptions>
  </configuration>
  <dependencies>
    <dependency>
      <groupId>org.jvnet.jaxb</groupId>
      <artifactId>jaxb2-basics</artifactId>
      <version><!-- version --></version>
    </dependency>
  </dependencies>
</plugin>

Adding jaxb-plugins dependency to cxf-codegen-plugin (JAXB 3+)

In order to be able to use JAXB Basics plugins, you first have to make them available to CXF by adding the dependency to the cxf-codegen-plugin : Here is a fragment of pom.xml/build/plugins

<plugin>
  <groupId>org.apache.cxf</groupId>
  <artifactId>cxf-codegen-plugin</artifactId>
  <executions>
    <execution>
      <id>generate-sources</id>
      <phase>generate-sources</phase>
      <goals>
        <goal>wsdl2java</goal>
      </goals>
    </execution>
  </executions>
  <configuration>
    <wsdlOptions>
      <wsdlOption>
        <wsdl>${basedir}/src/main/wsdl/CustomerService.wsdl</wsdl>
        <bindingFiles>
          <bindingFile>${basedir}/src/main/wsdl/binding.xml</bindingFile>
          <bindingFile>${basedir}/src/main/wsdl/binding.xjb</bindingFile>
        </bindingFiles>
        <extraargs>
          <extraarg>-xjc-XhashCode</extraarg>
          <extraarg>-xjc-Xequals</extraarg>
        </extraargs>
      </wsdlOption>
    </wsdlOptions>
  </configuration>
  <dependencies>
    <dependency>
      <groupId>org.jvnet.jaxb</groupId>
      <artifactId>jaxb-plugins</artifactId>
      <version><!-- version --></version>
    </dependency>
  </dependencies>
</plugin>

Turning on the plugins

It's not enough to just add the dependency, you also need to explicitly activate the plugins you want to use. You can do this using the configuration/wsdlOptions/wsdlOption/extraargs/extraarg configuration element :

<wsdlOptions>
  <wsdlOption>
    <!-- ... -->
    <extraargs>
      <extraarg>-xjc-XhashCode</extraarg>
      <extraarg>-xjc-Xequals</extraarg>
    </extraargs>
  </wsdlOption>
</wsdlOptions>

Plugin options must be prefixed with -xjc. For instance for the Equals plugin (which is normally activated by the -Xequals option) you'll have an -xjc-Xequals extraarg element. Other examples would be:

  • -xjc-XhashCode
  • -xjc-XtoString
  • -xjc-Xcopyable
  • -xjc-Xmergeable
  • -xjc-Xinheritance
  • -xjc-Xsetters

And so on. Check the documentation of the JAXB2 Basics plugins for available options.

Adding jaxb2-basics-runtime dependency to your project

Like previously said, some of the JAXB2 Basics plugins generate code which depends on jaxb2-basics-runtime (JAXB 2) or jaxb-plugins-runtime (JAXB 3+) artifact. If you're using these plugins, make sure you add jaxb2-basics-runtime (JAXB 2) or jaxb-plugins-runtime (JAXB 3+) as dependency in dependencies section (see [above] for configuration).

Adding customizations to your binding files

In some cases you may need to add customizations. Here's an example :

<jaxb:bindings version="1.0"
  xmlns:jaxb="http://java.sun.com/xml/ns/jaxb"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"

  xmlns:inheritance="http://jaxb2-commons.dev.java.net/basic/inheritance"
  jaxb:extensionBindingPrefixes="inheritance">
  
  <jaxb:bindings schemaLocation="customer.xsd" node="/xsd:schema">
    <jaxb:bindings node="xsd:complexType[@name='customer']">
      <inheritance:implements>com.acme.foo.Actor</inheritance:implements>
    </jaxb:bindings>
  </jaxb:bindings>
</jaxb:bindings>
Add a custom footer
Clone this wiki locally