+
+ How to fetch DTDs and XML Schemas from JAR files using Castor
+
+ Introduction to using an EntityResolver to fetch XML dependencies
+ from JAR files rather than the network.
+
+ Final
+
+
+ How to fetch DTDs and XML Schemas from JAR files using Castor
+
+
+
+
+ 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.
+
+
+
+
+
+ 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.
+
+
+
+
+
+ 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. & or
+ <) 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.
+
+
+
+
+
+ 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.
+
+
+
+
+
+ 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.
+
+
+
+
+ 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
+
+
+
+
+
+
+
+
+