1 /*
2 * Copyright (c) 2000, 2006, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package javax.xml.parsers;
27
28 import javax.xml.validation.Schema;
29 import org.xml.sax.SAXException;
30 import org.xml.sax.SAXNotRecognizedException;
31 import org.xml.sax.SAXNotSupportedException;
32
33 /**
34 * Defines a factory API that enables applications to configure and
35 * obtain a SAX based parser to parse XML documents.
36 *
37 * @author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a>
38 * @author <a href="mailto:Neeraj.Bajaj@sun.com">Neeraj Bajaj</a>
39 *
40 * @version $Revision: 1.10 $, $Date: 2010-11-01 04:36:09 $
41 *
42 */
43 public abstract class SAXParserFactory {
44 /** The default property name according to the JAXP spec */
45 private static final String DEFAULT_PROPERTY_NAME = "javax.xml.parsers.SAXParserFactory";
46
47 /**
48 * <p>Should Parsers be validating?</p>
49 */
50 private boolean validating = false;
51
52 /**
53 * <p>Should Parsers be namespace aware?</p>
54 */
55 private boolean namespaceAware = false;
56
57 /**
58 * <p>Protected constructor to force use of {@link #newInstance()}.</p>
59 */
60 protected SAXParserFactory () {
61
62 }
63
64 /**
65 * Obtain a new instance of a <code>SAXParserFactory</code>. This
66 * static method creates a new factory instance
67 * This method uses the following ordered lookup procedure to determine
68 * the <code>SAXParserFactory</code> implementation class to
69 * load:
70 * <ul>
71 * <li>
72 * Use the <code>javax.xml.parsers.SAXParserFactory</code> system
73 * property.
74 * </li>
75 * <li>
76 * Use the properties file "lib/jaxp.properties" in the JRE directory.
77 * This configuration file is in standard <code>java.util.Properties
78 * </code> format and contains the fully qualified name of the
79 * implementation class with the key being the system property defined
80 * above.
81 *
82 * The jaxp.properties file is read only once by the JAXP implementation
83 * and it's values are then cached for future use. If the file does not exist
84 * when the first attempt is made to read from it, no further attempts are
85 * made to check for its existence. It is not possible to change the value
86 * of any property in jaxp.properties after it has been read for the first time.
87 * </li>
88 * <li>
89 * Uses the service-provider loading facilities, defined by the {@link java.util.ServiceLoader} class, to attempt
90 * to locate and load an implementation of the service. If there are providers other than the implementation specific
91 * default located, then the first provider that is not the default is instantiated and returned; Otherwise
92 * the default implementation is returned if it is on the classpath or installed as a module.
93 *
94 * If a misconfigured provider is encountered and {@link java.util.ServiceConfigurationError} is thrown, the error will be wrapped
95 * in a {@link javax.xml.parsers.FactoryConfigurationException}.</p>
96 * </li>
97 * <li>
98 * Platform default <code>SAXParserFactory</code> instance.
99 * </li>
100 * </ul>
101 *
102 * Once an application has obtained a reference to a
103 * <code>SAXParserFactory</code> it can use the factory to
104 * configure and obtain parser instances.
105 *
106 *
107 *
108 * <h2>Tip for Trouble-shooting</h2>
109 * <p>Setting the <code>jaxp.debug</code> system property will cause
110 * this method to print a lot of debug messages
111 * to <code>System.err</code> about what it is doing and where it is looking at.</p>
112 *
113 * <p> If you have problems loading {@link DocumentBuilder}s, try:</p>
114 * <pre>
115 * java -Djaxp.debug=1 YourProgram ....
116 * </pre>
117 *
118 *
119 * @return A new instance of a SAXParserFactory.
120 *
121 * @throws FactoryConfigurationError if the implementation is
122 * not available or cannot be instantiated.
123 */
124
125 public static SAXParserFactory newInstance()
126 {
127 try{
128 return (SAXParserFactory) FactoryFinder.find(SAXParserFactory.class,
129 /* The default property name according to the JAXP spec */
130 "javax.xml.parsers.SAXParserFactory",
131 /* The fallback implementation class name */
132 "com.sun.org.apache.xerces.internal.jaxp.SAXParserFactoryImpl");
133 } catch (FactoryConfigurationError e) {
134 throw e;
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, ClassLoader classLoader){
173 try {
174 //do not fallback if given classloader can't find the class, throw exception
175 return (SAXParserFactory) FactoryFinder.newInstance(factoryClassName, classLoader, false);
176 } catch (FactoryConfigurationError e) {
177 throw e;
178 }
179 }
180
181 /**
182 * <p>Creates a new instance of a SAXParser using the currently
183 * configured factory parameters.</p>
184 *
185 * @return A new instance of a SAXParser.
186 *
187 * @throws ParserConfigurationException if a parser cannot
188 * be created which satisfies the requested configuration.
189 * @throws SAXException for SAX errors.
190 */
191
192 public abstract SAXParser newSAXParser()
193 throws ParserConfigurationException, SAXException;
194
195
196 /**
197 * Specifies that the parser produced by this code will
198 * provide support for XML namespaces. By default the value of this is set
199 * to <code>false</code>.
200 *
201 * @param awareness true if the parser produced by this code will
202 * provide support for XML namespaces; false otherwise.
203 */
204
205 public void setNamespaceAware(boolean awareness) {
206 this.namespaceAware = awareness;
207 }
208
209 /**
210 * Specifies that the parser produced by this code will
211 * validate documents as they are parsed. By default the value of this is
212 * set to <code>false</code>.
213 *
214 * <p>
215 * Note that "the validation" here means
216 * <a href="http://www.w3.org/TR/REC-xml#proc-types">a validating
217 * parser</a> as defined in the XML recommendation.
218 * In other words, it essentially just controls the DTD validation.
219 * (except the legacy two properties defined in JAXP 1.2.)
220 * </p>
221 *
222 * <p>
223 * To use modern schema languages such as W3C XML Schema or
224 * RELAX NG instead of DTD, you can configure your parser to be
225 * a non-validating parser by leaving the {@link #setValidating(boolean)}
226 * method <code>false</code>, then use the {@link #setSchema(Schema)}
227 * method to associate a schema to a parser.
228 * </p>
229 *
230 * @param validating true if the parser produced by this code will
231 * validate documents as they are parsed; false otherwise.
232 */
233
234 public void setValidating(boolean validating) {
235 this.validating = validating;
236 }
237
238 /**
239 * Indicates whether or not the factory is configured to produce
240 * parsers which are namespace aware.
241 *
242 * @return true if the factory is configured to produce
243 * parsers which are namespace aware; false otherwise.
244 */
245
246 public boolean isNamespaceAware() {
247 return namespaceAware;
248 }
249
250 /**
251 * Indicates whether or not the factory is configured to produce
252 * parsers which validate the XML content during parse.
253 *
254 * @return true if the factory is configured to produce parsers which validate
255 * the XML content during parse; false otherwise.
256 */
257
258 public boolean isValidating() {
259 return validating;
260 }
261
262 /**
263 *
264 * <p>Sets the particular feature in the underlying implementation of
265 * org.xml.sax.XMLReader.
266 * A list of the core features and properties can be found at
267 * <a href="http://www.saxproject.org/">http://www.saxproject.org/</a></p>
268 *
269 * <p>All implementations are required to support the {@link javax.xml.XMLConstants#FEATURE_SECURE_PROCESSING} feature.
270 * When the feature is</p>
271 * <ul>
272 * <li>
273 * <code>true</code>: the implementation will limit XML processing to conform to implementation limits.
274 * Examples include enity expansion limits and XML Schema constructs that would consume large amounts of resources.
275 * If XML processing is limited for security reasons, it will be reported via a call to the registered
276 * {@link org.xml.sax.ErrorHandler#fatalError(SAXParseException exception)}.
277 * See {@link SAXParser} <code>parse</code> methods for handler specification.
278 * </li>
279 * <li>
280 * When the feature is <code>false</code>, the implementation will processing XML according to the XML specifications without
281 * regard to possible implementation limits.
282 * </li>
283 * </ul>
284 *
285 * @param name The name of the feature to be set.
286 * @param value The value of the feature to be set.
287 *
288 * @throws ParserConfigurationException if a parser cannot
289 * be created which satisfies the requested configuration.
290 * @throws SAXNotRecognizedException When the underlying XMLReader does
291 * not recognize the property name.
292 * @throws SAXNotSupportedException When the underlying XMLReader
293 * recognizes the property name but doesn't support the
294 * property.
295 * @throws NullPointerException If the <code>name</code> parameter is null.
296 *
297 * @see org.xml.sax.XMLReader#setFeature
298 */
299 public abstract void setFeature(String name, boolean value)
300 throws ParserConfigurationException, SAXNotRecognizedException,
301 SAXNotSupportedException;
302
303 /**
304 *
305 * <p>Returns the particular property requested for in the underlying
306 * implementation of org.xml.sax.XMLReader.</p>
307 *
308 * @param name The name of the property to be retrieved.
309 *
310 * @return Value of the requested property.
311 *
312 * @throws ParserConfigurationException if a parser cannot be created which satisfies the requested configuration.
313 * @throws SAXNotRecognizedException When the underlying XMLReader does not recognize the property name.
314 * @throws SAXNotSupportedException When the underlying XMLReader recognizes the property name but doesn't support the property.
315 *
316 * @see org.xml.sax.XMLReader#getProperty
317 */
318 public abstract boolean getFeature(String name)
319 throws ParserConfigurationException, SAXNotRecognizedException,
320 SAXNotSupportedException;
321
322
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().getSpecificationTitle()
354 + "\" version \""
355 + this.getClass().getPackage().getSpecificationVersion()
356 + "\""
357 );
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().getSpecificationTitle()
422 + "\" version \""
423 + this.getClass().getPackage().getSpecificationVersion()
424 + "\""
425 );
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 if (state) {
447 throw new UnsupportedOperationException(" setXIncludeAware " +
448 "is not supported on this JAXP" +
449 " implementation or earlier: " + this.getClass());
450 }
451 }
452
453 /**
454 * <p>Get state of XInclude processing.</p>
455 *
456 * @return current state of XInclude processing
457 *
458 * @throws UnsupportedOperationException When implementation does not
459 * override this method
460 *
461 * @since 1.5
462 */
463 public boolean isXIncludeAware() {
464 throw new UnsupportedOperationException(
465 "This parser does not support specification \""
466 + this.getClass().getPackage().getSpecificationTitle()
467 + "\" version \""
468 + this.getClass().getPackage().getSpecificationVersion()
469 + "\""
470 );
471 }
472 }