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 * <p></p>
65 * <ul>
66 * <li>
67 * Use the <code>javax.xml.parsers.DocumentBuilderFactory</code> system
68 * property.
69 * </li>
70 * <li>
71 * Use the properties file "lib/jaxp.properties" in the JRE directory.
72 * This configuration file is in standard <code>java.util.Properties
73 * </code> format and contains the fully qualified name of the
74 * implementation class with the key being the system property defined
75 * above.
76 *
77 * The jaxp.properties file is read only once by the JAXP implementation
78 * and it's 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>
84 * Uses the service-provider loading facilities, defined by the
85 * {@link java.util.ServiceLoader} class, to attempt to locate and load an
86 * implementation of the service. If there are providers other than the
87 * implementation system default located, then the first provider that is
88 * not the default is instantiated and returned.
89 * </li>
90 * <li>
91 * Otherwise the system default implementation is returned.
92 * </li>
93 * </ul>
94 *
95 * Once an application has obtained a reference to a
96 * <code>DocumentBuilderFactory</code> it can use the factory to
97 * configure and obtain parser instances.
98 *
99 *
100 * <h2>Tip for Trouble-shooting</h2>
101 * <p>Setting the <code>jaxp.debug</code> system property will cause
102 * this method to print a lot of debug messages
103 * to <code>System.err</code> about what it is doing and where it is looking at.</p>
104 *
105 * <p> If you have problems loading {@link DocumentBuilder}s, try:</p>
106 * <pre>
107 * java -Djaxp.debug=1 YourProgram ....
108 * </pre>
109 *
110 * @return New instance of a <code>DocumentBuilderFactory</code>
111 *
112 * @throws FactoryConfigurationError in case of {@linkplain
113 * java.util.ServiceConfigurationError service configuration error} or if
114 * the implementation is not available or cannot be instantiated.
115 */
116 public static DocumentBuilderFactory newInstance() {
117 return FactoryFinder.find(
118 /* The default property name according to the JAXP spec */
119 DocumentBuilderFactory.class, // "javax.xml.parsers.DocumentBuilderFactory"
120 /* The fallback implementation class name */
121 "com.sun.org.apache.xerces.internal.jaxp.DocumentBuilderFactoryImpl");
122 }
123
124 /**
125 * <p>Obtain a new instance of a <code>DocumentBuilderFactory</code> from class name.
126 * This function is useful when there are multiple providers in the classpath.
127 * It gives more control to the application as it can specify which provider
128 * should be loaded.</p>
129 *
130 * <p>Once an application has obtained a reference to a <code>DocumentBuilderFactory</code>
131 * it can use the factory to configure and obtain parser instances.</p>
132 *
133 *
134 * <h2>Tip for Trouble-shooting</h2>
135 * <p>Setting the <code>jaxp.debug</code> system property will cause
136 * this method to print a lot of debug messages
137 * to <code>System.err</code> about what it is doing and where it is looking at.</p>
138 *
139 * <p> If you have problems try:</p>
140 * <pre>
141 * java -Djaxp.debug=1 YourProgram ....
142 * </pre>
143 *
144 * @param factoryClassName fully qualified factory class name that provides implementation of <code>javax.xml.parsers.DocumentBuilderFactory</code>.
145 *
146 * @param classLoader <code>ClassLoader</code> used to load the factory class. If <code>null</code>
147 * current <code>Thread</code>'s context classLoader is used to load the factory class.
148 *
149 * @return New instance of a <code>DocumentBuilderFactory</code>
150 *
151 * @throws FactoryConfigurationError if <code>factoryClassName</code> is <code>null</code>, or
152 * the factory class cannot be loaded, instantiated.
153 *
154 * @see #newInstance()
155 *
156 * @since 1.6
157 */
158 public static DocumentBuilderFactory newInstance(String factoryClassName, ClassLoader classLoader){
159 //do not fallback if given classloader can't find the class, throw exception
160 return (DocumentBuilderFactory) FactoryFinder.newInstance(factoryClassName, classLoader, false);
161 }
162
163 /**
164 * Creates a new instance of a {@link javax.xml.parsers.DocumentBuilder}
165 * using the currently configured parameters.
166 *
167 * @return A new instance of a DocumentBuilder.
168 *
169 * @throws ParserConfigurationException if a DocumentBuilder
170 * cannot be created which satisfies the configuration requested.
171 */
172
173 public abstract DocumentBuilder newDocumentBuilder()
174 throws ParserConfigurationException;
175
176
177 /**
178 * Specifies that the parser produced by this code will
179 * provide support for XML namespaces. By default the value of this is set
180 * to <code>false</code>
420 *
421 * <p>
422 * Feature names are fully qualified {@link java.net.URI}s.
423 * Implementations may define their own features.
424 * An {@link ParserConfigurationException} is thrown if this <code>DocumentBuilderFactory</code> or the
425 * <code>DocumentBuilder</code>s it creates cannot support the feature.
426 * It is possible for an <code>DocumentBuilderFactory</code> to expose a feature value but be unable to change its state.
427 * </p>
428 *
429 * @param name Feature name.
430 *
431 * @return State of the named feature.
432 *
433 * @throws ParserConfigurationException if this <code>DocumentBuilderFactory</code>
434 * or the <code>DocumentBuilder</code>s it creates cannot support this feature.
435 */
436 public abstract boolean getFeature(String name)
437 throws ParserConfigurationException;
438
439
440 /**
441 * Gets the {@link Schema} object specified through
442 * the {@link #setSchema(Schema schema)} method.
443 *
444 * @return
445 * the {@link Schema} object that was last set through
446 * the {@link #setSchema(Schema)} method, or null
447 * if the method was not invoked since a {@link DocumentBuilderFactory}
448 * is created.
449 *
450 * @throws UnsupportedOperationException When implementation does not
451 * override this method.
452 *
453 * @since 1.5
454 */
455 public Schema getSchema() {
456 throw new UnsupportedOperationException(
457 "This parser does not support specification \""
458 + this.getClass().getPackage().getSpecificationTitle()
459 + "\" version \""
460 + this.getClass().getPackage().getSpecificationVersion()
461 + "\""
462 );
463
464 }
465
466 /**
467 * <p>Set the {@link Schema} to be used by parsers created
468 * from this factory.
469 *
470 * <p>
471 * When a {@link Schema} is non-null, a parser will use a validator
472 * created from it to validate documents before it passes information
473 * down to the application.
474 *
475 * <p>When errors are found by the validator, the parser is responsible
476 * to report them to the user-specified {@link org.xml.sax.ErrorHandler}
477 * (or if the error handler is not set, ignore them or throw them), just
478 * like any other errors found by the parser itself.
479 * In other words, if the user-specified {@link org.xml.sax.ErrorHandler}
480 * is set, it must receive those errors, and if not, they must be
481 * treated according to the implementation specific
482 * default error handling rules.
483 *
484 * <p>
485 * A validator may modify the outcome of a parse (for example by
|