JAXB (XJC) Imported Schemas and XML Catalogs

XML schema has a power mechanism called "import".  Import allows one XML schema to reference elements and types from another XML schema.  This means you could define types to represent commonly used information once and import these types into other XML schemas. Like any powerful tool, the import mechanism also has the ability to inflict pain.  In this post I'll demonstrate how to leverage an XML catalog to eliminate the pain when using JAXB's XJC tool to generate classes from an XML schema with imports.

XML Schemas

The following XML schemas will be used for this post.  The imported schemas (address.xsd and phone-number.xsd) are in a subdirectory called "imports" relative to customer.xsd.

customer.xsd (Root XML Schema)

This is the root XML schema that we will be generating our Java classes from.  This XML schema contains two import statement:

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema
    targetNamespace="http://www.example.com/customer"
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    xmlns="http://www.example.com/customer"
    xmlns:add="http://www.example.com/address"
    xmlns:phn="http://www.example.com/phone-number"
    elementFormDefault="qualified">

    <xs:import
        schemaLocation="http://www.example.com/address/address.xsd"
        namespace="http://www.example.com/address"/>

    <xs:import
        namespace="http://www.example.com/phone-number"/>

    <xs:element name="customer">
        <xs:complexType>
            <xs:sequence>
                <xs:element name="name" type="xs:string"/>
                <xs:element ref="add:address"/>
                <xs:element ref="phn:phone-number"
                    minOccurs="0" maxOccurs="unbounded"/>
            </xs:sequence>
        </xs:complexType>
    </xs:element>

</xs:schema>

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema
    targetNamespace="http://www.example.com/customer"
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    xmlns="http://www.example.com/customer"
    xmlns:add="http://www.example.com/address"
    xmlns:phn="http://www.example.com/phone-number"
    elementFormDefault="qualified">

    <xs:import
        schemaLocation="http://www.example.com/address/address.xsd"
        namespace="http://www.example.com/address"/>

    <xs:import
        namespace="http://www.example.com/phone-number"/>

    <xs:element name="customer">
        <xs:complexType>
            <xs:sequence>
                <xs:element name="name" type="xs:string"/>
                <xs:element ref="add:address"/>
                <xs:element ref="phn:phone-number"
                    minOccurs="0" maxOccurs="unbounded"/>
            </xs:sequence>
        </xs:complexType>
    </xs:element>

</xs:schema>

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    targetNamespace="http://www.example.com/phone-number"
    xmlns="http://www.example.com/phone-number"
    elementFormDefault="qualified">

    <xs:element name="phone-number">
        <xs:complexType>
            <xs:simpleContent>
                <xs:extension base="xs:string">
                    <xs:attribute name="type" type="xs:string"/>
                </xs:extension>
            </xs:simpleContent>
        </xs:complexType>
    </xs:element>

</xs:schema>

The XJC tool can be used to generate Java classes from an XML schema. In this example I have customer.xsd on my local file system

xjc -d out customer.xsd

Below are the error messages that I receive from making the above XJC call.  One error we see is that it could not find the schema at "http://www.example.com/address/address.xsd" which is expected as I stated earlier that I haven't hosted that XML schema yet.  Another error we see is that "phn:phone-number" can not be resolved to an element definition, this is expected too since we did not specify a schema location.

parsing a schema...
[WARNING] schema_reference.4: Failed to read schema document 'http://www.example.com/address/address.xsd', because 1) could not find the document; 2) the document could not be read; 3) the root element of the document is not <xsd:schema>.
  line 12 of file:/C:/Program%20Files/Java/jdk1.6.0_20/bin/customer.xsd

[ERROR] src-resolve: Cannot resolve the name 'add:address' to a(n) 'element declaration' component.
  line 21 of file:/C:/Program%20Files/Java/jdk1.6.0_20/bin/customer.xsd

[ERROR] src-resolve: Cannot resolve the name 'phn:phone-number' to a(n) 'element declaration' component.
  line 23 of file:/C:/Program%20Files/Java/jdk1.6.0_20/bin/customer.xsd

Failed to parse a schema.

We can solve the problems we are encountering through the use of an XML catalog.  An XML catalog will allow us to specify real locations for our imported XML schemas.  The XJC tool supports several different XML Catalog formats:  TR9401, XCatalog, OASIS XML Catalog.  

The XML catalog formats have system and public mappings.  The system mappings are useful for when the import contains a system ID, and the public mappings must be used when the import does not contain a system ID.

The following import can be used with a system mapping

<xs:import
    schemaLocation="http://www.example.com/address/address.xsd"
    namespace="http://www.example.com/address"/>

This import requires a public mapping based on the namespace URI:

<xs:import
    namespace="http://www.example.com/phone-number"/>

Below are a couple of examples based on the XML schemas from this post:

-- Match address.xsd by URL --
SYSTEM "http://www.example.com/address/address.xsd" "imports/address.xsd"

-- Match phone-number.xsd by namespace URI --
PUBLIC "http://www.example.com/phone-number" "imports/phone-number.xsd"

OASIS XML Catalog Format

<!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">

    <system
        systemId="http://www.example.com/address/address.xsd"
        uri="imports/address.xsd"/>
    <public
        publicId="http://www.example.com/phone-number"
        uri="imports/phone-number.xsd"/>

</catalog>

xjc -d out -catalog catalog.cat customer.xsd

From http://blog.bdoughan.com/2011/10/jaxb-xjc-imported-schemas-and-xml.html