Using Catalogs

Using catalogs

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

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

Another case is when the provided schema location is an absolute URL but you would like to use a local copy of this schema (which is highly recommended).

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

Both cases are resolved using the catalog mechanism. See this document for more information.

JAXB2 Maven Plugin allows you to provide a catalog file using the catalog or catalogs configuration parameters.

• catalog - Specify the catalog file to resolve external entity references (XJC's -catalog option).
• catalogs/catalog - Specifies catalogs as filesets, URLs or Maven artifact resources.
  • dependencyResource - Specifies a catalog from the Maven artifact.
    • groupId - Group id of the artifact, required.
    • artifactId - Artifact id of the artifact, required.
    • version - Version of the artifact. May be omitted. The plugin will then try to find the version using the dependencyManagement and dependencies of the project.
    • resource - Path of the resource within the artifact, for instance catalog.cat. Required. Do not include a leading /.
    • type - Type of the dependency, optional. Defaults to jar.
    • classifier - Classifier of the dependency, optional. Defaults to none.
  • url - Specifies the URL of the catalog to use.
  • fileset - Specifies a fileset of catalogs to use.
    • directory - Base directory of the fileset. Optional, defaults to schemaDirectory (see above).
    • includes/include - File patterns to include. Optional, defaults to *.cat (see above).
    • excludes/exclude - File patterns to exclude. Optional, by default nothing is excluded.

Examples of configuration

Using a local catalog file:

<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><!-- Version --></version>
				<resource>catalog.cat</resource>
			</dependencyResource>
		</catalog>
	</catalogs>
</configuration>

This will load the catalog from catalog.cat resource inside the bar artifact.

Examples of catalogs

The catalog can be defined as text (*.cat) or in the XML form (`*.xml).

Let's take at the text-based definition first:

PUBLIC "http://www.w3.org/1999/xlink" "w3c/1999/xlink.xsd"
REWRITE_SYSTEM "http://www.w3.org" "w3c"

The first PUBLIC definition resolves a certain namespace URI to a different URI - for instance, a local file. So the catalog above will allow to resolve the following import:

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

To the w3c/1999/xlink.xsd relative to the catalog file.

Due to the bug in the XJC this only works if schemaLocation is not specified. So, unfortunately the following combination does not work at the moment.

PUBLIC "http://www.w3.org/1999/xlink" "w3c/1999/xlink.xsd"

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

The second option is the rewriting of the system id. Consider the following definition:

REWRITE_SYSTEM "http://www.w3.org" "w3c"

It will rewrite all URIs starting with http://www.w3.org to start with w3c instead.

So the schema location http://www.w3.org/1999/xlink.xsd in the following import:

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

Will be turned into w3c/1999/xlink.xsd and finally resolved to a local file.

Catalogs may also be defined in the XML form:

<!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">
	<public publicId="http://www.w3.org/1999/xlink" uri="w3c/1999/xlink.xsd"/>
	<rewriteSystem systemIdStartString="http://www.w3.org/1999/xlink" rewritePrefix="w3c"/>
</catalog>

You can also reference resources inside Maven artifacts. For example, consider the following catalog definition:

REWRITE_SYSTEM "http://schemas.opengis.net" "maven:org.jvnet.ogc:ogc-schemas:jar::!/ogc"

This will rewrite an URI http://schemas.opengis.net/ows/2.0/owsAll.xsd to maven:org.jvnet.ogc:ogc-schemas:jar::!/ogc/ows/2.0/owsAll.xsd. This will reference the ogc/ows/2.0/owsAll.xsd resource in ogc-schemas JAR artifact. So, no need to unpack or extract schemas.

See the sample catalog project for example.