|  |  |  | 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
| Copyright © 1999-2005 ExoLab Group, Intalio Inc., and Contributors. All rights reserved. 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. |