About the plugin

JAXB2 Maven2 plugin which allows you to generate code with JAXB RI in your Maven builds. The plugin participates in the generate-code phase and produces code of the schema-derived classes (plus maybe some other resources) out of the XML Schemas, DTDs and so on.

Basic usage

Since version 0.7.4 maven-jaxb2-plugin is distributed via the central Maven repository.

Simply add the generate execution goal to the build:

<build>
	<plugins>
		<plugin>
			<groupId>org.jvnet.jaxb2.maven2</groupId>
			<artifactId>maven-jaxb2-plugin</artifactId>
			<executions>
				<execution>
					<goals>
						<goal>generate</goal>
					</goals>
				</execution>
			</executions>
		</plugin>
	</plugins>
</build>

To compile the generated sources, set at 1.5 (or higher) version in source and target of the maven-compiler-plugin:

<build>
	<plugins>
		...
		<plugin>
			<inherited>true</inherited>
			<groupId>org.apache.maven.plugins</groupId>
			<artifactId>maven-compiler-plugin</artifactId>
			<configuration>
				<source>1.5</source>
				<target>1.5</target>
			</configuration>
		</plugin>
	</plugins>
</build>

See the [sample purchase order project] for example.

The plugin has a large number of configuration options. Please see the plugin documentation for a complete reference.

Specifying schemas and bindings to compile

• schemaDirectory - Specifies the schema directory, src/main/resources by default.
• schemaIncludes - Specifies file patterns to include as schemas. By default all *.xsd files will be included.
• schemaExcludes - Specifies file patterns of schemas to exclude. By default, nothing is excluded.
• schemas - Specifies schemas as filesets, URLs or Maven artifact resources (see resource entries.
• bindingDirectory - Specifies the binding directory, defaults to the schema directory.
• bindingIncludes - Specifies file patterns to include as bindings. By default all *.xjb files will be included.
• bindingExcludes - Specifies file patterns of bindings to exclude. By default, nothing is excluded.
• bindings - Specifies bindings as filesets, URLs or Maven artifact resources (see resource entries.
• schemaLanguage - Type of input schema language. One of: DTD, XMLSCHEMA, RELAXNG, RELAXNG_COMPACT, WSDL, AUTODETECT. If unspecified, it is assumed AUTODETECT.

Below is an example of a non-standard directory layout configuration:

<configuration>
	<!-- Changes the default schema directory -->
	<schemaDirectory>src/main/schema</schemaDirectory>
	<schemaIncludes>
		<include>one/*/*.xsd</include>
	</schemaIncludes>			
	<schemaExcludes>
		<exclude>one/two/*.xsd</exclude>
	</schemaExcludes>			
	<bindingDirectory>src/main/binding</bindingDirectory>
	<bindingIncludes>
		<include>one/*/*.xjb</include>
	</bindingIncludes>			
	<bindingExcludes>
		<exclude>one/two/*.xjb</exclude>
	</bindingExcludes>			
</configuration>

Resource entries

Since version 0.8.0 you can specify schema and binding resources via resource entries in configuration elements schemas and bindings:

<configuration>                                                                                         
	<forceRegenerate>true</forceRegenerate>                                                         
	<schemas>                                                                                       
		<schema>                                                                                
			<fileset>                                                                       
				<!-- Defaults to schemaDirectory -->                                    
				<directory>${basedir}/src/main/schemas</directory>                                 
				<!-- Defaults to schemaIncludes -->                                     
				<includes>                                                              
					<include>*.*</include>                                          
				</includes>                                                             
				<!-- Defaults to schemaExcludes -->                                     
				<excludes>                                                              
					<exclude>*.xs</exclude>                                         
				</excludes>                                                             
			</fileset>                                                                      
			<url>http://schemas.opengis.net/wms/1.3.0/capabilities_1_3_0.xsd</url>          
			<dependencyResource>                                                            
				<groupId>org.jvnet.jaxb2.maven2</groupId>                               
				<artifactId>maven-jaxb2-plugin-tests-po</artifactId>                    
				<!-- Can be defined in project dependencies or dependency management -->
				<version>${project.version}</version>                                   
				<resource>purchaseorder.xsd</resource>                                  
			</dependencyResource>                                                           
		</schema>                                                                               
	</schemas>                                                                                      
</configuration>                                                                                        

The same works for bindings with fileset elements defaulting to bindingDirectory, bindingIncludes and bindingExcludes.

Compiling a schema from an URL

<configuration>                                                                                         
	<forceRegenerate>true</forceRegenerate>                                                         
	<schemas>                                                                                       
		<schema>
			<url>http://schemas.opengis.net/wms/1.3.0/capabilities_1_3_0.xsd</url>
		</schema>                                                                               
	</schemas>                                                                                      
</configuration>                                                                                        

Compiling a schema from a Maven artifact

<configuration>                                                                                         
	<forceRegenerate>true</forceRegenerate>                                                         
	<schemas>                                                                                       
		<schema>
			<dependencyResource>                                                            
				<groupId>org.jvnet.jaxb2.maven2</groupId>                               
				<artifactId>maven-jaxb2-plugin-tests-po</artifactId>                    
				<!-- Can be defined in project dependencies or dependency management -->
				<version>${project.version}</version>                                   
				<resource>purchaseorder.xsd</resource>                                  
			</dependencyResource>                                                           
		</schema>                                                                               
	</schemas>                                                                                      
</configuration>                                                                                        

Compiling DTDs

If you want to compile DTD, change the schemaLanguage to DTD and set the appropriate schemaIncludes:

<configuration>
  <schemaLanguage>DTD</schemaLanguage>
  <schemaIncludes>
    <include>*.dtd</include>
  </schemaIncludes>
</configuration>

See the [sample DTD project] for example.

Controlling the output

• generateDirectory - Target directory for the generated code, target/generated-sources/xjc by default.
• generatePackage - The generated classes will all be placed under this Java package (XJC's -p option), unless otherwise specified in the schemas. If left unspecified, the package will be derived from the schemas only.
• writeCode - If false, the plugin will not write the generated code to disk, true by default.
• readOnly - If true, the generated Java source files are set as read-only (XJC's -readOnly option). Default is false.
• removeOldOutput - If true, the generateDirectory will be deleted before the XJC binding compiler recompiles the source files. Default is false.
• cleanPackageDirectories - If true (default), package directories will be cleaned before the XJC binding compiler generates the source files.
• forceRegenerate - If true, no up-to-date check is performed and the XJC always re-generates the sources. Otherwise schemas will only be recompiled if anything has changed (this is the default behavior).
• markGenerated - If true, marks generated classes using a @Generated annotation - i.e. turns on XJC -mark-generated option. Default is false.

Adding target directory as Maven source directory

By default, target directory (target/generated-sources/xjc) will be added as a compile source root. If your project also generates the episode file, it will be added as a project resource.

In some cases you may need to generate test source instead of main sources - so you'll need to add target directory as a test compile source root. Or you may need to override or avoid automatic source root addition for some other reason. You can accomplish this using the following configuration options:

• addCompileSourceRoot - If set to true (default), adds target directory as a compile source root of this Maven project.
• addTestCompileSourceRoot - If set to true, adds target directory as a test compile source root of this Maven project. Default value is false.

Controlling the extension and validation modes

• extension - If true, the XJC binding compiler will run in the extension mode (XJC's -extension option). Otherwise, it will run in the strict conformance mode (this is the default). Please note that you must enable the extension mode if you use vendor extensions in your bindings.
• strict - If true (default), XJC will perform strict validation of the input schema. If strict is set to false XJC will be run with -nv, this disables strict validation of schemas.

Setting the debug options

• debug - If true, the XJC compiler is set to debug mode (XJC's -debug option).
• verbose - If true, the plugin and the XJC compiler are both set to verbose mode (XJC's -verbose option). It is automatically set to true when Maven is run in debug mode (mvn's -X option).

Using a specific version of JAXB 2.x specification

There are differences between JAXB 2.0, 2.1 and 2.2. By default, maven-jaxb2-plugin uses the latest available version of the latest available specification.

Do not forget to use the appropriate version of jaxb-impl.

If you need to stick to a specific version of the JAXB specification, there are two ways to accomplish this.

Configuring the JAXB specification version

You can specify the version of the JAXB specification using the following configuration option:

• specVersion - Version of the JAXB specification (ex. 2.0, 2.1 or 2.2).

Using the version-specific plugin

Alternatively you may also use maven-jaxb20-plugin, maven-jaxb21-plugin or maven-jaxb22-plugin instead of maven-jaxb2-plugin to make your dependency on JAXB specification version more explicit:

			<plugin>
				<groupId>org.jvnet.jaxb2.maven2</groupId>
				<artifactId>maven-jaxb20-plugin</artifactId>
				<executions>
					<execution>
						<goals>
							<goal>generate</goal>
						</goals>
					</execution>
				</executions>
			</plugin>

All these plugins have identical configuration options (except that specVersion is ignored in maven-jaxb2x-plugin}}s, it only makes sense in {{maven-jaxb2-plugin).

Using custom JAXB2 plugins

• plugins/plugin - Configures artifacts of the custom JAXB2 plugins you want to use.
• args/arg - A list of extra XJC's command-line arguments (items must include the dash "-"). Use this argument to enable the JAXB2 plugin you want to use.</dd>

Example:

<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 --></version>
		</plugin>
	</plugins>
</configuration>

See the [sample JAXB2 plugins project] for example.

Using catalogs

Sometimes a schema may refer to another schema document without indicating where the schema file can be found:

<xs:import namespace="http://www.w3.org/1999/xlink"/>

Another case is when the provided schema location is somewhere in the internet but you have you local copy of that schema which you'd like to use for compilation.

Both cases are resolved using the catalog mechanism. See this section in the JAXB guide.

Maven2 JAXB plugin allows you to provide a catalog file using the catalog configuration parameter.

• catalog - Specify the catalog file to resolve external entity references (XJC's -catalog option).
• catalogs - Specifies catalogs as filesets, URLs or Maven artifact resources (see resource entries). Since 0.8.1.

Examples:

<configuration>
  <catalog>src/main/resources/catalog.cat</catalog>
</configuration>

Loading catalog from a Maven artifact resource

<configuration>
	<catalogs>
		<catalog>
			<dependencyResource>                                                            
				<groupId>com.acme.foo</groupId>
				<artifactId>bar</artifactId>
				<!-- Version can be omitted if artifact is already
				configured in dependencies or dependency management. -->
				<version>${project.version}</version>
				<resource>catalog.cat</resource>
			</dependencyResource>
		</catalog>
	</catalogs>
</configuration>

The catalog file looks as follows:

PUBLIC "http://example.org/A" "others/schema_a.xsd"

The URI http://example.org/A is the namespace of the schema to be resolved, others/schema_a.xsd is the local schema
location (relative to the catalog file).

XML catalogs also work:

<!DOCTYPE catalog
	PUBLIC "-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN" "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd">
<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog"
         prefer="public">

	<rewriteSystem systemIdStartString="http://example.org/schemas" rewritePrefix="."/>
</catalog>

You can also reference resources inside Maven artifacts:

REWRITE_SYSTEM "https://maven-jaxb2-plugin.dev.java.net/svn/maven-jaxb2-plugin/trunk/tests/episodes/a/src/main/resources/a.xsd" "maven:org.jvnet.jaxb2.maven2:maven-jaxb2-plugin-tests-episodes-a!/a.xsd"

The URI syntax for Maven artifact resources is as follows:

maven:groupId:artifactId:type:classifier:version!/resource/path/in/jar/schema.xsd

• groupId is required
• artifactId is required
• type is optional, defaults to jar
• classifier is optional, default to null
• version is optional if artifact is defined in project dependencies or dependency management
• !/ is used as resource delimiter

A few examples:

• maven:org.jvnet.jaxb2.maven2:maven-jaxb2-plugin-tests-episodes-a!/a.xsd
• maven:org.jvnet.jaxb2.maven2:maven-jaxb2-plugin-tests-episodes-a:jar!/a.xsd - equivalent to above
• maven:org.jvnet.jaxb2.maven2:maven-jaxb2-plugin-tests-episodes-a:jar:!/a.xsd - equivalent to above
• maven:org.jvnet.jaxb2.maven2:maven-jaxb2-plugin-tests-episodes-a:jar::!/a.xsd - equivalent to above
• maven:org.jvnet.jaxb2.maven2:maven-jaxb2-plugin-tests-episodes-a:::!/a.xsd - equivalent to above
• maven:org.jvnet.jaxb2.maven2:maven-jaxb2-plugin-tests-episodes-a:::0.8.1!/a.xsd - using a specific version, type is defaulted to jar
• maven:org.jvnet.jaxb2.maven2:maven-jaxb2-plugin-tests-episodes-a::sources!/a.xsd -
  getting a.xsd from the sources JAR

See the [sample catalog project] for example.

Separate schema compilation

If you're compiling large sets of schemas (like the OGC Schemas) you may probably want to compile the
schemas separately. For instance, if you have two schemas A and B (where B imports A), you may
want to compile them into two artifacts A.jar and B.jar such that:

• Classes relevant to A reside in the A.jar artifact.
• Classes relevant to B (and only those classes) reside in the B.jar artifact.
• The A.jar artifact is the dependency of the B.jar artifact.

This task is called the separate or episodic compilation. Kohsuke described it in his blog.

Maven2 JAXB2 plugin supports episodic compilation via the following configuration parameters:

• episode - If true, the episode file (describing mapping of elements and types to classes for the compiled schema) will be generated.
• episodeFile - Target location of the episode file. By default it is target/generated-sources/xjc/META-INF/sun-jaxb.episode so that the episode file will appear as META-INF/sun-jaxb.episode in the JAR - just as XJC wants it.
• episodes/episode - If you want to use existing artifacts as episodes for separate compilation, configure them as episodes/episode elements. It is assumed that episode artifacts contain an appropriate META-INF/sun-jaxb.episode resource.
• useDependenciesAsEpisodes - Use all of the compile-scope project dependencies as episode artifacts. It is assumed that episode artifacts contain an appropriate META-INF/sun-jaxb.episode resource. Default is false. (Since version 0.8.1).

For example, consider that we've built the A schema as com.acme.foo:a-schema:jar:1.0 artifact and want to use it as an episode when we compile the B schema. Here's how we configure it:

<project ...>
	...
	<dependencies>
		...
		<dependency>
			<groupId>com.acme.foo</groupId>
			<artifactId>a-schema</artifactId>
			<version>1.0</version>
		</dependency>
		...
	</dependencies>
	<build>
		<defaultGoal>test</defaultGoal>
		<plugins>
			<plugin>
				<groupId>org.jvnet.jaxb2.maven2</groupId>
				<artifactId>maven-jaxb2-plugin</artifactId>
				<configuration>
					<extension>true</extension>
					<useDependenciesAsEpisodes>true</useDependenciesAsEpisodes>
				</configuration>
			</plugin>
		</plugins>
	</build>
	...
</project>

Alternatively you can specify episode artifacts explicitly:

<project ...>
	...
	<dependencies>
		...
		<dependency>
			<groupId>com.acme.foo</groupId>
			<artifactId>a-schema</artifactId>
			<version>1.0</version>
		</dependency>
		...
	</dependencies>
	<build>
		<defaultGoal>test</defaultGoal>
		<plugins>
			<plugin>
				<groupId>org.jvnet.jaxb2.maven2</groupId>
				<artifactId>maven-jaxb2-plugin</artifactId>
				<configuration>
					<extension>true</extension>
					<episodes>
						<episode>
							<groupId>com.acme.foo</groupId>
							<artifactId>a-schema</artifactId>
							<!-- Version is not required if the artifact is
								configured as dependency -->
						</episode>
					</episodes>
				</configuration>
			</plugin>
		</plugins>
	</build>
	...
</project>

In this case JAXB will not generate classes for the imported A schema. The B.jar artifact will only contain classes relevant to the B schema.

Note that JAXB still needs to access BOTH A and B schemas during the compilation. You may use catalogs to provide alternative locations of the imported schemas.

See the [sample episode project] for example.

Integration with M2Eclipse

Since the version 0.8.1, maven-jaxb2-plugin provides "native" integration for M2Eclipse. That is, the plugin provides lifecycle mapping metadata and uses Plexus Build API to check if any relevant files were changes and to refresh the workspace after source code was generated. This should resolve the "plugin execution not covered by lifecycle configuration" problem.

This feature is supported in M2Eclipse since version 1.1.

Miscellaneous Problems

Target directory ignored by M2Eclipse if plugin is executed in generated-test-sources phase

Please see this issue.

The problem appears in Eclipse environments running M2Eclipse.

If maven-jaxb2-plugin is executed in the generate-test-sources phase, target directory is not considered by the M2Eclipse - therefore the project is missing target source folder (ex. target/generated-sources/xjc) in Eclipse.

This is not a bug. By default, M2Eclipse only executes the lifecycle only up to the process-resources phase. The generate-test-sources phase is coming after the process-resources phase and therefore is not executed. Accordingly, target directory is not added to the Maven project source directories.

To resolve, please change the following setting:

Window > Preferences > Maven > Goals to run when updating project configuration: > process-test-resources

Solving "Plugin execution not covered by lifecycle configuration" problem in Eclipse/M2Eclipse

There are following options:

• Ugrade to M2Eclipse 1.1 and maven-jaxb2-plugin 0.8.1 or higher
• Use one of the m2e connectors:
  • Window > Preferences > Maven > Discovery > Open Catalog > Find: jaxb2