|  |  |  | License Codehaus OpenEJB OpenJMS OpenORB Tyrex

Old releases
General
Release 1.3
Release 1.3rc1
Release 1.2

Main
Home
About
Features
Download
Dependencies
Reference guide
Publications
JavaDoc
Maven 2 support
Maven 2 archetypes
DTD & Schemas
Recent HTML changes
News Archive
RSS news feed
Project Wiki

Development/Support
Mailing Lists
SVN/JIRA
Contributing
Support
Continuous builds
Prof. services

Related projects
Spring ORM support
Spring XML factories
WS frameworks

XML
XML

XML Code Generator
XML Code Generator

JDO
Introduction
First steps
Using JDO
JDO Config
Types
JDO Mapping
JDO FAQ
JDO Examples
JDO HOW-TOs
Tips & Tricks
Other Features
JDO sample JAR

Tools
Schema generator

Advanced JDO
Caching
OQL
Trans. & Locks
Design
KeyGen
Long Trans.
Nested Attrs.
Pooling Examples
LOBs
Best practice

DDL Generator
Using DDL Generator
Properties
Ant task
Type Mapping

More
The Examples
3rd Party Tools
JDO Tests
XML Tests
Configuration

About
License
User stories
Contributors
Marketplace
Status, Todo
Changelog
Library
Contact
Project Name

## How to fetch DTDs and XML Schemas from JAR files using Castor

Intended Audience
Prerequisites
What Dependencies?
An Introduction to the EntityResolver
The Castor DTDResolver
The Hitch: Defining the Correct IDs
References

## Intended Audience

Anyone who wants to retrieve DTDs and/or schemas from a local JAR file rather than the network.

This document helps people to get familiar with the basic concepts and discusses some implementation details.

## Prerequisites

None. All the required files reside in the Castor JAR, but what version of Castor you have will determine the public/system IDs are recognized by the `DTDResolver`.

## What Dependencies?

XML files often reference other files. The most common dependencies are either document type definitions (DTDs) from the `DOCTYPE` declaration or XML Schemas from the `schemaLocation` attribute.

Parsers usually only request schemas for validation, but more parsers are now requesting the DTDs whether validation is on or off. This allows the parser to resolve any entity references (i.e. `&amp;` or `&lt;`) that might be used in the document and defined in the DTD. This behavior can cause problems for machines with limited network connectivity, and in certain situations it is simply undesirable to have the parser going to the internet for each dependency.

## An Introduction to the EntityResolver

The `org.xml.sax.EntityResolver` interface is the key to retrieving XML dependencies from locations other than the defined system location. The interface has one method:

    public InputSource resolveEntity( String publicId, String systemId )
        throws SAXException, IOException

During parsing, before it attempts to retrieve any external files, the parser will call the above method, giving the public and/or system ID for the file. The implementing object can then either return an `InputSource` through which the parser can access the file, or `null` if the parser should fetch the file via normal channels.

## The Castor DTDResolver

In Castor, the `org.exolab.castor.util.DTDResolver` class provides an implementation of `EntityResolver` that is designed to fetch all the Castor dependencies from the Castor JAR file. This includes:

- | Mapping file DTD
- | Mapping file schema
- | JDOConf DTD
- | JDOConf schema
- | XML Schema Part 1: Structures DTD
- | XML Schema Part 1: Structures schema
- | XML Schema Part 2: Datatypes DTD

Castor automatically uses a `DTDResolver` when loading a mapping file, but must be told to use one during unmarshalling:

       public static void main( String[] args ) {
          String filename = args[0];

          try {
             Mapping mapping = new Mapping();

             // Castor will internally create and use a DTDResolver here
             mapping.loadMapping( "fooMap.xml" );

             Unmarshaller um1 = new Unmarshaller( mapping );

             // Castor needs to be told to use a DTDResolver here
             um1.setEntityResolver( new DTDResolver() );

             Foo foo = (foo)um1.unmarshal(new FileReader(filename));
          }
          catch( IOException e ) {
             e.printStackTrace();
          }
          catch( MappingException e ) {
             e.printStackTrace();
          }
       }

The `DTDResolver` can also wrap another `EntityResolver` to allow resolver chaining. `DTDResolver` calls the nested `EntityResolver` before attempting to resolve the ID(s) itself.

## The Hitch: Defining the Correct IDs

For the `DTDResolver` to retrieve the desired file from the Castor JAR, either the public ID or the system ID must match exactly. Below are lists of public and system IDs for the versions of Castor, but when in doubt, check the code of `DTDResolver`.

Since Castor v0.9.9.1 the following IDs are preferred:

Mapping DTD
  Public: `-//EXOLAB/Castor Mapping DTD Version 1.0//EN`
  System: `http://castor.org/mapping.dtd`
Mapping Schema
  Public: `-//EXOLAB/Castor Mapping Schema Version 1.0//EN`
  System: `http://castor.org/mapping.xsd`
JDO Configuration DTD
  Public: `-//EXOLAB/Castor JDO Configuration DTD Version 1.0//EN`
  System: `http://castor.org/jdo-conf.dtd`
JDO Configuration Schema
  Public: `-//EXOLAB/Castor JDO Configuration Schema Version 1.0//EN`
  System: `http://castor.org/jdo-conf.xsd`
XML Schema Part 1: Structures DTD
  Public: `-//W3C//DTD XMLSCHEMA 19991216//EN`
  System: `http://www.w3.org/TR/2000/WD-xmlschema-1-20000225/structures.dtd`
XML Schema Part 1: Structures Schema
  System: `http://www.w3.org/TR/2000/WD-xmlschema-1-20000225/structures.xsd`
XML Schema Part 2: Datatypes DTD
  System: `http://www.w3.org/TR/2000/WD-xmlschema-2-20000225/datatypes.dtd`

For older distributions, the following IDs have been accepted since Castor v0.9.5:

Mapping DTD
  Public: `-//EXOLAB/Castor Mapping DTD Version 1.0//EN`
  System: `http://castor.exolab.org/mapping.dtd`
Mapping Schema
  Public: `-//EXOLAB/Castor Mapping Schema Version 1.0//EN`
  System: `http://castor.exolab.org/mapping.xsd`
JDO Configuration DTD
  Public: `-//EXOLAB/Castor JDO Configuration DTD Version 1.0//EN`
  System: `http://castor.exolab.org/jdo-conf.dtd`
JDO Configuration Schema
  Public: `-//EXOLAB/Castor JDO Configuration Schema Version 1.0//EN`
  System: `http://castor.exolab.org/jdo-conf.xsd`
XML Schema Part 1: Structures DTD
  Public: `-//W3C//DTD XMLSCHEMA 19991216//EN`
  System: `http://www.w3.org/TR/2000/WD-xmlschema-1-20000225/structures.dtd`
XML Schema Part 1: Structures Schema
  System: `http://www.w3.org/TR/2000/WD-xmlschema-1-20000225/structures.xsd`
XML Schema Part 2: Datatypes DTD
  System: `http://www.w3.org/TR/2000/WD-xmlschema-2-20000225/datatypes.dtd`

## References

- | `EntityResolver` JavaDoc

<notice> Copyright © 1999-2005 ExoLab Group, Intalio Inc., and Contributors. All rights reserved. </notice>
<notice> Java, EJB, JDBC, JNDI, JTA, Sun, Sun Microsystems are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and in other countries. XML, XML Schema, XSLT and related standards are trademarks or registered trademarks of MIT, INRIA, Keio or others, and a product of the World Wide Web Consortium. All other product names mentioned herein are trademarks of their respective owners. </notice>