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 Jeff Suttor
36 * @author Neeraj Bajaj
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>
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 * <h4>Tip for Trouble-shooting</h4>
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 ....
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}
|
1 /*
2 * Copyright (c) 2000, 2019, 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 Jeff Suttor
36 * @author Neeraj Bajaj
37 *
38 * @since 1.4
39 */
40
41 public abstract class DocumentBuilderFactory {
42 private static final String DEFAULT_IMPL =
43 "com.sun.org.apache.xerces.internal.jaxp.DocumentBuilderFactoryImpl";
44 private boolean validating = false;
45 private boolean namespaceAware = false;
46 private boolean whitespace = false;
47 private boolean expandEntityRef = true;
48 private boolean ignoreComments = false;
49 private boolean coalescing = false;
50
51 /**
52 * Protected constructor to prevent instantiation.
53 * Use {@link #newInstance()}.
54 */
55 protected DocumentBuilderFactory () {
56 }
57
58 /**
59 * Creates a new NamespaceAware instance of the {@code DocumentBuilderFactory}
60 * builtin system-default implementation. Parsers produced by the factory
61 * instance provides support for XML namespaces by default.
62 *
63 * @implSpec
64 * In addition to creating a factory instance using the same process as
65 * {@link #newDefaultInstance()}, this method must set NamespaceAware to true.
66 *
67 * @return a new instance of the {@code DocumentBuilderFactory} builtin
68 * system-default implementation.
69 *
70 * @since 13
71 */
72 public static DocumentBuilderFactory newDefaultNSInstance() {
73 return makeNSAware(new DocumentBuilderFactoryImpl());
74 }
75
76 /**
77 * Creates a new NamespaceAware instance of a {@code DocumentBuilderFactory}.
78 * Parsers produced by the factory instance provides support for XML namespaces
79 * by default.
80 *
81 * @implSpec
82 * In addition to creating a factory instance using the same process as
83 * {@link #newInstance()}, this method must set NamespaceAware to true.
84 *
85 * @return a new instance of a {@code DocumentBuilderFactory}
86 *
87 * @throws FactoryConfigurationError in case of {@linkplain
88 * java.util.ServiceConfigurationError service configuration error}
89 * or if the implementation is not available or cannot be instantiated.
90 *
91 * @since 13
92 */
93 public static DocumentBuilderFactory newNSInstance() {
94 return makeNSAware(FactoryFinder.find(DocumentBuilderFactory.class, DEFAULT_IMPL));
95 }
96
97 /**
98 * Creates a new NamespaceAware instance of a {@code DocumentBuilderFactory}
99 * from the class name. Parsers produced by the factory instance provides
100 * support for XML namespaces by default.
101 *
102 * @implSpec
103 * In addition to creating a factory instance using the same process as
104 * {@link #newInstance(java.lang.String, java.lang.ClassLoader)}, this method
105 * must set NamespaceAware to true.
106 *
107 * @param factoryClassName a fully qualified factory class name that provides
108 * implementation of
109 * {@code javax.xml.parsers.DocumentBuilderFactory}.
110 *
111 * @param classLoader the {@code ClassLoader} used to load the factory class.
112 * If it is {@code null}, the current {@code Thread}'s
113 * context classLoader is used to load the factory class.
114 *
115 * @return a new instance of a {@code DocumentBuilderFactory}
116 *
117 * @throws FactoryConfigurationError if {@code factoryClassName} is {@code null}, or
118 * the factory class cannot be loaded, instantiated.
119 *
120 * @since 13
121 */
122 public static DocumentBuilderFactory newNSInstance(String factoryClassName,
123 ClassLoader classLoader) {
124 return makeNSAware(FactoryFinder.newInstance(
125 DocumentBuilderFactory.class, factoryClassName, classLoader, false));
126 }
127
128 /**
129 * Creates a new instance of the {@code DocumentBuilderFactory} builtin
130 * system-default implementation.
131 *
132 * @return A new instance of the {@code DocumentBuilderFactory} builtin
133 * system-default implementation.
134 *
135 * @since 9
136 */
137 public static DocumentBuilderFactory newDefaultInstance() {
138 return new DocumentBuilderFactoryImpl();
139 }
140
141 /**
142 * Obtain a new instance of a
143 * {@code DocumentBuilderFactory}. This static method creates
144 * a new factory instance.
145 * This method uses the following ordered lookup procedure to determine
146 * the {@code DocumentBuilderFactory} implementation class to
147 * load:
148 * <ul>
195 * this method to print a lot of debug messages
196 * to {@code System.err} about what it is doing and where it is looking at.
197 *
198 * <p>
199 * If you have problems loading {@link DocumentBuilder}s, try:
200 * <pre>
201 * java -Djaxp.debug=1 YourProgram ....
202 * </pre>
203 *
204 * @return New instance of a {@code DocumentBuilderFactory}
205 *
206 * @throws FactoryConfigurationError in case of {@linkplain
207 * java.util.ServiceConfigurationError service configuration error} or if
208 * the implementation is not available or cannot be instantiated.
209 */
210 public static DocumentBuilderFactory newInstance() {
211 return FactoryFinder.find(
212 /* The default property name according to the JAXP spec */
213 DocumentBuilderFactory.class, // "javax.xml.parsers.DocumentBuilderFactory"
214 /* The fallback implementation class name */
215 DEFAULT_IMPL);
216 }
217
218 /**
219 * Obtain a new instance of a {@code DocumentBuilderFactory} from class name.
220 * This function is useful when there are multiple providers in the classpath.
221 * It gives more control to the application as it can specify which provider
222 * should be loaded.
223 *
224 * <p>Once an application has obtained a reference to a {@code DocumentBuilderFactory}
225 * it can use the factory to configure and obtain parser instances.
226 *
227 *
228 * <h4>Tip for Trouble-shooting</h4>
229 * <p>Setting the {@code jaxp.debug} system property will cause
230 * this method to print a lot of debug messages
231 * to {@code System.err} about what it is doing and where it is looking at.
232 *
233 * <p> If you have problems try:
234 * <pre>
235 * java -Djaxp.debug=1 YourProgram ....
237 *
238 * @param factoryClassName fully qualified factory class name that provides
239 * implementation of {@code javax.xml.parsers.DocumentBuilderFactory}.
240 *
241 * @param classLoader {@code ClassLoader} used to load the factory class. If {@code null}
242 * current {@code Thread}'s context classLoader is used to load the factory class.
243 *
244 * @return New instance of a {@code DocumentBuilderFactory}
245 *
246 * @throws FactoryConfigurationError if {@code factoryClassName} is {@code null}, or
247 * the factory class cannot be loaded, instantiated.
248 *
249 * @see #newInstance()
250 *
251 * @since 1.6
252 */
253 public static DocumentBuilderFactory newInstance(String factoryClassName, ClassLoader classLoader){
254 //do not fallback if given classloader can't find the class, throw exception
255 return FactoryFinder.newInstance(DocumentBuilderFactory.class,
256 factoryClassName, classLoader, false);
257 }
258
259 private static DocumentBuilderFactory makeNSAware(DocumentBuilderFactory dbf) {
260 dbf.setNamespaceAware(true);
261 return dbf;
262 }
263
264 /**
265 * Creates a new instance of a {@link javax.xml.parsers.DocumentBuilder}
266 * using the currently configured parameters.
267 *
268 * @return A new instance of a DocumentBuilder.
269 *
270 * @throws ParserConfigurationException if a DocumentBuilder
271 * cannot be created which satisfies the configuration requested.
272 */
273
274 public abstract DocumentBuilder newDocumentBuilder()
275 throws ParserConfigurationException;
276
277
278 /**
279 * Specifies that the parser produced by this code will
280 * provide support for XML namespaces. By default the value of this is set
281 * to {@code false}
|