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