001 /*
002 * Copyright 2000-2006 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package javax.xml.parsers;
027
028 import javax.xml.validation.Schema;
029
030 import org.xml.sax.SAXException;
031 import org.xml.sax.SAXNotRecognizedException;
032 import org.xml.sax.SAXNotSupportedException;
033
034 /**
035 * Defines a factory API that enables applications to configure and
036 * obtain a SAX based parser to parse XML documents.
037 *
038 * @author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a>
039 * @author <a href="mailto:Neeraj.Bajaj@sun.com">Neeraj Bajaj</a>
040 *
041 * @version $Revision: 1.5 $, $Date: 2006/04/24 13:41:47 $
042 *
043 */
044 public abstract class SAXParserFactory {
045 /** The default property name according to the JAXP spec */
046 private static final String DEFAULT_PROPERTY_NAME = "javax.xml.parsers.SAXParserFactory";
047
048 /**
049 * <p>Should Parsers be validating?</p>
050 */
051 private boolean validating = false;
052
053 /**
054 * <p>Should Parsers be namespace aware?</p>
055 */
056 private boolean namespaceAware = false;
057
058 /**
059 * <p>Protected constructor to force use of {@link #newInstance()}.</p>
060 */
061 protected SAXParserFactory() {
062
063 }
064
065 /**
066 * Obtain a new instance of a <code>SAXParserFactory</code>. This
067 * static method creates a new factory instance
068 * This method uses the following ordered lookup procedure to determine
069 * the <code>SAXParserFactory</code> implementation class to
070 * load:
071 * <ul>
072 * <li>
073 * Use the <code>javax.xml.parsers.SAXParserFactory</code> system
074 * property.
075 * </li>
076 * <li>
077 * Use the properties file "lib/jaxp.properties" in the JRE directory.
078 * This configuration file is in standard <code>java.util.Properties
079 * </code> format and contains the fully qualified name of the
080 * implementation class with the key being the system property defined
081 * above.
082 *
083 * The jaxp.properties file is read only once by the JAXP implementation
084 * and it's values are then cached for future use. If the file does not exist
085 * when the first attempt is made to read from it, no further attempts are
086 * made to check for its existence. It is not possible to change the value
087 * of any property in jaxp.properties after it has been read for the first time.
088 * </li>
089 * <li>
090 * Use the Services API (as detailed in the JAR specification), if
091 * available, to determine the classname. The Services API will look
092 * for a classname in the file
093 * <code>META-INF/services/javax.xml.parsers.SAXParserFactory</code>
094 * in jars available to the runtime.
095 * </li>
096 * <li>
097 * Platform default <code>SAXParserFactory</code> instance.
098 * </li>
099 * </ul>
100 *
101 * Once an application has obtained a reference to a
102 * <code>SAXParserFactory</code> it can use the factory to
103 * configure and obtain parser instances.
104 *
105 *
106 *
107 * <h2>Tip for Trouble-shooting</h2>
108 * <p>Setting the <code>jaxp.debug</code> system property will cause
109 * this method to print a lot of debug messages
110 * to <code>System.err</code> about what it is doing and where it is looking at.</p>
111 *
112 * <p> If you have problems loading {@link DocumentBuilder}s, try:</p>
113 * <pre>
114 * java -Djaxp.debug=1 YourProgram ....
115 * </pre>
116 *
117 *
118 * @return A new instance of a SAXParserFactory.
119 *
120 * @throws FactoryConfigurationError if the implementation is
121 * not available or cannot be instantiated.
122 */
123
124 public static SAXParserFactory newInstance() {
125 try {
126 return (SAXParserFactory) FactoryFinder
127 .find(
128 /* The default property name according to the JAXP spec */
129 "javax.xml.parsers.SAXParserFactory",
130 /* The fallback implementation class name */
131 "com.sun.org.apache.xerces.internal.jaxp.SAXParserFactoryImpl");
132 } catch (FactoryFinder.ConfigurationError e) {
133 throw new FactoryConfigurationError(e.getException(), e
134 .getMessage());
135 }
136 }
137
138 /**
139 * <p>Obtain a new instance of a <code>SAXParserFactory</code> from class name.
140 * This function is useful when there are multiple providers in the classpath.
141 * It gives more control to the application as it can specify which provider
142 * should be loaded.</p>
143 *
144 * <p>Once an application has obtained a reference to a <code>SAXParserFactory</code>
145 * it can use the factory to configure and obtain parser instances.</p>
146 *
147 *
148 * <h2>Tip for Trouble-shooting</h2>
149 * <p>Setting the <code>jaxp.debug</code> system property will cause
150 * this method to print a lot of debug messages
151 * to <code>System.err</code> about what it is doing and where it is looking at.</p>
152 *
153 * <p> If you have problems, try:</p>
154 * <pre>
155 * java -Djaxp.debug=1 YourProgram ....
156 * </pre>
157 *
158 * @param factoryClassName fully qualified factory class name that provides implementation of <code>javax.xml.parsers.SAXParserFactory</code>.
159 *
160 * @param classLoader <code>ClassLoader</code> used to load the factory class. If <code>null</code>
161 * current <code>Thread</code>'s context classLoader is used to load the factory class.
162 *
163 * @return New instance of a <code>SAXParserFactory</code>
164 *
165 * @throws FactoryConfigurationError if <code>factoryClassName</code> is <code>null</code>, or
166 * the factory class cannot be loaded, instantiated.
167 *
168 * @see #newInstance()
169 *
170 * @since 1.6
171 */
172 public static SAXParserFactory newInstance(String factoryClassName,
173 ClassLoader classLoader) {
174 try {
175 //do not fallback if given classloader can't find the class, throw exception
176 return (SAXParserFactory) FactoryFinder.newInstance(
177 factoryClassName, classLoader, false);
178 } catch (FactoryFinder.ConfigurationError e) {
179 throw new FactoryConfigurationError(e.getException(), e
180 .getMessage());
181 }
182 }
183
184 /**
185 * <p>Creates a new instance of a SAXParser using the currently
186 * configured factory parameters.</p>
187 *
188 * @return A new instance of a SAXParser.
189 *
190 * @throws ParserConfigurationException if a parser cannot
191 * be created which satisfies the requested configuration.
192 * @throws SAXException for SAX errors.
193 */
194
195 public abstract SAXParser newSAXParser()
196 throws ParserConfigurationException, SAXException;
197
198 /**
199 * Specifies that the parser produced by this code will
200 * provide support for XML namespaces. By default the value of this is set
201 * to <code>false</code>.
202 *
203 * @param awareness true if the parser produced by this code will
204 * provide support for XML namespaces; false otherwise.
205 */
206
207 public void setNamespaceAware(boolean awareness) {
208 this .namespaceAware = awareness;
209 }
210
211 /**
212 * Specifies that the parser produced by this code will
213 * validate documents as they are parsed. By default the value of this is
214 * set to <code>false</code>.
215 *
216 * <p>
217 * Note that "the validation" here means
218 * <a href="http://www.w3.org/TR/REC-xml#proc-types">a validating
219 * parser</a> as defined in the XML recommendation.
220 * In other words, it essentially just controls the DTD validation.
221 * (except the legacy two properties defined in JAXP 1.2.)
222 * </p>
223 *
224 * <p>
225 * To use modern schema languages such as W3C XML Schema or
226 * RELAX NG instead of DTD, you can configure your parser to be
227 * a non-validating parser by leaving the {@link #setValidating(boolean)}
228 * method <code>false</code>, then use the {@link #setSchema(Schema)}
229 * method to associate a schema to a parser.
230 * </p>
231 *
232 * @param validating true if the parser produced by this code will
233 * validate documents as they are parsed; false otherwise.
234 */
235
236 public void setValidating(boolean validating) {
237 this .validating = validating;
238 }
239
240 /**
241 * Indicates whether or not the factory is configured to produce
242 * parsers which are namespace aware.
243 *
244 * @return true if the factory is configured to produce
245 * parsers which are namespace aware; false otherwise.
246 */
247
248 public boolean isNamespaceAware() {
249 return namespaceAware;
250 }
251
252 /**
253 * Indicates whether or not the factory is configured to produce
254 * parsers which validate the XML content during parse.
255 *
256 * @return true if the factory is configured to produce parsers which validate
257 * the XML content during parse; false otherwise.
258 */
259
260 public boolean isValidating() {
261 return validating;
262 }
263
264 /**
265 *
266 * <p>Sets the particular feature in the underlying implementation of
267 * org.xml.sax.XMLReader.
268 * A list of the core features and properties can be found at
269 * <a href="http://www.saxproject.org/">http://www.saxproject.org/</a></p>
270 *
271 * <p>All implementations are required to support the {@link javax.xml.XMLConstants#FEATURE_SECURE_PROCESSING} feature.
272 * When the feature is</p>
273 * <ul>
274 * <li>
275 * <code>true</code>: the implementation will limit XML processing to conform to implementation limits.
276 * Examples include enity expansion limits and XML Schema constructs that would consume large amounts of resources.
277 * If XML processing is limited for security reasons, it will be reported via a call to the registered
278 * {@link org.xml.sax.ErrorHandler#fatalError(SAXParseException exception)}.
279 * See {@link SAXParser} <code>parse</code> methods for handler specification.
280 * </li>
281 * <li>
282 * When the feature is <code>false</code>, the implementation will processing XML according to the XML specifications without
283 * regard to possible implementation limits.
284 * </li>
285 * </ul>
286 *
287 * @param name The name of the feature to be set.
288 * @param value The value of the feature to be set.
289 *
290 * @throws ParserConfigurationException if a parser cannot
291 * be created which satisfies the requested configuration.
292 * @throws SAXNotRecognizedException When the underlying XMLReader does
293 * not recognize the property name.
294 * @throws SAXNotSupportedException When the underlying XMLReader
295 * recognizes the property name but doesn't support the
296 * property.
297 * @throws NullPointerException If the <code>name</code> parameter is null.
298 *
299 * @see org.xml.sax.XMLReader#setFeature
300 */
301 public abstract void setFeature(String name, boolean value)
302 throws ParserConfigurationException,
303 SAXNotRecognizedException, SAXNotSupportedException;
304
305 /**
306 *
307 * <p>Returns the particular property requested for in the underlying
308 * implementation of org.xml.sax.XMLReader.</p>
309 *
310 * @param name The name of the property to be retrieved.
311 *
312 * @return Value of the requested property.
313 *
314 * @throws ParserConfigurationException if a parser cannot be created which satisfies the requested configuration.
315 * @throws SAXNotRecognizedException When the underlying XMLReader does not recognize the property name.
316 * @throws SAXNotSupportedException When the underlying XMLReader recognizes the property name but doesn't support the property.
317 *
318 * @see org.xml.sax.XMLReader#getProperty
319 */
320 public abstract boolean getFeature(String name)
321 throws ParserConfigurationException,
322 SAXNotRecognizedException, SAXNotSupportedException;
323
324 /* <p>Get current state of canonicalization.</p>
325 *
326 * @return current state canonicalization control
327 */
328 /*
329 public boolean getCanonicalization() {
330 return canonicalState;
331 }
332 */
333
334 /**
335 * Gets the {@link Schema} object specified through
336 * the {@link #setSchema(Schema schema)} method.
337 *
338 *
339 * @throws UnsupportedOperationException When implementation does not
340 * override this method
341 *
342 * @return
343 * the {@link Schema} object that was last set through
344 * the {@link #setSchema(Schema)} method, or null
345 * if the method was not invoked since a {@link SAXParserFactory}
346 * is created.
347 *
348 * @since 1.5
349 */
350 public Schema getSchema() {
351 throw new UnsupportedOperationException(
352 "This parser does not support specification \""
353 + this .getClass().getPackage()
354 .getSpecificationTitle()
355 + "\" version \""
356 + this .getClass().getPackage()
357 .getSpecificationVersion() + "\"");
358 }
359
360 /** <p>Set canonicalization control to <code>true</code> or
361 * </code>false</code>.</p>
362 *
363 * @param state of canonicalization
364 */
365 /*
366 public void setCanonicalization(boolean state) {
367 canonicalState = state;
368 }
369 */
370
371 /**
372 * <p>Set the {@link Schema} to be used by parsers created
373 * from this factory.</p>
374 *
375 * <p>When a {@link Schema} is non-null, a parser will use a validator
376 * created from it to validate documents before it passes information
377 * down to the application.</p>
378 *
379 * <p>When warnings/errors/fatal errors are found by the validator, the parser must
380 * handle them as if those errors were found by the parser itself.
381 * In other words, if the user-specified {@link org.xml.sax.ErrorHandler}
382 * is set, it must receive those errors, and if not, they must be
383 * treated according to the implementation specific
384 * default error handling rules.
385 *
386 * <p>A validator may modify the SAX event stream (for example by
387 * adding default values that were missing in documents), and a parser
388 * is responsible to make sure that the application will receive
389 * those modified event stream.</p>
390 *
391 * <p>Initialy, <code>null</code> is set as the {@link Schema}.</p>
392 *
393 * <p>This processing will take effect even if
394 * the {@link #isValidating()} method returns <code>false</code>.
395 *
396 * <p>It is an error to use
397 * the <code>http://java.sun.com/xml/jaxp/properties/schemaSource</code>
398 * property and/or the <code>http://java.sun.com/xml/jaxp/properties/schemaLanguage</code>
399 * property in conjunction with a non-null {@link Schema} object.
400 * Such configuration will cause a {@link SAXException}
401 * exception when those properties are set on a {@link SAXParser}.</p>
402 *
403 * <h4>Note for implmentors</h4>
404 * <p>
405 * A parser must be able to work with any {@link Schema}
406 * implementation. However, parsers and schemas are allowed
407 * to use implementation-specific custom mechanisms
408 * as long as they yield the result described in the specification.
409 * </p>
410 *
411 * @param schema <code>Schema</code> to use, <code>null</code> to remove a schema.
412 *
413 * @throws UnsupportedOperationException When implementation does not
414 * override this method
415 *
416 * @since 1.5
417 */
418 public void setSchema(Schema schema) {
419 throw new UnsupportedOperationException(
420 "This parser does not support specification \""
421 + this .getClass().getPackage()
422 .getSpecificationTitle()
423 + "\" version \""
424 + this .getClass().getPackage()
425 .getSpecificationVersion() + "\"");
426 }
427
428 /**
429 * <p>Set state of XInclude processing.</p>
430 *
431 * <p>If XInclude markup is found in the document instance, should it be
432 * processed as specified in <a href="http://www.w3.org/TR/xinclude/">
433 * XML Inclusions (XInclude) Version 1.0</a>.</p>
434 *
435 * <p>XInclude processing defaults to <code>false</code>.</p>
436 *
437 * @param state Set XInclude processing to <code>true</code> or
438 * <code>false</code>
439 *
440 * @throws UnsupportedOperationException When implementation does not
441 * override this method
442 *
443 * @since 1.5
444 */
445 public void setXIncludeAware(final boolean state) {
446 throw new UnsupportedOperationException(
447 "This parser does not support specification \""
448 + this .getClass().getPackage()
449 .getSpecificationTitle()
450 + "\" version \""
451 + this .getClass().getPackage()
452 .getSpecificationVersion() + "\"");
453 }
454
455 /**
456 * <p>Get state of XInclude processing.</p>
457 *
458 * @return current state of XInclude processing
459 *
460 * @throws UnsupportedOperationException When implementation does not
461 * override this method
462 *
463 * @since 1.5
464 */
465 public boolean isXIncludeAware() {
466 throw new UnsupportedOperationException(
467 "This parser does not support specification \""
468 + this .getClass().getPackage()
469 .getSpecificationTitle()
470 + "\" version \""
471 + this .getClass().getPackage()
472 .getSpecificationVersion() + "\"");
473 }
474 }
|