User Guide

The user guide is currently being ported, this is work in progress.

<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|Sample Purchase Order Project]] for example.

The plugin has a large number of configuration options. Please see the [plugin documentation](TODO) or the [[cheat sheet|Configuration Cheat Sheet]] for a complete reference.

h1. 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:

```xml
<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>

h2. Resource entries

Since the 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.

h2. 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>

h2. 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>

h1. 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.

h1. 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.
packageLevelAnnotations - If false, suppresses generation of package level annotations (package-info.java). Default is true. Since 0.9.0.
noFileHeader - If true, suppresses generation of a file header with timestamp. Default is false. Since 0.9.0.
enableIntrospection - If true, enables correct generation of Boolean getters/setters to enable Bean Introspection apis. Since 0.9.0.
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.
encoding - Encoding for the generated sources, defaults to ${project.build.sourceEncoding}.
locale - Locale used during generation, for instance en, de, fr etc. This will for instance influence the language of the generated JavaDoc comments.

h2. 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.

h1. 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.

h1. Controlling XML security

Since 0.9.0.

disableXmlSecurity - If 'true', disables XML security features when parsing XML documents. Default is true.
accessExternalSchema - Restrict access to the protocols specified for external reference set by the schemaLocation attribute, import and include element. Value: a list of protocols separated by comma. A protocol is the scheme portion of a URI, or in the case of the JAR protocol, jar plus the scheme portion separated by colon. The keyword all grants permission to all protocols. Default is all.
accessExternalDTD - Restricts access to external DTDs and external Entity References to the protocols specified. Value: a list of protocols separated by comma. A protocol is the scheme portion of a URI, or in the case of the JAR protocol, jar plus the scheme portion separated by colon. The keyword "all" grants permission to all protocols. Default is all.

h1. 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).

h1. 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.

h2. 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).

h2. 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: org.jvnet.jaxb2.maven2 maven-jaxb20-plugin generate

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

h1. 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.

Example: true -XtoString -Xequals -XhashCode -Xcopyable org.jvnet.jaxb2_commons jaxb2-basics See the [sample JAXB2 plugins project|sample JAXB2 plugins project] for example.

h1. 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|http://jaxb.java.net/guide/Fixing_broken_references_in_schema.html] 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: src/main/resources/catalog.cat

Loading catalog from a Maven artifact resource
com.acme.foo bar ${project.version} catalog.cat

The catalog file looks as follows: PUBLIC "http://example.org/A" "others/schema_a.xsd" The URI [http://example.org/A|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:

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

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|sample catalog project] for example.

h1. Separate schema compilation

If you're compiling large sets of schemas (like the [OGC Schemas|http://ogc.java.net]) 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|http://weblogs.java.net/blog/kohsuke/archive/2006/09/separate_compil.html].

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 ...> ... ... com.acme.foo a-schema 1.0 ... test org.jvnet.jaxb2.maven2 maven-jaxb2-plugin true true ...

Alternatively you can specify episode artifacts explicitly: <project ...> ... ... com.acme.foo a-schema 1.0 ... test org.jvnet.jaxb2.maven2 maven-jaxb2-plugin true com.acme.foo a-schema ...

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|sample episode project] for example.

h1. 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.

h1. Miscellaneous Problems

h2. 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

User Guide

Table of Contents

About the plugin

Distribution

Basic usage

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

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!