17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package javax.xml.parsers;
27
28 import javax.xml.validation.Schema;
29
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>
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
|
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package javax.xml.parsers;
27
28 import javax.xml.validation.Schema;
29
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.10 $, $Date: 2010-11-01 04:36:09 $
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>
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 * Uses the service-provider loading facilities, defined by the {@link java.util.ServiceLoader} class, to attempt
89 * to locate and load an implementation of the service. If there are providers other than the implementation specific
90 * default located, then the first provider that is not the default is instantiated and returned; Otherwise
91 * the default implementation is returned if it is on the classpath or installed as a module.
92 *
93 * If a misconfigured provider is encountered and {@link java.util.ServiceConfigurationError} is thrown, the error will be wrapped
94 * in a {@link javax.xml.parsers.FactoryConfigurationException}.</p>
95 * </li>
96 * <li>
97 * Platform default <code>DocumentBuilderFactory</code> instance.
98 * </li>
99 * </ul>
100 *
101 * Once an application has obtained a reference to a
102 * <code>DocumentBuilderFactory</code> it can use the factory to
103 * configure and obtain parser instances.
104 *
105 *
106 * <h2>Tip for Trouble-shooting</h2>
107 * <p>Setting the <code>jaxp.debug</code> system property will cause
108 * this method to print a lot of debug messages
109 * to <code>System.err</code> about what it is doing and where it is looking at.</p>
110 *
111 * <p> If you have problems loading {@link DocumentBuilder}s, try:</p>
112 * <pre>
113 * java -Djaxp.debug=1 YourProgram ....
114 * </pre>
115 *
116 * @return New instance of a <code>DocumentBuilderFactory</code>
117 *
118 * @throws FactoryConfigurationError if the implementation is not
119 * available or cannot be instantiated.
120 */
121 public static DocumentBuilderFactory newInstance() {
122 // try {
123 return (DocumentBuilderFactory) FactoryFinder.find(DocumentBuilderFactory.class,
124 /* The default property name according to the JAXP spec */
125 "javax.xml.parsers.DocumentBuilderFactory",
126 /* The fallback implementation class name */
127 "com.sun.org.apache.xerces.internal.jaxp.DocumentBuilderFactoryImpl");
128 // } catch (FactoryConfigurationError e) {
129 // throw e;
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 (FactoryConfigurationError e) {
172 throw e;
173 }
174 }
175
176 /**
177 * Creates a new instance of a {@link javax.xml.parsers.DocumentBuilder}
178 * using the currently configured parameters.
179 *
180 * @return A new instance of a DocumentBuilder.
181 *
182 * @throws ParserConfigurationException if a DocumentBuilder
183 * cannot be created which satisfies the configuration requested.
184 */
185
186 public abstract DocumentBuilder newDocumentBuilder()
187 throws ParserConfigurationException;
188
189
190 /**
191 * Specifies that the parser produced by this code will
192 * provide support for XML namespaces. By default the value of this is set
|