001: /*
002: *
003: *
004: * Copyright 1990-2007 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
006: *
007: * This program is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU General Public License version
009: * 2 only, as published by the Free Software Foundation.
010: *
011: * This program is distributed in the hope that it will be useful, but
012: * WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * General Public License version 2 for more details (a copy is
015: * included at /legal/license.txt).
016: *
017: * You should have received a copy of the GNU General Public License
018: * version 2 along with this work; if not, write to the Free Software
019: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA
021: *
022: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
023: * Clara, CA 95054 or visit www.sun.com if you need additional
024: * information or have any questions.
025: */
026:
027: package javax.xml.parsers;
028:
029: import org.xml.sax.SAXException;
030: import org.xml.sax.SAXNotSupportedException;
031: import org.xml.sax.SAXNotRecognizedException;
032:
033: /**
034: * Defines a factory API that enables applications to configure and
035: * obtain a SAX based parser to parse XML documents.<p>
036: * An implementation of the <code>SAXParserFactory</code> class is
037: * <em>NOT</em> guaranteed to be thread safe. It is up to the user application
038: * to make sure about the use of the <code>SAXParserFactory</code> from
039: * more than one thread. Alternatively the application can have one instance
040: * of the <code>SAXParserFactory</code> per thread.
041: * An application can use the same instance of the factory to obtain one or
042: * more instances of the <code>SAXParser</code> provided the instance
043: * of the factory isn't being used in more than one thread at a time.
044: * <p>
045: *
046: * The static <code>newInstance</code> method returns a new concrete
047: * implementation of this class.
048: *
049: * @since JAXP 1.0
050: * @version 1.0
051: */
052:
053: public abstract class SAXParserFactory {
054:
055: private boolean namespaceAware = false;
056:
057: private boolean validating = false;
058:
059: protected SAXParserFactory() {
060: }
061:
062: /**
063: * Obtain a new instance of a <code>SAXParserFactory</code>. This
064: * static method creates a new factory instance
065: * This method uses the following ordered lookup procedure to determine
066: * the <code>SAXParserFactory</code> implementation class to
067: * load:
068: * <ul>
069: * <li>
070: * Use the <code>javax.xml.parsers.SAXParserFactory</code> system
071: * property.
072: * </li>
073: * <li>
074: * Use the properties file "lib/jaxp.properties" in the JRE directory.
075: * This configuration file is in standard <code>java.util.Properties
076: * </code> format and contains the fully qualified name of the
077: * implementation class with the key being the system property defined
078: * above.
079: * </li>
080: * <li>
081: * Use the Services API (as detailed in the JAR specification), if
082: * available, to determine the classname. The Services API will look
083: * for a classname in the file
084: * <code>META-INF/services/javax.xml.parsers.SAXParserFactory</code>
085: * in jars available to the runtime.
086: * </li>
087: * <li>
088: * Platform default <code>SAXParserFactory</code> instance.
089: * </li>
090: * </ul>
091: *
092: * Once an application has obtained a reference to a
093: * <code>SAXParserFactory</code> it can use the factory to
094: * configure and obtain parser instances.
095: *
096: * @return A new instance of a SAXParserFactory.
097: *
098: * @exception FactoryConfigurationError if the implementation is
099: * not available or cannot be instantiated.
100: */
101:
102: public static SAXParserFactory newInstance()
103: throws FactoryConfigurationError {
104: return new com.sun.ukit.jaxp.ParserFactory();
105: }
106:
107: /**
108: * Creates a new instance of a SAXParser using the currently
109: * configured factory parameters.
110: *
111: * @return A new instance of a SAXParser.
112: *
113: * @exception ParserConfigurationException if a parser cannot
114: * be created which satisfies the requested configuration.
115: */
116:
117: public abstract SAXParser newSAXParser()
118: throws ParserConfigurationException, SAXException;
119:
120: /**
121: * Specifies that the parser produced by this code will
122: * provide support for XML namespaces. By default the value of this is set
123: * to <code>false</code>.
124: *
125: * @param awareness true if the parser produced by this code will
126: * provide support for XML namespaces; false otherwise.
127: */
128:
129: public void setNamespaceAware(boolean awareness) {
130: namespaceAware = awareness;
131: }
132:
133: /**
134: * Indicates whether or not the factory is configured to produce
135: * parsers which are namespace aware.
136: *
137: * @return true if the factory is configured to produce
138: * parsers which are namespace aware; false otherwise.
139: */
140:
141: public boolean isNamespaceAware() {
142: return namespaceAware;
143: }
144:
145: /**
146: * Specifies that the parser produced by this code will validate
147: * documents as they are parsed. By default the value of this is
148: * set to false.
149: *
150: * @param validating true if the parser produced by this code will
151: * validate documents as they are parsed; false
152: * otherwise.
153: */
154: public void setValidating(boolean validating) {
155: // NOTE: the factory does not currently support a validating parser
156: validating = false;
157: }
158:
159: /**
160: * Indicates whether or not the factory is configured to produce
161: * parsers which validate the XML content during parse.
162: *
163: * @return true if the factory is configured to produce parsers
164: * which validate the XML content during parse.
165: */
166: public boolean isValidating() {
167: return validating;
168: }
169:
170: /**
171: * Sets the particular feature in the underlying implementation of
172: * org.xml.sax.XMLReader.
173: * A list of the core features and properties can be found at
174: * <a href="http://www.saxproject.org/?selected=get-set"> http://www.saxproject.org/?selected=get-set </a>
175: *
176: * @param name The name of the feature to be set.
177: * @param value The value of the feature to be set.
178: * @exception SAXNotRecognizedException When the underlying XMLReader does
179: * not recognize the property name.
180: *
181: * @exception SAXNotSupportedException When the underlying XMLReader
182: * recognizes the property name but doesn't support the
183: * property.
184: *
185: * @see org.xml.sax.XMLReader#setFeature
186: */
187: public abstract void setFeature(String name, boolean value)
188: throws ParserConfigurationException,
189: SAXNotRecognizedException, SAXNotSupportedException;
190:
191: /**
192: * Returns the particular property requested for in the underlying
193: * implementation of org.xml.sax.XMLReader.
194: *
195: * @param name The name of the property to be retrieved.
196: * @return Value of the requested property.
197: *
198: * @exception SAXNotRecognizedException When the underlying XMLReader does
199: * not recognize the property name.
200: *
201: * @exception SAXNotSupportedException When the underlying XMLReader
202: * recognizes the property name but doesn't support the
203: * property.
204: *
205: * @see org.xml.sax.XMLReader#getProperty
206: */
207: public abstract boolean getFeature(String name)
208: throws ParserConfigurationException,
209: SAXNotRecognizedException, SAXNotSupportedException;
210:
211: }
|