Using Episodes

Using Episodes

Also known as 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].

JAXB2 Maven 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.
  • groupId - Group id of the episode artifact, required.
  • artifactId - Id of the episode artifact, required.
  • version - Version of the episode artifact. May be omitted. The plugin will then try to find the version using the dependencyManagement and dependencies of the project.
  • type - Type of the episode artifact, optional. Defaults to jar.
  • classifier - Classifier of the episode artifact, optional. Defaults to none.
• 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.

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:

```xml
<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 schema B.

See the [sample episode project|sample episode project] for example.

Note that JAXB still needs to access BOTH A and B schemas during the compilation. And you probably don't want to manually copy or duplicate schemas.

One way to solve this is to use the maven-dependency-plugin to unpack the required schema from schema-a.jar.

A much better way is to use a catalog to resolve schema-a.xsd into a resource inside the Maven artifact schema-a:

REWRITE_SYSTEM "http://www.acme.com/foo/a.xsd" "maven:com.acme.foo:a-schema!/"

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

A combination of episodes, catalogs and referencing resources in maven Artifacts allows fully modular schema compilation. Please see the Modular Schema Compilation guide.