001: /*
002: * @(#)SAXParserFactory.java 1.23 01/12/03
003: *
004: * Copyright 2002 Sun Microsystems, Inc. All rights reserved.
005: * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
006: */
007:
008: package javax.xml.parsers;
009:
010: import org.xml.sax.Parser;
011: import org.xml.sax.SAXException;
012: import org.xml.sax.SAXNotRecognizedException;
013: import org.xml.sax.SAXNotSupportedException;
014:
015: /**
016: * Defines a factory API that enables applications to configure and
017: * obtain a SAX based parser to parse XML documents.<p>
018: * An implementation of the <code>SAXParserFactory</code> class is
019: * <em>NOT</em> guaranteed to be thread safe. It is up to the user application
020: * to make sure about the use of the <code>SAXParserFactory</code> from
021: * more than one thread. Alternatively the application can have one instance
022: * of the <code>SAXParserFactory</code> per thread.
023: * An application can use the same instance of the factory to obtain one or
024: * more instances of the <code>SAXParser</code> provided the instance
025: * of the factory isn't being used in more than one thread at a time.
026: * <p>
027: *
028: * The static <code>newInstance</code> method returns a new concrete
029: * implementation of this class.
030: *
031: * @since JAXP 1.0
032: * @version 1.0
033: */
034:
035: public abstract class SAXParserFactory {
036: private boolean validating = false;
037: private boolean namespaceAware = false;
038:
039: protected SAXParserFactory() {
040:
041: }
042:
043: /**
044: * Obtain a new instance of a <code>SAXParserFactory</code>. This
045: * static method creates a new factory instance
046: * This method uses the following ordered lookup procedure to determine
047: * the <code>SAXParserFactory</code> implementation class to
048: * load:
049: * <ul>
050: * <li>
051: * Use the <code>javax.xml.parsers.SAXParserFactory</code> system
052: * property.
053: * </li>
054: * <li>
055: * Use the properties file "lib/jaxp.properties" in the JRE directory.
056: * This configuration file is in standard <code>java.util.Properties
057: * </code> format and contains the fully qualified name of the
058: * implementation class with the key being the system property defined
059: * above.
060: * </li>
061: * <li>
062: * Use the Services API (as detailed in the JAR specification), if
063: * available, to determine the classname. The Services API will look
064: * for a classname in the file
065: * <code>META-INF/services/javax.xml.parsers.SAXParserFactory</code>
066: * in jars available to the runtime.
067: * </li>
068: * <li>
069: * Platform default <code>SAXParserFactory</code> instance.
070: * </li>
071: * </ul>
072: *
073: * Once an application has obtained a reference to a
074: * <code>SAXParserFactory</code> it can use the factory to
075: * configure and obtain parser instances.
076: *
077: * @return A new instance of a SAXParserFactory.
078: *
079: * @exception FactoryConfigurationError if the implementation is
080: * not available or cannot be instantiated.
081: */
082:
083: public static SAXParserFactory newInstance()
084: throws FactoryConfigurationError {
085: try {
086: return (SAXParserFactory) FactoryFinder.find(
087: /* The default property name according to the JAXP spec */
088: "javax.xml.parsers.SAXParserFactory",
089: /* The fallback implementation class name */
090: "com.bluecast.xml.JAXPSAXParserFactory");
091: } catch (FactoryFinder.ConfigurationError e) {
092: throw new FactoryConfigurationError(e.getException(), e
093: .getMessage());
094: }
095: }
096:
097: /**
098: * Creates a new instance of a SAXParser using the currently
099: * configured factory parameters.
100: *
101: * @return A new instance of a SAXParser.
102: *
103: * @exception ParserConfigurationException if a parser cannot
104: * be created which satisfies the requested configuration.
105: */
106:
107: public abstract SAXParser newSAXParser()
108: throws ParserConfigurationException, SAXException;
109:
110: /**
111: * Specifies that the parser produced by this code will
112: * provide support for XML namespaces. By default the value of this is set
113: * to <code>false</code>.
114: *
115: * @param awareness true if the parser produced by this code will
116: * provide support for XML namespaces; false otherwise.
117: */
118:
119: public void setNamespaceAware(boolean awareness) {
120: this .namespaceAware = awareness;
121: }
122:
123: /**
124: * Specifies that the parser produced by this code will
125: * validate documents as they are parsed. By default the value of this is
126: * set to <code>false</code>.
127: *
128: * @param validating true if the parser produced by this code will
129: * validate documents as they are parsed; false otherwise.
130: */
131:
132: public void setValidating(boolean validating) {
133: this .validating = validating;
134: }
135:
136: /**
137: * Indicates whether or not the factory is configured to produce
138: * parsers which are namespace aware.
139: *
140: * @return true if the factory is configured to produce
141: * parsers which are namespace aware; false otherwise.
142: */
143:
144: public boolean isNamespaceAware() {
145: return namespaceAware;
146: }
147:
148: /**
149: * Indicates whether or not the factory is configured to produce
150: * parsers which validate the XML content during parse.
151: *
152: * @return true if the factory is configured to produce parsers which validate
153: * the XML content during parse; false otherwise.
154: */
155:
156: public boolean isValidating() {
157: return validating;
158: }
159:
160: /**
161: *
162: * Sets the particular feature in the underlying implementation of
163: * org.xml.sax.XMLReader.
164: * A list of the core features and properties can be found at
165: * <a href="http://www.megginson.com/SAX/Java/features.html"> http://www.megginson.com/SAX/Java/features.html </a>
166: *
167: * @param name The name of the feature to be set.
168: * @param value The value of the feature to be set.
169: * @exception SAXNotRecognizedException When the underlying XMLReader does
170: * not recognize the property name.
171: *
172: * @exception SAXNotSupportedException When the underlying XMLReader
173: * recognizes the property name but doesn't support the
174: * property.
175: *
176: * @see org.xml.sax.XMLReader#setFeature
177: */
178: public abstract void setFeature(String name, boolean value)
179: throws ParserConfigurationException,
180: SAXNotRecognizedException, SAXNotSupportedException;
181:
182: /**
183: *
184: * Returns the particular property requested for in the underlying
185: * implementation of org.xml.sax.XMLReader.
186: *
187: * @param name The name of the property to be retrieved.
188: * @return Value of the requested property.
189: *
190: * @exception SAXNotRecognizedException When the underlying XMLReader does
191: * not recognize the property name.
192: *
193: * @exception SAXNotSupportedException When the underlying XMLReader
194: * recognizes the property name but doesn't support the
195: * property.
196: *
197: * @see org.xml.sax.XMLReader#getProperty
198: */
199: public abstract boolean getFeature(String name)
200: throws ParserConfigurationException,
201: SAXNotRecognizedException, SAXNotSupportedException;
202: }
|