001// XMLReaderFactory.java - factory for creating a new reader.
002// Written by David Megginson, sax@megginson.com
003// NO WARRANTY!  This class is in the Public Domain.
004
005// $Id: XMLReaderFactory.java,v 1.1 2001/03/05 21:40:06 jstrachan Exp $
006
007package org.xml.sax.helpers;
008import org.xml.sax.Parser;
009import org.xml.sax.XMLReader;
010import org.xml.sax.SAXException;
011
012
013/**
014 * Factory for creating an XML reader.
015 *
016 * <blockquote>
017 * <em>This module, both source code and documentation, is in the
018 * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
019 * </blockquote>
020 *
021 * <p>This class contains static methods for creating an XML reader
022 * from an explicit class name, or for creating an XML reader based
023 * on the value of the <code>org.xml.sax.driver</code> system 
024 * property:</p>
025 *
026 * <pre>
027 * try {
028 *   XMLReader myReader = XMLReaderFactory.createXMLReader();
029 * } catch (SAXException e) {
030 *   System.err.println(e.getMessage());
031 * }
032 * </pre>
033 *
034 * <p>Note that these methods will not be usable in environments where
035 * system properties are not accessible or where the application or
036 * applet is not permitted to load classes dynamically.</p>
037 *
038 * <p><strong>Note to implementors:</strong> SAX implementations in specialized
039 * environments may replace this class with a different one optimized for the
040 * environment, as long as its method signatures remain the same.</p>
041 *
042 * @since SAX 2.0
043 * @author David Megginson, 
044 *         <a href="mailto:sax@megginson.com">sax@megginson.com</a>
045 * @version 2.0
046 * @see org.xml.sax.XMLReader
047 */
048final public class XMLReaderFactory
049{
050
051    /**
052     * Private constructor.
053     *
054     * <p>This constructor prevents the class from being instantiated.</p>
055     */
056    private XMLReaderFactory ()
057    {
058    }
059
060
061    /**
062     * Attempt to create an XML reader from a system property.
063     *
064     * <p>This method uses the value of the system property
065     * "org.xml.sax.driver" as the full name of a Java class
066     * and tries to instantiate that class as a SAX2 
067     * XMLReader.</p>
068     *
069     * <p>Note that many Java interpreters allow system properties
070     * to be specified on the command line.</p>
071     *
072     * @return A new XMLReader.
073     * @exception org.xml.sax.SAXException If the value of the
074     *            "org.xml.sax.driver" system property is null,
075     *            or if the class cannot be loaded and instantiated.
076     * @see #createXMLReader(java.lang.String)
077     */
078    public static XMLReader createXMLReader ()
079        throws SAXException
080    {
081        String className = System.getProperty("org.xml.sax.driver");
082        if (className == null) {
083            Parser parser;
084            try {
085                parser = ParserFactory.makeParser();
086            } catch (Exception e) {
087                parser = null;
088            }
089            if (parser == null) {
090                throw new
091                    SAXException("System property org.xml.sax.driver not specified");
092            } else {
093                return new ParserAdapter(parser);
094            }
095        } else {
096            return createXMLReader(className);
097        }
098    }
099
100
101    /**
102     * Attempt to create an XML reader from a class name.
103     *
104     * <p>Given a class name, this method attempts to load
105     * and instantiate the class as an XML reader.</p>
106     *
107     * @return A new XML reader.
108     * @exception org.xml.sax.SAXException If the class cannot be
109     *            loaded, instantiated, and cast to XMLReader.
110     * @see #createXMLReader()
111     */
112    public static XMLReader createXMLReader (String className)
113        throws SAXException
114    {
115        try {
116            return (XMLReader)(Class.forName(className).newInstance());
117        } catch (ClassNotFoundException e1) {
118            throw new SAXException("SAX2 driver class " + className +
119                                   " not found", e1);
120        } catch (IllegalAccessException e2) {
121            throw new SAXException("SAX2 driver class " + className +
122                                   " found but cannot be loaded", e2);
123        } catch (InstantiationException e3) {
124            throw new SAXException("SAX2 driver class " + className +
125                                   " loaded but cannot be instantiated (no empty public constructor?)",
126                                   e3);
127        } catch (ClassCastException e4) {
128            throw new SAXException("SAX2 driver class " + className +
129                                   " does not implement XMLReader", e4);
130        }
131                                   
132    }
133
134}
135
136// end of XMLReaderFactory.java