1 // XMLReaderFactory.java - factory for creating a new reader.
2 // http://www.saxproject.org
3 // Written by David Megginson
4 // and by David Brownell
5 // NO WARRANTY! This class is in the Public Domain.
7 // $Id: XMLReaderFactory.java,v 1.5.2.4 2002/01/29 21:34:15 dbrownell Exp $
9 package org
.xml
.sax
.helpers
;
10 import java
.io
.BufferedReader
;
11 import java
.io
.InputStream
;
12 import java
.io
.InputStreamReader
;
13 import org
.xml
.sax
.XMLReader
;
14 import org
.xml
.sax
.SAXException
;
18 * Factory for creating an XML reader.
21 * <em>This module, both source code and documentation, is in the
22 * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
23 * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
24 * for further information.
27 * <p>This class contains static methods for creating an XML reader
28 * from an explicit class name, or based on runtime defaults:</p>
32 * XMLReader myReader = XMLReaderFactory.createXMLReader();
33 * } catch (SAXException e) {
34 * System.err.println(e.getMessage());
38 * <p><strong>Note to Distributions bundled with parsers:</strong>
39 * You should modify the implementation of the no-arguments
40 * <em>createXMLReader</em> to handle cases where the external
41 * configuration mechanisms aren't set up. That method should do its
42 * best to return a parser when one is in the class path, even when
43 * nothing bound its class name to <code>org.xml.sax.driver</code> so
44 * those configuration mechanisms would see it.</p>
47 * @author David Megginson, David Brownell
48 * @version 2.0.1 (sax2r2)
50 final public class XMLReaderFactory
53 * Private constructor.
55 * <p>This constructor prevents the class from being instantiated.</p>
57 private XMLReaderFactory ()
61 private static final String property
= "org.xml.sax.driver";
64 * Attempt to create an XMLReader from system defaults.
65 * In environments which can support it, the name of the XMLReader
66 * class is determined by trying each these options in order, and
67 * using the first one which succeeds:</p> <ul>
69 * <li>If the system property <code>org.xml.sax.driver</code>
70 * has a value, that is used as an XMLReader class name. </li>
72 * <li>The JAR "Services API" is used to look for a class name
73 * in the <em>META-INF/services/org.xml.sax.driver</em> file in
74 * jarfiles available to the runtime.</li>
76 * <li> SAX parser distributions are strongly encouraged to provide
77 * a default XMLReader class name that will take effect only when
78 * previous options (on this list) are not successful.</li>
80 * <li>Finally, if {@link ParserFactory#makeParser()} can
81 * return a system default SAX1 parser, that parser is wrapped in
82 * a {@link ParserAdapter}. (This is a migration aid for SAX1
83 * environments, where the <code>org.xml.sax.parser</code> system
84 * property will often be usable.) </li>
88 * <p> In environments such as small embedded systems, which can not
89 * support that flexibility, other mechanisms to determine the default
92 * <p>Note that many Java environments allow system properties to be
93 * initialized on a command line. This means that <em>in most cases</em>
94 * setting a good value for that property ensures that calls to this
95 * method will succeed, except when security policies intervene.
96 * This will also maximize application portability to older SAX
97 * environments, with less robust implementations of this method.
100 * @return A new XMLReader.
101 * @exception org.xml.sax.SAXException If no default XMLReader class
102 * can be identified and instantiated.
103 * @see #createXMLReader(java.lang.String)
105 public static XMLReader
createXMLReader ()
108 String className
= null;
109 ClassLoader loader
= NewInstance
.getClassLoader ();
111 // 1. try the JVM-instance-wide system property
112 try { className
= System
.getProperty (property
); }
113 catch (Exception e
) { /* normally fails for applets */ }
115 // 2. if that fails, try META-INF/services/
116 if (className
== null) {
118 String service
= "META-INF/services/" + property
;
120 BufferedReader reader
;
123 in
= ClassLoader
.getSystemResourceAsStream (service
);
125 in
= loader
.getResourceAsStream (service
);
128 reader
= new BufferedReader (
129 new InputStreamReader (in
, "UTF8"));
130 className
= reader
.readLine ();
133 } catch (Exception e
) {
137 // 3. Distro-specific fallback
138 if (className
== null) {
139 // BEGIN DISTRIBUTION-SPECIFIC
142 // className = "com.example.sax.XmlReader";
143 // or a $JAVA_HOME/jre/lib/*properties setting...
145 // END DISTRIBUTION-SPECIFIC
148 // do we know the XMLReader implementation class yet?
149 if (className
!= null)
150 return loadClass (loader
, className
);
152 // 4. panic -- adapt any SAX1 parser
154 return new ParserAdapter (ParserFactory
.makeParser ());
155 } catch (Exception e
) {
156 throw new SAXException ("Can't create default XMLReader; "
157 + "is system property org.xml.sax.driver set?");
163 * Attempt to create an XML reader from a class name.
165 * <p>Given a class name, this method attempts to load
166 * and instantiate the class as an XML reader.</p>
168 * <p>Note that this method will not be usable in environments where
169 * the caller (perhaps an applet) is not permitted to load classes
172 * @return A new XML reader.
173 * @exception org.xml.sax.SAXException If the class cannot be
174 * loaded, instantiated, and cast to XMLReader.
175 * @see #createXMLReader()
177 public static XMLReader
createXMLReader (String className
)
180 return loadClass (NewInstance
.getClassLoader (), className
);
183 private static XMLReader
loadClass (ClassLoader loader
, String className
)
187 return (XMLReader
) NewInstance
.newInstance (loader
, className
);
188 } catch (ClassNotFoundException e1
) {
189 throw new SAXException("SAX2 driver class " + className
+
191 } catch (IllegalAccessException e2
) {
192 throw new SAXException("SAX2 driver class " + className
+
193 " found but cannot be loaded", e2
);
194 } catch (InstantiationException e3
) {
195 throw new SAXException("SAX2 driver class " + className
+
196 " loaded but cannot be instantiated (no empty public constructor?)",
198 } catch (ClassCastException e4
) {
199 throw new SAXException("SAX2 driver class " + className
+
200 " does not implement XMLReader", e4
);