Team lead for the TopLink/EclipseLink JAXB & SDO implementations, and the Oracle representative on those specifications. Blaise is a DZone MVB and is not an employee of DZone and has posted 44 posts at DZone. You can read more from them at their website. View Full User Profile

JAXB (XJC) Imported Schemas and XML Catalogs

10.21.2011
| 13340 views |
  • submit to reddit

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

 

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

Published at DZone with permission of Blaise Doughan, author and DZone MVB.

(Note: Opinions expressed in this article and its replies are the opinions of their respective authors and not those of DZone, Inc.)

Tags:

Comments

Ali Yang replied on Tue, 2011/10/25 - 2:35am

Why using XML catalog, rather than using relative path.

Blaise Doughan replied on Tue, 2011/10/25 - 2:52pm in response to: Ali Yang

Hi Ali,

The XML schema may be provided by a third party and you won't have control over how the imports are specified.  This is the type of scenario where XML catalogs are useful.

-Blaise

Tim Drury replied on Thu, 2011/10/27 - 1:26pm

Relative paths won't work when your schemas are in multiple projects unless everyone checks the entire source tree out. Our schemas are spread across multiple maven modules and, therefore, are packaged into multiple jars. We wrote a ClasspathCatalogResolver and added it to our jaxb-maven-plugin which allows us to reference schemas embedded in dependency jars via the XML catalog.

Good article - there's not many practical examples out there for XML catalog.

Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.