1 /*
2 * Copyright (c) 2000, 2015, 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 com.sun.org.apache.xerces.internal.jaxp.DocumentBuilderFactoryImpl;
29 import javax.xml.validation.Schema;
30
31 /**
32 * Defines a factory API that enables applications to obtain a
33 * parser that produces DOM object trees from XML documents.
34 *
35 * @author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a>
36 * @author <a href="mailto:Neeraj.Bajaj@sun.com">Neeraj Bajaj</a>
37 *
38 * @since 1.4
39 */
40
41 public abstract class DocumentBuilderFactory {
42
43 private boolean validating = false;
44 private boolean namespaceAware = false;
45 private boolean whitespace = false;
46 private boolean expandEntityRef = true;
47 private boolean ignoreComments = false;
48 private boolean coalescing = false;
49
50 /**
51 * Protected constructor to prevent instantiation.
52 * Use {@link #newInstance()}.
53 */
54 protected DocumentBuilderFactory () {
55 }
56
57 /**
58 * Creates a new instance of the {@code DocumentBuilderFactory} builtin
59 * system-default implementation.
60 *
61 * @return A new instance of the {@code DocumentBuilderFactory} builtin
62 * system-default implementation.
63 *
64 * @since 9
65 */
66 public static DocumentBuilderFactory newDefaultInstance() {
67 return new DocumentBuilderFactoryImpl();
68 }
69
70 /**
71 * Obtain a new instance of a
72 * {@code DocumentBuilderFactory}. This static method creates
73 * a new factory instance.
74 * This method uses the following ordered lookup procedure to determine
75 * the {@code DocumentBuilderFactory} implementation class to
76 * load:
77 * <ul>
78 * <li>
79 * Use the {@code javax.xml.parsers.DocumentBuilderFactory} system
80 * property.
81 * </li>
82 * <li>
83 * <p>
84 * Use the configuration file "jaxp.properties". The file is in standard
85 * {@link java.util.Properties} format and typically located in the
86 * {@code conf} directory of the Java installation. It contains the fully qualified
87 * name of the implementation class with the key being the system property
88 * defined above.
89 * <p>
90 * The jaxp.properties file is read only once by the JAXP implementation
91 * and its values are then cached for future use. If the file does not exist
92 * when the first attempt is made to read from it, no further attempts are
93 * made to check for its existence. It is not possible to change the value
94 * of any property in jaxp.properties after it has been read for the first time.
95 * </li>
96 * <li>
97 * <p>
98 * Use the service-provider loading facility, defined by the
99 * {@link java.util.ServiceLoader} class, to attempt to locate and load an
100 * implementation of the service using the {@linkplain
101 * java.util.ServiceLoader#load(java.lang.Class) default loading mechanism}:
102 * the service-provider loading facility will use the {@linkplain
103 * java.lang.Thread#getContextClassLoader() current thread's context class loader}
104 * to attempt to load the service. If the context class
105 * loader is null, the {@linkplain
106 * ClassLoader#getSystemClassLoader() system class loader} will be used.
107 * </li>
108 * <li>
109 * <p>
110 * Otherwise, the {@linkplain #newDefaultInstance() system-default}
111 * implementation is returned.
112 * </li>
113 * </ul>
114 *
115 * <p>
116 * Once an application has obtained a reference to a
117 * {@code DocumentBuilderFactory} it can use the factory to
118 * configure and obtain parser instances.
119 *
120 *
121 * <h2>Tip for Trouble-shooting</h2>
122 * <p>
123 * Setting the {@code jaxp.debug} system property will cause
124 * this method to print a lot of debug messages
125 * to {@code System.err} about what it is doing and where it is looking at.
126 *
127 * <p>
128 * If you have problems loading {@link DocumentBuilder}s, try:
129 * <pre>
130 * java -Djaxp.debug=1 YourProgram ....
131 * </pre>
132 *
133 * @return New instance of a {@code DocumentBuilderFactory}
134 *
135 * @throws FactoryConfigurationError in case of {@linkplain
136 * java.util.ServiceConfigurationError service configuration error} or if
137 * the implementation is not available or cannot be instantiated.
138 */
139 public static DocumentBuilderFactory newInstance() {
140 return FactoryFinder.find(
141 /* The default property name according to the JAXP spec */
142 DocumentBuilderFactory.class, // "javax.xml.parsers.DocumentBuilderFactory"
143 /* The fallback implementation class name */
144 "com.sun.org.apache.xerces.internal.jaxp.DocumentBuilderFactoryImpl");
145 }
146
147 /**
148 * Obtain a new instance of a {@code DocumentBuilderFactory} from class name.
149 * This function is useful when there are multiple providers in the classpath.
150 * It gives more control to the application as it can specify which provider
151 * should be loaded.
152 *
153 * <p>Once an application has obtained a reference to a {@code DocumentBuilderFactory}
154 * it can use the factory to configure and obtain parser instances.
155 *
156 *
157 * <h2>Tip for Trouble-shooting</h2>
158 * <p>Setting the {@code jaxp.debug} system property will cause
159 * this method to print a lot of debug messages
160 * to {@code System.err} about what it is doing and where it is looking at.
161 *
162 * <p> If you have problems try:
163 * <pre>
164 * java -Djaxp.debug=1 YourProgram ....
165 * </pre>
166 *
167 * @param factoryClassName fully qualified factory class name that provides
168 * implementation of {@code javax.xml.parsers.DocumentBuilderFactory}.
169 *
170 * @param classLoader {@code ClassLoader} used to load the factory class. If {@code null}
171 * current {@code Thread}'s context classLoader is used to load the factory class.
172 *
173 * @return New instance of a {@code DocumentBuilderFactory}
174 *
175 * @throws FactoryConfigurationError if {@code factoryClassName} is {@code null}, or
176 * the factory class cannot be loaded, instantiated.
177 *
178 * @see #newInstance()
179 *
180 * @since 1.6
181 */
182 public static DocumentBuilderFactory newInstance(String factoryClassName, ClassLoader classLoader){
183 //do not fallback if given classloader can't find the class, throw exception
184 return FactoryFinder.newInstance(DocumentBuilderFactory.class,
185 factoryClassName, classLoader, false);
186 }
187
188 /**
189 * Creates a new instance of a {@link javax.xml.parsers.DocumentBuilder}
190 * using the currently configured parameters.
191 *
192 * @return A new instance of a DocumentBuilder.
193 *
194 * @throws ParserConfigurationException if a DocumentBuilder
195 * cannot be created which satisfies the configuration requested.
196 */
197
198 public abstract DocumentBuilder newDocumentBuilder()
199 throws ParserConfigurationException;
200
201
202 /**
203 * Specifies that the parser produced by this code will
204 * provide support for XML namespaces. By default the value of this is set
205 * to {@code false}
206 *
207 * @param awareness true if the parser produced will provide support
208 * for XML namespaces; false otherwise.
209 */
210
211 public void setNamespaceAware(boolean awareness) {
212 this.namespaceAware = awareness;
213 }
214
215 /**
216 * Specifies that the parser produced by this code will
217 * validate documents as they are parsed. By default the value of this
218 * is set to {@code false}.
219 *
220 * <p>
221 * Note that "the validation" here means
222 * <a href="http://www.w3.org/TR/REC-xml#proc-types">a validating
223 * parser</a> as defined in the XML recommendation.
224 * In other words, it essentially just controls the DTD validation.
225 * (except the legacy two properties defined in JAXP 1.2.)
226 *
227 * <p>
228 * To use modern schema languages such as W3C XML Schema or
229 * RELAX NG instead of DTD, you can configure your parser to be
230 * a non-validating parser by leaving the {@link #setValidating(boolean)}
231 * method {@code false}, then use the {@link #setSchema(Schema)}
232 * method to associate a schema to a parser.
233 *
234 * @param validating true if the parser produced will validate documents
235 * as they are parsed; false otherwise.
236 */
237
238 public void setValidating(boolean validating) {
239 this.validating = validating;
240 }
241
242 /**
243 * Specifies that the parsers created by this factory must eliminate
244 * whitespace in element content (sometimes known loosely as
245 * 'ignorable whitespace') when parsing XML documents (see XML Rec
246 * 2.10). Note that only whitespace which is directly contained within
247 * element content that has an element only content model (see XML
248 * Rec 3.2.1) will be eliminated. Due to reliance on the content model
249 * this setting requires the parser to be in validating mode. By default
250 * the value of this is set to {@code false}.
251 *
252 * @param whitespace true if the parser created must eliminate whitespace
253 * in the element content when parsing XML documents;
254 * false otherwise.
255 */
256
257 public void setIgnoringElementContentWhitespace(boolean whitespace) {
258 this.whitespace = whitespace;
259 }
260
261 /**
262 * Specifies that the parser produced by this code will
263 * expand entity reference nodes. By default the value of this is set to
264 * {@code true}
265 *
266 * @param expandEntityRef true if the parser produced will expand entity
267 * reference nodes; false otherwise.
268 */
269
270 public void setExpandEntityReferences(boolean expandEntityRef) {
271 this.expandEntityRef = expandEntityRef;
272 }
273
274 /**
275 * Specifies that the parser produced by this code will
276 * ignore comments. By default the value of this is set to {@code false}.
277 *
278 * @param ignoreComments {@code boolean} value to ignore comments during processing
279 */
280
281 public void setIgnoringComments(boolean ignoreComments) {
282 this.ignoreComments = ignoreComments;
283 }
284
285 /**
286 * Specifies that the parser produced by this code will
287 * convert CDATA nodes to Text nodes and append it to the
288 * adjacent (if any) text node. By default the value of this is set to
289 * {@code false}
290 *
291 * @param coalescing true if the parser produced will convert CDATA nodes
292 * to Text nodes and append it to the adjacent (if any)
293 * text node; false otherwise.
294 */
295
296 public void setCoalescing(boolean coalescing) {
297 this.coalescing = coalescing;
298 }
299
300 /**
301 * Indicates whether or not the factory is configured to produce
302 * parsers which are namespace aware.
303 *
304 * @return true if the factory is configured to produce parsers which
305 * are namespace aware; false otherwise.
306 */
307
308 public boolean isNamespaceAware() {
309 return namespaceAware;
310 }
311
312 /**
313 * Indicates whether or not the factory is configured to produce
314 * parsers which validate the XML content during parse.
315 *
316 * @return true if the factory is configured to produce parsers
317 * which validate the XML content during parse; false otherwise.
318 */
319
320 public boolean isValidating() {
321 return validating;
322 }
323
324 /**
325 * Indicates whether or not the factory is configured to produce
326 * parsers which ignore ignorable whitespace in element content.
327 *
328 * @return true if the factory is configured to produce parsers
329 * which ignore ignorable whitespace in element content;
330 * false otherwise.
331 */
332
333 public boolean isIgnoringElementContentWhitespace() {
334 return whitespace;
335 }
336
337 /**
338 * Indicates whether or not the factory is configured to produce
339 * parsers which expand entity reference nodes.
340 *
341 * @return true if the factory is configured to produce parsers
342 * which expand entity reference nodes; false otherwise.
343 */
344
345 public boolean isExpandEntityReferences() {
346 return expandEntityRef;
347 }
348
349 /**
350 * Indicates whether or not the factory is configured to produce
351 * parsers which ignores comments.
352 *
353 * @return true if the factory is configured to produce parsers
354 * which ignores comments; false otherwise.
355 */
356
357 public boolean isIgnoringComments() {
358 return ignoreComments;
359 }
360
361 /**
362 * Indicates whether or not the factory is configured to produce
363 * parsers which converts CDATA nodes to Text nodes and appends it to
364 * the adjacent (if any) Text node.
365 *
366 * @return true if the factory is configured to produce parsers
367 * which converts CDATA nodes to Text nodes and appends it to
368 * the adjacent (if any) Text node; false otherwise.
369 */
370
371 public boolean isCoalescing() {
372 return coalescing;
373 }
374
375 /**
376 * Allows the user to set specific attributes on the underlying
377 * implementation.
378 * <p>
379 * All implementations that implement JAXP 1.5 or newer are required to
380 * support the {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_DTD} and
381 * {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_SCHEMA} properties.
382 *
383 * <ul>
384 * <li>
385 * Setting the {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_DTD} property
386 * restricts the access to external DTDs, external Entity References to the
387 * protocols specified by the property.
388 * If access is denied during parsing due to the restriction of this property,
389 * {@link org.xml.sax.SAXException} will be thrown by the parse methods defined by
390 * {@link javax.xml.parsers.DocumentBuilder}.
391 * </li>
392 * <li>
393 * Setting the {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_SCHEMA} property
394 * restricts the access to external Schema set by the schemaLocation attribute to
395 * the protocols specified by the property. If access is denied during parsing
396 * due to the restriction of this property, {@link org.xml.sax.SAXException}
397 * will be thrown by the parse methods defined by
398 * {@link javax.xml.parsers.DocumentBuilder}.
399 * </li>
400 * </ul>
401 *
402 * @param name The name of the attribute.
403 * @param value The value of the attribute.
404 *
405 * @throws IllegalArgumentException thrown if the underlying
406 * implementation doesn't recognize the attribute.
407 */
408 public abstract void setAttribute(String name, Object value)
409 throws IllegalArgumentException;
410
411 /**
412 * Allows the user to retrieve specific attributes on the underlying
413 * implementation.
414 *
415 * @param name The name of the attribute.
416 *
417 * @return value The value of the attribute.
418 *
419 * @throws IllegalArgumentException thrown if the underlying
420 * implementation doesn't recognize the attribute.
421 */
422 public abstract Object getAttribute(String name)
423 throws IllegalArgumentException;
424
425 /**
426 * Set a feature for this {@code DocumentBuilderFactory}
427 * and {@code DocumentBuilder}s created by this factory.
428 *
429 * <p>
430 * Feature names are fully qualified {@link java.net.URI}s.
431 * Implementations may define their own features.
432 * A {@link ParserConfigurationException} is thrown if this {@code DocumentBuilderFactory} or the
433 * {@code DocumentBuilder}s it creates cannot support the feature.
434 * It is possible for a {@code DocumentBuilderFactory} to expose a feature value but be unable to change its state.
435 *
436 *
437 * <p>
438 * All implementations are required to support the {@link javax.xml.XMLConstants#FEATURE_SECURE_PROCESSING} feature.
439 * When the feature is:
440 * <ul>
441 * <li>
442 * {@code true}: the implementation will limit XML processing to conform to implementation limits.
443 * Examples include entity expansion limits and XML Schema constructs that would consume large amounts of resources.
444 * If XML processing is limited for security reasons, it will be reported via a call to the registered
445 * {@link org.xml.sax.ErrorHandler#fatalError(SAXParseException exception)}.
446 * See {@link DocumentBuilder#setErrorHandler(org.xml.sax.ErrorHandler errorHandler)}.
447 * </li>
448 * <li>
449 * {@code false}: the implementation will processing XML according to the XML specifications without
450 * regard to possible implementation limits.
451 * </li>
452 * </ul>
453 *
454 * @param name Feature name.
455 * @param value Is feature state {@code true} or {@code false}.
456 *
457 * @throws ParserConfigurationException if this {@code DocumentBuilderFactory} or the {@code DocumentBuilder}s
458 * it creates cannot support this feature.
459 * @throws NullPointerException If the {@code name} parameter is null.
460 * @since 1.5
461 */
462 public abstract void setFeature(String name, boolean value)
463 throws ParserConfigurationException;
464
465 /**
466 * Get the state of the named feature.
467 *
468 * <p>
469 * Feature names are fully qualified {@link java.net.URI}s.
470 * Implementations may define their own features.
471 * An {@link ParserConfigurationException} is thrown if this {@code DocumentBuilderFactory} or the
472 * {@code DocumentBuilder}s it creates cannot support the feature.
473 * It is possible for an {@code DocumentBuilderFactory} to expose a feature value but be unable to change its state.
474 *
475 * @param name Feature name.
476 *
477 * @return State of the named feature.
478 *
479 * @throws ParserConfigurationException if this {@code DocumentBuilderFactory}
480 * or the {@code DocumentBuilder}s it creates cannot support this feature.
481 * @since 1.5
482 */
483 public abstract boolean getFeature(String name)
484 throws ParserConfigurationException;
485
486
487 /**
488 * Gets the {@link Schema} object specified through
489 * the {@link #setSchema(Schema schema)} method.
490 *
491 * @return
492 * the {@link Schema} object that was last set through
493 * the {@link #setSchema(Schema)} method, or null
494 * if the method was not invoked since a {@link DocumentBuilderFactory}
495 * is created.
496 *
497 * @throws UnsupportedOperationException When implementation does not
498 * override this method.
499 *
500 * @since 1.5
501 */
502 public Schema getSchema() {
503 throw new UnsupportedOperationException(
504 "This parser does not support specification \""
505 + this.getClass().getPackage().getSpecificationTitle()
506 + "\" version \""
507 + this.getClass().getPackage().getSpecificationVersion()
508 + "\""
509 );
510
511 }
512
513 /**
514 * Set the {@link Schema} to be used by parsers created
515 * from this factory.
516 *
517 * <p>
518 * When a {@link Schema} is non-null, a parser will use a validator
519 * created from it to validate documents before it passes information
520 * down to the application.
521 *
522 * <p>When errors are found by the validator, the parser is responsible
523 * to report them to the user-specified {@link org.xml.sax.ErrorHandler}
524 * (or if the error handler is not set, ignore them or throw them), just
525 * like any other errors found by the parser itself.
526 * In other words, if the user-specified {@link org.xml.sax.ErrorHandler}
527 * is set, it must receive those errors, and if not, they must be
528 * treated according to the implementation specific
529 * default error handling rules.
530 *
531 * <p>
532 * A validator may modify the outcome of a parse (for example by
533 * adding default values that were missing in documents), and a parser
534 * is responsible to make sure that the application will receive
535 * modified DOM trees.
536 *
537 * <p>
538 * Initially, null is set as the {@link Schema}.
539 *
540 * <p>
541 * This processing will take effect even if
542 * the {@link #isValidating()} method returns {@code false}.
543 *
544 * <p>It is an error to use
545 * the {@code http://java.sun.com/xml/jaxp/properties/schemaSource}
546 * property and/or the {@code http://java.sun.com/xml/jaxp/properties/schemaLanguage}
547 * property in conjunction with a {@link Schema} object.
548 * Such configuration will cause a {@link ParserConfigurationException}
549 * exception when the {@link #newDocumentBuilder()} is invoked.
550 *
551 *
552 * <h3>Note for implementors</h3>
553 *
554 * <p>
555 * A parser must be able to work with any {@link Schema}
556 * implementation. However, parsers and schemas are allowed
557 * to use implementation-specific custom mechanisms
558 * as long as they yield the result described in the specification.
559 *
560 *
561 * @param schema {@code Schema} to use or {@code null}
562 * to remove a schema.
563 *
564 * @throws UnsupportedOperationException When implementation does not
565 * override this method.
566 *
567 * @since 1.5
568 */
569 public void setSchema(Schema schema) {
570 throw new UnsupportedOperationException(
571 "This parser does not support specification \""
572 + this.getClass().getPackage().getSpecificationTitle()
573 + "\" version \""
574 + this.getClass().getPackage().getSpecificationVersion()
575 + "\""
576 );
577 }
578
579
580
581 /**
582 * Set state of XInclude processing.
583 *
584 * <p>If XInclude markup is found in the document instance, should it be
585 * processed as specified in <a href="http://www.w3.org/TR/xinclude/">
586 * XML Inclusions (XInclude) Version 1.0</a>.
587 *
588 * <p>XInclude processing defaults to {@code false}.
589 *
590 * @param state Set XInclude processing to {@code true} or
591 * {@code false}
592 *
593 * @throws UnsupportedOperationException When implementation does not
594 * override this method.
595 *
596 * @since 1.5
597 */
598 public void setXIncludeAware(final boolean state) {
599 if (state) {
600 throw new UnsupportedOperationException(" setXIncludeAware " +
601 "is not supported on this JAXP" +
602 " implementation or earlier: " + this.getClass());
603 }
604 }
605
606 /**
607 * Get state of XInclude processing.
608 *
609 * @return current state of XInclude processing
610 *
611 * @throws UnsupportedOperationException When implementation does not
612 * override this method.
613 *
614 * @since 1.5
615 */
616 public boolean isXIncludeAware() {
617 throw new UnsupportedOperationException(
618 "This parser does not support specification \""
619 + this.getClass().getPackage().getSpecificationTitle()
620 + "\" version \""
621 + this.getClass().getPackage().getSpecificationVersion()
622 + "\""
623 );
624 }
625 }