User Guide

h1. About the plugin

JAXB2 Maven 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.

h1. 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: org.jvnet.jaxb2.maven2 maven-jaxb2-plugin generate To compile the generated sources, set at {{1.5}} (or higher) version in {{source}} and {{target}} of the {{maven-compiler-plugin}}: ... true org.apache.maven.plugins maven-compiler-plugin 1.5 1.5 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|http://static.highsource.org/mjiip/maven-jaxb2-plugin/generate-mojo.html] 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: src/main/schema one//.xsd one/two/.xsd src/main/binding one//.xjb one/two/.xjb h2. Resource entries

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




${basedir}/src/main/schemas


.



*.xs


http://schemas.opengis.net/wms/1.3.0/capabilities_1_3_0.xsd

org.jvnet.jaxb2.maven2
maven-jaxb2-plugin-tests-po
${project.version}
purchaseorder.xsd

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

h2. Compiling a schema from an URL
true

http://schemas.opengis.net/wms/1.3.0/capabilities_1_3_0.xsd

h2. Compiling a schema from a Maven artifact
true


org.jvnet.jaxb2.maven2
maven-jaxb2-plugin-tests-po
${project.version}
purchaseorder.xsd

h1. Compiling DTDs

If you want to compile DTD, change the {{schemaLanguage}} to {{DTD}} and set the appropriate {{schemaIncludes}}: DTD *.dtd See the [sample DTD project|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-plugin}}s, 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|http://java.net/jira/browse/MAVEN_JAXB2_PLUGIN-32].

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}}

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