jaxb > maven-jaxb2-plugin

출처: https://maven-jaxb2-plugin.dev.java.net/docs/guide.html

About the plugin

JAXB2 Maven2 plugin which allows you to generate code with JAXB RI in Maven builds. The plugin takes part 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.

Using the plugin

Basic usage

In order to use the plugin, you first have to make it available to your build. The plugin is distributed via the dev.java.net Maven2 repository, so add this to your pom.xml:

<repositories>
	<repository>
		<id>maven2-repository.dev.java.net</id>
		<name>Java.net Maven 2 Repository</name>
		<url>http://download.java.net/maven/2</url>
	</repository>
	<repository>
		<id>maven-repository.dev.java.net</id>
		<name>Java.net Maven 1 Repository (legacy)</name>
		<url>http://download.java.net/maven/1</url>
		<layout>legacy</layout>
	</repository>
</repositories>
<pluginRepositories>
	<pluginRepository>
		<id>maven2-repository.dev.java.net</id>
		<url>http://download.java.net/maven/2</url>
	</pluginRepository>
	<pluginRepository>
		<id>maven-repository.dev.java.net</id>
		<name>Java.net Maven 1 Repository (legacy)</name>
		<url>http://download.java.net/maven/1</url>
		<layout>legacy</layout>
	</pluginRepository>
</pluginRepositories>

When this is done, 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 1.5 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 PO project for example.

Configuring the plugin

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

Basic configuration options

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.

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.

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>

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 (default), the generateDirectory will be deleted before the XJC binding compiler recompiles 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).

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) and the com.sun.tools.xjc.Options.findServices property is set, to print any plugin instantiation messages.
It is automatically set to true when Maven is run in debug mode (mvn's -X 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 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:

<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>basic</artifactId>
			<version>0.2.GA</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 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).

catalogResolver

Specify the class name of the catalog resolver. This class must extend the com.sun.org.apache.xml.internal.resolver.tools.CatalogResolver class and provide a public no-arg constructor. For instance, if you want to resolve schemas from the classpath you may configure the org.jvnet.jaxb2.maven2.resolver.tools.ClasspathCatalogResolver class. See the episode sample project for example.

Example:

<configuration>
	<catalog>src/main/resources/catalog.cat</catalog>
	<catalogResolver>org.jvnet.jaxb2.maven2.resolver.tools.ClasspathCatalogResolver</catalogResolver>
</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 schemaDirectory).

Please note that if you want to load schemas from the classpath then they must be in the classpath. In order to achieve this you may need to add the artifact containing schemas to the plugins/plugin.

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.

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