Using JAXB2 Basics Plugins

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.

<project ...>
	...
	<build>
		<plugins>
			...
			<plugin>
				<groupId>org.jvnet.jaxb2.maven2</groupId>
				<artifactId>maven-jaxb2-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.jaxb2_commons</groupId>
							<artifactId>jaxb2-basics</artifactId>
							<version>...</version>
						</plugin>
					</plugins>
				</configuration>
			</plugin>
		</plugins>
	</build>
	...
</project>

Some of the JAXB2 Basics plugins (like hashCode, equals, toString, copyable, mergeable) have a runtime dependency to org.jvnet.jaxb2_commons: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.jaxb2_commons</groupId>
			<artifactId>jaxb2-basics-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"/>