GlassFish - World's first Java EE 7 Application Server


Documentation | Reference | Configuration

Using Hyperjaxb3 in builds

Essentially, Hyperjaxb3 is a code generator. It provides a JAXB 2 plugin which participates in JAXB's code generation - and produces all necessary JPA annotations (as well as the supporting code, where necessary).

Apart from that, Hyperjaxb3 also provides utility code which will be used in the runtime.

So "using Hyperjaxb3" actually means:

  • Use Hyperjaxb3 JAXB 2 plugin during the code generation.
  • Use Hyperjaxb3 runtime libraries when compiling and running the generated code.

In the next sections we'll demonstrate how to use Hyperjaxb3 with Maven2 or Ant. We also provide "just add water" project samples - just put your schemas where they belong and you're ready to build!

However, this document does not cover the configuration of Hyperjaxb3 - please consult the configuration guide for the configuration reference.

JAXB 2.1 API under Java 1.6

If you'r using Java 1.6, you need to put the JAXB 2.1 API JAR into the lib/endorsed library of your JRE. This is either <JDK_HOME>/jre/lib/endorsed or <JRE_HOME>/lib/endorsed depending on if you're using full JDK or only JRE.

The reason is that Java 1.6 is bundled JAXB 2.0 API by default. Hyperjaxb3 is, however based on XJC 2.1.x and subsequently requires JAXB 2.1 API. In order to override system libraries (which contain JAXB 2.0 API) with the required JAXB 2.1 API, you must use the endorsed mechanism as shown above.

Here's a direct link to JAXB 2.1 API JAR.

Hyperjaxb3 with Maven2

Quickstart with a sample project

The easiest way to try out Hyperjaxb3 is to start with a sample project. Below are the stems to go:

  1. Download the project archive.
  2. Unpack it to the target folder.
  3. Put your schema files into the src/main/resources. Schemas should have the *.xsd extensions.
  4. Put your binding files into the same directory (src/main/resources). Binding files should have the *.xjb extensions.
  5. Put your sample XML (*.xml) into the src/test/samples directory. These samples will be used for the automatic roundtrip testing.
  6. Run mvn clean install.

When sample project is build, the following happens:

  • JAXB 2 together with Hyperjaxb3 plugin generate the code into the target/generated-sources/xjc. Hyperjaxb3 plugin additionally generates a roundtrip test
  • The code is compiled.
  • During the test phase, the roundtrip test class is used to test the generated annotations. The roundtrip test iterates over all the *.xml samples in src/test/samples and does the following:
    • The sample is unmarshalled using JAXB.
    • Unmarshalled object structure is saved into the test database using the JPA interfaces. (Don't worry about the database, sample project uses the embedded HSQLDB for testing - you don't need to install or configure any RDBMS to run it.)
    • Afterwards this structure is loaded back from the database via JPA.
    • The loaded structure is compared to the original and marshalled with JAXB. If samples are not corrupted after the database roundtrip, this more or less guarantees that generated annotations work fine.

You may also use the pom.xml from the sample project as an example.

Using Hyperjaxb3 in your Maven2 build

Configure repositories

Hyperjaxb3 and some of its dependencies are distributed via the dev.java.net's Maven1 and Maven2 repositories, so in order for Hyperjaxb3 to function in your Maven2 build, you have to include them into repositories and pluginRepositories. In case you intend to use Hibernate Entity Manager as a JPA implementation, you'll also need to configure the JBoss Maven2 repo as well:

<repositories>
	<repository>
		<id>maven2-repository.java.net</id>
		<url>http://download.java.net/maven/2</url>
	</repository>
	<repository>
		<id>maven-repository.java.net</id>
		<url>http://download.java.net/maven/1</url>
		<layout>legacy</layout>
	</repository>
	<repository>
		<id>maven2-repository.jboss.com</id>
		<url>http://repository.jboss.com/maven2</url>
	</repository>
	<repository>
		<id>jfrog.org</id>
		<url>http://www.jfrog.org/artifactory/plugins-releases@repo</url>
	</repository>
</repositories>
<pluginRepositories>
	<pluginRepository>
		<id>maven2-repository.java.net</id>
		<url>http://download.java.net/maven/2</url>
	</pluginRepository>
	<pluginRepository>
		<id>maven-repository.java.net</id>
		<url>http://download.java.net/maven/1</url>
		<layout>legacy</layout>
	</pluginRepository>
</pluginRepositories>

Configure dependencies

The code that you generate with Hyperjaxb3 naturally depends on the JAXB implementation as well as Hyperjaxb3 runtime libraries. So you have to add the appropriate artifacts to the dependencies:

<dependencies>
	<dependency>
		<groupId>com.sun.xml.bind</groupId>
		<artifactId>jaxb-impl</artifactId>
		<version>2.1.6</version>
	</dependency>
	<dependency>
		<groupId>org.jvnet.hyperjaxb3</groupId>
		<artifactId>hyperjaxb3-ejb-runtime</artifactId>
		<version>0.3</version>
	</dependency>
	<!-- ... -->
</dependencies>

Note that there are no dependencies on any specific EJB3 implementation. However, if you actually want to test the generated code with the roundtrip test, you'll need to include few more things - the roundtrip package, target EJB3 implementation libraries as well as JDBC driver of the target database. Assuming the "default" constellation of Hibernate3/HSQLDB, these dependencies look as follows:

<dependencies>
	<!-- ... -->

	<!-- Roundtrip package-->
	<dependency>
		<groupId>org.jvnet.hyperjaxb3</groupId>
		<artifactId>hyperjaxb3-ejb-roundtrip</artifactId>
		<version>0.3</version>
	</dependency>
	<!-- Hibernate -->
	<dependency>
		<groupId>org.hibernate</groupId>
		<artifactId>hibernate-entitymanager</artifactId>
		<version>3.3.1.ga</version>
		<scope>test</scope>
	</dependency>
	<!-- HSQLDB -->
	<dependency>
		<groupId>hsqldb</groupId>
		<artifactId>hsqldb</artifactId>
		<version>1.8.0.7</version>
		<scope>test</scope>
	</dependency>
</dependencies>

Add Hyperjaxb3 Maven2 plugin to the build section

Now you have to instruct Maven that Hyperjaxb3 will participate in code generation. The simplest way to achieve this is to use the Hyperjaxb3 Maven2 plugin. This plugin will initialize JAXB schema compiler (XJC), pass the appropriate configuration options, turn on the required JAXB plugins and so on. All you have to do is to add the Hyperjaxb3 Maven plugin into the build/plugins of your project POM:

<build>
	<defaultGoal>install</defaultGoal>
	<plugins>
		<plugin>
			<groupId>org.jvnet.hyperjaxb3</groupId>
			<artifactId>maven-hyperjaxb3-plugin</artifactId>
			<executions>
				<execution>
					<goals>
						<goal>generate</goal>
					</goals>
				</execution>
			</executions>
			<configuration>
				<extension>true</extension>
				<roundtripTestClassName>RoundtripTest</roundtripTestClassName>
			</configuration>
		</plugin>
		<plugin>
			<inherited>true</inherited>
			<artifactId>maven-compiler-plugin</artifactId>
			<configuration>
				<source>1.5</source>
				<target>1.5</target>
			</configuration>
		</plugin>
	</plugins>
</build>

The roundTripTestClassName element of the plugin configuration instructs Hyperjaxb3 to generate a roundtrip test class which will be executed during the test phase.

You may also have mentioned the reconfigured Maven compiler plugin. Since JAXB 2 produces Java 1.5 compatible code, we also need to set source and target compatibility levels of the Maven compiler to 1.5.

Using Hyperjaxb3 with a JAXB2 Maven2 plugin

If for some reason you do not want to use the Hyperjaxb3 Maven2 plugin, you can still invoke Hyperjaxb3 from the "standard" JAXB2 Maven2 plugin. In this case you will need to configure Hyperjaxb3 as JAXB2 plugin and pass the appropriate arguments to XJC.

<build>
	<defaultGoal>install</defaultGoal>
	<resources>
		<resource>
			<directory>src/main/resources</directory>
			<excludes>
				<exclude>**/*.java</exclude>
			</excludes>
		</resource>
		<resource>
			<directory>target/generated-sources/xjc</directory>
			<excludes>
				<exclude>**/*.java</exclude>
			</excludes>
		</resource>
	</resources>
	<plugins>
		<plugin>
			<groupId>org.jvnet.jaxb2.maven2</groupId>
			<artifactId>maven-jaxb2-plugin</artifactId>
			<version>0.5</version>
			<executions>
				<execution>
					<goals>
						<goal>generate</goal>
					</goals>
				</execution>
			</executions>
			<configuration>
				<extension>true</extension>
				<plugins>
					<plugin>
						<groupId>org.jvnet.hyperjaxb3</groupId>
						<artifactId>hyperjaxb3-ejb-plugin</artifactId>
						<version>0.3</version>
					</plugin>
				</plugins>
				<args>
					<arg>-Xequals</arg>
					<arg>-XhashCode</arg>
					<arg>-Xhyperjaxb3-ejb</arg>
				</args>
			</configuration>
		</plugin>
		<!-- ... -->
	</plugins>
</build>

Note the additional resources element where we add our target generation directory as a resource directory. This is required since Hyperjaxb3 also generates the META-INF/persistence.xml - and Maven must be instructed to add this file as a resource.

Another thing is that if you generate the roundtrip test class, you have to configure Maven's surefire plugin to run this test.

Actually, you can avoid all of the configuration overhead above if you simply use the Hyperjaxb3 Maven2 plugin.

Hyperjaxb3 with Ant

Using Hyperjaxb3 with Ant is a a bit more complex than with Maven since you have to take care of all the dependency management yourself. Still, it's not that hard - especially with the prepared sample project.

Quickstart with a sample project

To help Ant users get started with Hyperjaxb3, we've prepared a sample ant project. This is 1:1 clone of the Maven2 project with the difference that you have Ant's build.xml instead of Maven's pom.xml. This project is also in a pure "just add water" style:

  1. Download the project archive.
  2. Unpack it to the target folder. Note the lib folder which contains all the required libraries.
  3. Put your schema files into the src/main/resources. Schemas should have the *.xsd extensions.
  4. Put your binding files into the same directory (src/main/resources). Binding files should have the *.xjb extensions.
  5. Put your sample XML (*.xml) into the src/test/samples directory. These samples will be used for the automatic roundtrip testing.
  6. Run ant clean install.

The magic that happens after that is exactly the same as in the case of the Maven project sample.

You may also use the build.xml from the sample project as an example when you'll write your own builds.

Using Hyperjaxb3 in your Ant build

If you want to use Hyperjaxb3 to generate sources in the frame of an existing Ant build, you essentially need a correctly configured XJC task. Below is an example from the sample build.xml:

<taskdef name="xjc" classname="com.sun.tools.xjc.XJCTask">
	<classpath>
		<fileset dir="${basedir}/lib">
			<include name="*.jar"/>
		</fileset>
	</classpath>
</taskdef>
<mkdir dir="${basedir}/target/generated-sources/xjc"/>
<xjc destdir="${basedir}/target/generated-sources/xjc" extension="true">
	<arg line="
		-Xequals
		-XhashCode
		-XtoString
		-Xhyperjaxb3-ejb
		-Xhyperjaxb3-ejb-roundtripTestClassName=RoundtripTest"/>
	<binding dir="${basedir}/src/main/resources">
	 	<include name="**/*.xjb"/>
	</binding>
	<schema dir="${basedir}/src/main/resources">
	 	<include name="**/*.xsd"/>
	</schema>
</xjc>

The trickiest part here is configuring the right dependencies for the XJC task definition. If you miss some of the required dependencies, the task will fail. As the matter of fact, most of the problems Hyperjaxb users ever reported were due to the erroneous dependency configurations. Our best advice is to copy the dependencies from the sample project.

In any case, if you are getting "class not found" or "unrecognized parameter" error messages, include the -Dcom.sun.tools.xjc.Options.findServices=true option to your ANT_OPTS and run ant with -d -v. This will force XJC to output the diagnostic information and you may get some further clues on what's missing.