23 * questions.
24 */
25
26 package javax.xml.parsers;
27
28 import javax.xml.validation.Schema;
29
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 * @version $Revision: 1.9 $, $Date: 2010/05/25 16:19:44 $
38
39 */
40
41 public abstract class DocumentBuilderFactory {
42
43 /** The default property name according to the JAXP spec */
44 private static final String DEFAULT_PROPERTY_NAME = "javax.xml.parsers.DocumentBuilderFactory";
45
46 private boolean validating = false;
47 private boolean namespaceAware = false;
48 private boolean whitespace = false;
49 private boolean expandEntityRef = true;
50 private boolean ignoreComments = false;
51 private boolean coalescing = false;
52
53 private boolean canonicalState = false;
54
55 /**
56 * <p>Protected constructor to prevent instantiation.
57 * Use {@link #newInstance()}.</p>
58 */
59 protected DocumentBuilderFactory () {
60 }
61
62 /**
63 * Obtain a new instance of a
64 * <code>DocumentBuilderFactory</code>. This static method creates
65 * a new factory instance.
66 * This method uses the following ordered lookup procedure to determine
67 * the <code>DocumentBuilderFactory</code> implementation class to
68 * load:
69 * <ul>
70 * <li>
71 * Use the <code>javax.xml.parsers.DocumentBuilderFactory</code> system
72 * property.
73 * </li>
74 * <li>
75 * Use the properties file "lib/jaxp.properties" in the JRE directory.
76 * This configuration file is in standard <code>java.util.Properties
77 * </code> format and contains the fully qualified name of the
78 * implementation class with the key being the system property defined
79 * above.
80 *
81 * The jaxp.properties file is read only once by the JAXP implementation
82 * and it's values are then cached for future use. If the file does not exist
83 * when the first attempt is made to read from it, no further attempts are
84 * made to check for its existence. It is not possible to change the value
85 * of any property in jaxp.properties after it has been read for the first time.
86 * </li>
87 * <li>
88 * Use the Services API (as detailed in the JAR specification), if
89 * available, to determine the classname. The Services API will look
90 * for a classname in the file
91 * <code>META-INF/services/javax.xml.parsers.DocumentBuilderFactory</code>
92 * in jars available to the runtime.
93 * </li>
94 * <li>
95 * Platform default <code>DocumentBuilderFactory</code> instance.
96 * </li>
97 * </ul>
98 *
99 * Once an application has obtained a reference to a
100 * <code>DocumentBuilderFactory</code> it can use the factory to
101 * configure and obtain parser instances.
102 *
103 *
104 * <h2>Tip for Trouble-shooting</h2>
105 * <p>Setting the <code>jaxp.debug</code> system property will cause
106 * this method to print a lot of debug messages
107 * to <code>System.err</code> about what it is doing and where it is looking at.</p>
108 *
109 * <p> If you have problems loading {@link DocumentBuilder}s, try:</p>
110 * <pre>
111 * java -Djaxp.debug=1 YourProgram ....
112 * </pre>
113 *
114 * @return New instance of a <code>DocumentBuilderFactory</code>
115 *
116 * @throws FactoryConfigurationError if the implementation is not
117 * available or cannot be instantiated.
118 */
119 public static DocumentBuilderFactory newInstance() {
120 try {
121 return (DocumentBuilderFactory) FactoryFinder.find(
122 /* The default property name according to the JAXP spec */
123 "javax.xml.parsers.DocumentBuilderFactory",
124 /* The fallback implementation class name */
125 "com.sun.org.apache.xerces.internal.jaxp.DocumentBuilderFactoryImpl");
126 } catch (FactoryFinder.ConfigurationError e) {
127 throw new FactoryConfigurationError(e.getException(),
128 e.getMessage());
129 }
130
131 }
132
133 /**
134 * <p>Obtain a new instance of a <code>DocumentBuilderFactory</code> 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.</p>
138 *
139 * <p>Once an application has obtained a reference to a <code>DocumentBuilderFactory</code>
140 * it can use the factory to configure and obtain parser instances.</p>
141 *
142 *
143 * <h2>Tip for Trouble-shooting</h2>
144 * <p>Setting the <code>jaxp.debug</code> system property will cause
145 * this method to print a lot of debug messages
146 * to <code>System.err</code> 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</code>.
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</code>
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 try {
169 //do not fallback if given classloader can't find the class, throw exception
170 return (DocumentBuilderFactory) FactoryFinder.newInstance(factoryClassName, classLoader, false);
171 } catch (FactoryFinder.ConfigurationError e) {
172 throw new FactoryConfigurationError(e.getException(),
173 e.getMessage());
174 }
175 }
176
177 /**
178 * Creates a new instance of a {@link javax.xml.parsers.DocumentBuilder}
179 * using the currently configured parameters.
180 *
181 * @return A new instance of a DocumentBuilder.
182 *
183 * @throws ParserConfigurationException if a DocumentBuilder
184 * cannot be created which satisfies the configuration requested.
185 */
186
187 public abstract DocumentBuilder newDocumentBuilder()
188 throws ParserConfigurationException;
189
190
191 /**
192 * Specifies that the parser produced by this code will
193 * provide support for XML namespaces. By default the value of this is set
194 * to <code>false</code>
434 *
435 * <p>
436 * Feature names are fully qualified {@link java.net.URI}s.
437 * Implementations may define their own features.
438 * An {@link ParserConfigurationException} is thrown if this <code>DocumentBuilderFactory</code> or the
439 * <code>DocumentBuilder</code>s it creates cannot support the feature.
440 * It is possible for an <code>DocumentBuilderFactory</code> to expose a feature value but be unable to change its state.
441 * </p>
442 *
443 * @param name Feature name.
444 *
445 * @return State of the named feature.
446 *
447 * @throws ParserConfigurationException if this <code>DocumentBuilderFactory</code>
448 * or the <code>DocumentBuilder</code>s it creates cannot support this feature.
449 */
450 public abstract boolean getFeature(String name)
451 throws ParserConfigurationException;
452
453
454 /** <p>Get current state of canonicalization.</p>
455 *
456 * @return current state canonicalization control
457 */
458 /*
459 public boolean getCanonicalization() {
460 return canonicalState;
461 }
462 */
463
464
465 /**
466 * Gets the {@link Schema} object specified through
467 * the {@link #setSchema(Schema schema)} method.
468 *
469 * @return
470 * the {@link Schema} object that was last set through
471 * the {@link #setSchema(Schema)} method, or null
472 * if the method was not invoked since a {@link DocumentBuilderFactory}
473 * is created.
474 *
475 * @throws UnsupportedOperationException When implementation does not
476 * override this method.
477 *
478 * @since 1.5
479 */
480 public Schema getSchema() {
481 throw new UnsupportedOperationException(
482 "This parser does not support specification \""
483 + this.getClass().getPackage().getSpecificationTitle()
484 + "\" version \""
485 + this.getClass().getPackage().getSpecificationVersion()
486 + "\""
487 );
488
489 }
490
491 /* <p>Set canonicalization control to <code>true</code> or
492 * </code>false</code>.</p>
493 *
494 * @param state of canonicalization
495 */
496 /*
497 public void setCanonicalization(boolean state) {
498 canonicalState = state;
499 }
500 */
501
502 /**
503 * <p>Set the {@link Schema} to be used by parsers created
504 * from this factory.
505 *
506 * <p>
507 * When a {@link Schema} is non-null, a parser will use a validator
508 * created from it to validate documents before it passes information
509 * down to the application.
510 *
511 * <p>When errors are found by the validator, the parser is responsible
512 * to report them to the user-specified {@link org.xml.sax.ErrorHandler}
513 * (or if the error handler is not set, ignore them or throw them), just
514 * like any other errors found by the parser itself.
515 * In other words, if the user-specified {@link org.xml.sax.ErrorHandler}
516 * is set, it must receive those errors, and if not, they must be
517 * treated according to the implementation specific
518 * default error handling rules.
519 *
520 * <p>
521 * A validator may modify the outcome of a parse (for example by
|
23 * questions.
24 */
25
26 package javax.xml.parsers;
27
28 import javax.xml.validation.Schema;
29
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 * @version $Revision: 1.9 $, $Date: 2010/05/25 16:19:44 $
38
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 * <p>Protected constructor to prevent instantiation.
52 * Use {@link #newInstance()}.</p>
53 */
54 protected DocumentBuilderFactory () {
55 }
56
57 /**
58 * Obtain a new instance of a
59 * <code>DocumentBuilderFactory</code>. This static method creates
60 * a new factory instance.
61 * This method uses the following ordered lookup procedure to determine
62 * the <code>DocumentBuilderFactory</code> implementation class to
63 * load:
64 * <ul>
65 * <li>
66 * Use the <code>javax.xml.parsers.DocumentBuilderFactory</code> system
67 * property.
68 * </li>
69 * <li>
70 * Use the properties file "lib/jaxp.properties" in the JRE directory.
71 * This configuration file is in standard <code>java.util.Properties
72 * </code> format and contains the fully qualified name of the
73 * implementation class with the key being the system property defined
74 * above.
75 *
76 * The jaxp.properties file is read only once by the JAXP implementation
77 * and it's 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>
83 * Uses the service-provider loading facilities, defined by the
84 * {@link java.util.ServiceLoader} class, to attempt to locate and load an
85 * implementation of the service.
86 * </li>
87 * <li>
88 * Otherwise, the system-default implementation is returned.
89 * </li>
90 * </ul>
91 *
92 * Once an application has obtained a reference to a
93 * <code>DocumentBuilderFactory</code> it can use the factory to
94 * configure and obtain parser instances.
95 *
96 *
97 * <h2>Tip for Trouble-shooting</h2>
98 * <p>Setting the <code>jaxp.debug</code> system property will cause
99 * this method to print a lot of debug messages
100 * to <code>System.err</code> about what it is doing and where it is looking at.</p>
101 *
102 * <p> If you have problems loading {@link DocumentBuilder}s, try:</p>
103 * <pre>
104 * java -Djaxp.debug=1 YourProgram ....
105 * </pre>
106 *
107 * @return New instance of a <code>DocumentBuilderFactory</code>
108 *
109 * @throws FactoryConfigurationError in case of {@linkplain
110 * java.util.ServiceConfigurationError service configuration error} or if
111 * the implementation is not available or cannot be instantiated.
112 */
113 public static DocumentBuilderFactory newInstance() {
114 return FactoryFinder.find(
115 /* The default property name according to the JAXP spec */
116 DocumentBuilderFactory.class, // "javax.xml.parsers.DocumentBuilderFactory"
117 /* The fallback implementation class name */
118 "com.sun.org.apache.xerces.internal.jaxp.DocumentBuilderFactoryImpl");
119 }
120
121 /**
122 * <p>Obtain a new instance of a <code>DocumentBuilderFactory</code> from class name.
123 * This function is useful when there are multiple providers in the classpath.
124 * It gives more control to the application as it can specify which provider
125 * should be loaded.</p>
126 *
127 * <p>Once an application has obtained a reference to a <code>DocumentBuilderFactory</code>
128 * it can use the factory to configure and obtain parser instances.</p>
129 *
130 *
131 * <h2>Tip for Trouble-shooting</h2>
132 * <p>Setting the <code>jaxp.debug</code> system property will cause
133 * this method to print a lot of debug messages
134 * to <code>System.err</code> about what it is doing and where it is looking at.</p>
135 *
136 * <p> If you have problems try:</p>
137 * <pre>
138 * java -Djaxp.debug=1 YourProgram ....
139 * </pre>
140 *
141 * @param factoryClassName fully qualified factory class name that provides implementation of <code>javax.xml.parsers.DocumentBuilderFactory</code>.
142 *
143 * @param classLoader <code>ClassLoader</code> used to load the factory class. If <code>null</code>
144 * current <code>Thread</code>'s context classLoader is used to load the factory class.
145 *
146 * @return New instance of a <code>DocumentBuilderFactory</code>
147 *
148 * @throws FactoryConfigurationError if <code>factoryClassName</code> is <code>null</code>, or
149 * the factory class cannot be loaded, instantiated.
150 *
151 * @see #newInstance()
152 *
153 * @since 1.6
154 */
155 public static DocumentBuilderFactory newInstance(String factoryClassName, ClassLoader classLoader){
156 //do not fallback if given classloader can't find the class, throw exception
157 return FactoryFinder.newInstance(DocumentBuilderFactory.class,
158 factoryClassName, classLoader, false);
159 }
160
161 /**
162 * Creates a new instance of a {@link javax.xml.parsers.DocumentBuilder}
163 * using the currently configured parameters.
164 *
165 * @return A new instance of a DocumentBuilder.
166 *
167 * @throws ParserConfigurationException if a DocumentBuilder
168 * cannot be created which satisfies the configuration requested.
169 */
170
171 public abstract DocumentBuilder newDocumentBuilder()
172 throws ParserConfigurationException;
173
174
175 /**
176 * Specifies that the parser produced by this code will
177 * provide support for XML namespaces. By default the value of this is set
178 * to <code>false</code>
418 *
419 * <p>
420 * Feature names are fully qualified {@link java.net.URI}s.
421 * Implementations may define their own features.
422 * An {@link ParserConfigurationException} is thrown if this <code>DocumentBuilderFactory</code> or the
423 * <code>DocumentBuilder</code>s it creates cannot support the feature.
424 * It is possible for an <code>DocumentBuilderFactory</code> to expose a feature value but be unable to change its state.
425 * </p>
426 *
427 * @param name Feature name.
428 *
429 * @return State of the named feature.
430 *
431 * @throws ParserConfigurationException if this <code>DocumentBuilderFactory</code>
432 * or the <code>DocumentBuilder</code>s it creates cannot support this feature.
433 */
434 public abstract boolean getFeature(String name)
435 throws ParserConfigurationException;
436
437
438 /**
439 * Gets the {@link Schema} object specified through
440 * the {@link #setSchema(Schema schema)} method.
441 *
442 * @return
443 * the {@link Schema} object that was last set through
444 * the {@link #setSchema(Schema)} method, or null
445 * if the method was not invoked since a {@link DocumentBuilderFactory}
446 * is created.
447 *
448 * @throws UnsupportedOperationException When implementation does not
449 * override this method.
450 *
451 * @since 1.5
452 */
453 public Schema getSchema() {
454 throw new UnsupportedOperationException(
455 "This parser does not support specification \""
456 + this.getClass().getPackage().getSpecificationTitle()
457 + "\" version \""
458 + this.getClass().getPackage().getSpecificationVersion()
459 + "\""
460 );
461
462 }
463
464 /**
465 * <p>Set the {@link Schema} to be used by parsers created
466 * from this factory.
467 *
468 * <p>
469 * When a {@link Schema} is non-null, a parser will use a validator
470 * created from it to validate documents before it passes information
471 * down to the application.
472 *
473 * <p>When errors are found by the validator, the parser is responsible
474 * to report them to the user-specified {@link org.xml.sax.ErrorHandler}
475 * (or if the error handler is not set, ignore them or throw them), just
476 * like any other errors found by the parser itself.
477 * In other words, if the user-specified {@link org.xml.sax.ErrorHandler}
478 * is set, it must receive those errors, and if not, they must be
479 * treated according to the implementation specific
480 * default error handling rules.
481 *
482 * <p>
483 * A validator may modify the outcome of a parse (for example by
|