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:

1. The first import includes a system ID specifying the hosted location of the imported XML schema.  JAXB's XJC tool can generate classes from a hosted XML schema (see Processing Atom Feeds with JAXB), but in this example the XML schemas are still under development and have not been hosted yet.
2. The second import does not include a system ID at all.  The XJC tool will not know where to find the imported XML 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>

imports/address.xsd (Imported Schema)

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

    <xs:element name="address">
        <xs:complexType>
            <xs:sequence>
                <xs:element name="street" type="xs:string"/>
                <xs:element name="street" type="xs:string"/>
            </xs:sequence>
        </xs:complexType>
    </xs:element>

</xs:schema>

imports/phone-number.xsd (Imported 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>

XJC - Generating Java Classes from an XML 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.

XML Catalog (catalog.cat)

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:

TR9401 Format

-- 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 - Specifying the Catalog File

The "-catalog" option is used to specify the catalog file when running the XJC command to generate Java classed from XML schemas.

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

Further Reading

If you enjoyed this post, then you may also be interested in:

• JAXB (XJC) and Nested Classes
• XML Schema to Java - Generating XmlAdapters 
• XML Schema to Java - XSD Choice
• JAXB and Choosing the List Implementation