1 /*
2 * Copyright (c) 2009, 2020, 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.stream;
27
28 import com.sun.xml.internal.stream.XMLInputFactoryImpl;
29 import javax.xml.stream.util.XMLEventAllocator;
30 import javax.xml.transform.Source;
31
32 /**
33 * Defines an abstract implementation of a factory for getting streams.
34 *
35 * The following table defines the standard properties of this specification.
36 * Each property varies in the level of support required by each implementation.
37 * The level of support required is described in the 'Required' column.
38 *
39 * <table class="striped">
40 * <caption>Configuration Parameters</caption>
41 * <thead>
42 * <tr>
43 * <th scope="col">Property Name</th>
44 * <th scope="col">Behavior</th>
45 * <th scope="col">Return type</th>
46 * <th scope="col">Default Value</th>
47 * <th scope="col">Required</th>
48 * </tr>
49 * </thead>
50 * <tbody>
51 * <tr><th scope="row">javax.xml.stream.isValidating</th><td>Turns on/off implementation specific DTD validation</td><td>Boolean</td><td>False</td><td>No</td></tr>
52 * <tr><th scope="row">javax.xml.stream.isNamespaceAware</th><td>Turns on/off namespace processing for XML 1.0 support</td><td>Boolean</td><td>True</td><td>True (required) / False (optional)</td></tr>
53 * <tr><th scope="row">javax.xml.stream.isCoalescing</th><td>Requires the processor to coalesce adjacent character data</td><td>Boolean</td><td>False</td><td>Yes</td></tr>
54 * <tr><th scope="row">javax.xml.stream.isReplacingEntityReferences</th><td>replace internal entity references with their replacement text and report them as characters</td><td>Boolean</td><td>True</td><td>Yes</td></tr>
55 *<tr><th scope="row">javax.xml.stream.isSupportingExternalEntities</th><td>Resolve external parsed entities</td><td>Boolean</td><td>Unspecified</td><td>Yes</td></tr>
56 *<tr><th scope="row">javax.xml.stream.supportDTD</th><td>Use this property to request processors that do not support DTDs</td><td>Boolean</td><td>True</td><td>Yes</td></tr>
57 *<tr><th scope="row">javax.xml.stream.reporter</th><td>sets/gets the impl of the XMLReporter </td><td>javax.xml.stream.XMLReporter</td><td>Null</td><td>Yes</td></tr>
58 *<tr><th scope="row">javax.xml.stream.resolver</th><td>sets/gets the impl of the XMLResolver interface</td><td>javax.xml.stream.XMLResolver</td><td>Null</td><td>Yes</td></tr>
59 *<tr><th scope="row">javax.xml.stream.allocator</th><td>sets/gets the impl of the XMLEventAllocator interface</td><td>javax.xml.stream.util.XMLEventAllocator</td><td>Null</td><td>Yes</td></tr>
60 * </tbody>
61 * </table>
62 *
63 *
64 * @version 1.2
65 * @author Copyright (c) 2009, 2015 by Oracle Corporation. All Rights Reserved.
66 * @see XMLOutputFactory
67 * @see XMLEventReader
68 * @see XMLStreamReader
69 * @see EventFilter
70 * @see XMLReporter
71 * @see XMLResolver
72 * @see javax.xml.stream.util.XMLEventAllocator
73 * @since 1.6
74 */
75
76 public abstract class XMLInputFactory {
77 /**
78 * The property used to turn on/off namespace support,
79 * this is to support XML 1.0 documents,
80 * only the true setting must be supported
81 */
82 public static final String IS_NAMESPACE_AWARE=
83 "javax.xml.stream.isNamespaceAware";
84
85 /**
86 * The property used to turn on/off implementation specific validation
87 */
88 public static final String IS_VALIDATING=
89 "javax.xml.stream.isValidating";
90
91 /**
92 * The property that requires the parser to coalesce adjacent character data sections
93 */
94 public static final String IS_COALESCING=
95 "javax.xml.stream.isCoalescing";
96
97 /**
98 * Requires the parser to replace internal
99 * entity references with their replacement
100 * text and report them as characters
101 */
102 public static final String IS_REPLACING_ENTITY_REFERENCES=
103 "javax.xml.stream.isReplacingEntityReferences";
104
105 /**
106 * The property that requires the parser to resolve external parsed entities
107 */
108 public static final String IS_SUPPORTING_EXTERNAL_ENTITIES=
109 "javax.xml.stream.isSupportingExternalEntities";
110
111 /**
112 * The property that requires the parser to support DTDs
113 */
114 public static final String SUPPORT_DTD=
115 "javax.xml.stream.supportDTD";
116
117 /**
118 * The property used to
119 * set/get the implementation of the XMLReporter interface
120 */
121 public static final String REPORTER=
122 "javax.xml.stream.reporter";
123
124 /**
125 * The property used to set/get the implementation of the XMLResolver
126 */
127 public static final String RESOLVER=
128 "javax.xml.stream.resolver";
129
130 /**
131 * The property used to set/get the implementation of the allocator
132 */
133 public static final String ALLOCATOR=
134 "javax.xml.stream.allocator";
135
136 static final String DEFAULIMPL = "com.sun.xml.internal.stream.XMLInputFactoryImpl";
137
138 /**
139 * Protected constructor to prevent instantiation.
140 * Use {@link #newFactory()} instead.
141 */
142 protected XMLInputFactory(){}
143
144 /**
145 * Creates a new instance of the {@code XMLInputFactory} builtin
146 * system-default implementation.
147 *
148 * @return A new instance of the {@code XMLInputFactory} builtin
149 * system-default implementation.
150 *
151 * @since 9
152 */
153 public static XMLInputFactory newDefaultFactory() {
154 return new XMLInputFactoryImpl();
155 }
156
157 /**
158 * Creates a new instance of the factory in exactly the same manner as the
159 * {@link #newFactory()} method.
160 * @return an instance of the {@code XMLInputFactory}
161 * @throws FactoryConfigurationError if an instance of this factory cannot be loaded
162 */
163 public static XMLInputFactory newInstance()
164 throws FactoryConfigurationError
165 {
166 return FactoryFinder.find(XMLInputFactory.class, DEFAULIMPL);
167 }
168
169 /**
170 * Create a new instance of the factory.
171 * <p>
172 * This static method creates a new factory instance.
173 * This method uses the following ordered lookup procedure to determine
174 * the XMLInputFactory implementation class to load:
175 *
176 * <ul>
177 * <li>
178 * <p>Use the javax.xml.stream.XMLInputFactory system property.
179 * </li>
180 * <li>
181 * <p>Use the configuration file "stax.properties". The file is in standard
182 * {@link java.util.Properties} format and typically located in the
183 * {@code conf} directory of the Java installation. It contains the fully qualified
184 * name of the implementation class with the key being the system property
185 * defined above.
186 *
187 * <p>The stax.properties file is read only once by the implementation
188 * and its values are then cached for future use. If the file does not exist
189 * when the first attempt is made to read from it, no further attempts are
190 * made to check for its existence. It is not possible to change the value
191 * of any property in stax.properties after it has been read for the first time.
192 *
193 * <p>
194 * Use the jaxp configuration file "jaxp.properties". The file is in the same
195 * format as stax.properties and will only be read if stax.properties does
196 * not exist.
197 * </li>
198 * <li>
199 * <p>Use the service-provider loading facility, defined by the
200 * {@link java.util.ServiceLoader} class, to attempt to locate and load an
201 * implementation of the service using the {@linkplain
202 * java.util.ServiceLoader#load(java.lang.Class) default loading mechanism}:
203 * the service-provider loading facility will use the {@linkplain
204 * java.lang.Thread#getContextClassLoader() current thread's context class loader}
205 * to attempt to load the service. If the context class
206 * loader is null, the {@linkplain
207 * ClassLoader#getSystemClassLoader() system class loader} will be used.
208 * </li>
209 * <li>
210 * <p>Otherwise, the {@linkplain #newDefaultFactory() system-default}
211 * implementation is returned.
212 * </li>
213 * </ul>
214 * <p>
215 * Once an application has obtained a reference to a XMLInputFactory it
216 * can use the factory to configure and obtain stream instances.
217 *
218 * @return an instance of the {@code XMLInputFactory}
219 * @throws FactoryConfigurationError in case of {@linkplain
220 * java.util.ServiceConfigurationError service configuration error} or if
221 * the implementation is not available or cannot be instantiated.
222 */
223 public static XMLInputFactory newFactory()
224 throws FactoryConfigurationError
225 {
226 return FactoryFinder.find(XMLInputFactory.class, DEFAULIMPL);
227 }
228
229 /**
230 * Create a new instance of the factory.
231 *
232 * @param factoryId Name of the factory to find, same as
233 * a property name
234 * @param classLoader classLoader to use
235 * @return the factory implementation
236 * @throws FactoryConfigurationError if an instance of this factory cannot be loaded
237 *
238 * @deprecated This method has been deprecated to maintain API consistency.
239 * All newInstance methods have been replaced with corresponding
240 * newFactory methods. The replacement {@link
241 * #newFactory(java.lang.String, java.lang.ClassLoader)} method
242 * defines no changes in behavior.
243 */
244 @Deprecated(since="1.7")
245 public static XMLInputFactory newInstance(String factoryId,
246 ClassLoader classLoader)
247 throws FactoryConfigurationError {
248 //do not fallback if given classloader can't find the class, throw exception
249 return FactoryFinder.find(XMLInputFactory.class, factoryId, classLoader, null);
250 }
251
252 /**
253 * Create a new instance of the factory.
254 * If the classLoader argument is null, then the ContextClassLoader is used.
255 * <p>
256 * This method uses the following ordered lookup procedure to determine
257 * the XMLInputFactory implementation class to load:
258 * <ul>
259 * <li>
260 * <p>
261 * Use the value of the system property identified by {@code factoryId}.
262 * </li>
263 * <li>
264 * <p>
265 * Use the configuration file "stax.properties". The file is in standard
266 * {@link java.util.Properties} format and typically located in the
267 * {@code conf} directory of the Java installation. It contains the fully qualified
268 * name of the implementation class with the key being the system property
269 * defined above.
270 *
271 * <p>
272 * The stax.properties file is read only once by the implementation
273 * and its values are then cached for future use. If the file does not exist
274 * when the first attempt is made to read from it, no further attempts are
275 * made to check for its existence. It is not possible to change the value
276 * of any property in stax.properties after it has been read for the first time.
277 *
278 * <p>
279 * Use the jaxp configuration file "jaxp.properties". The file is in the same
280 * format as stax.properties and will only be read if stax.properties does
281 * not exist.
282 * </li>
283 * <li>
284 * <p>
285 * If {@code factoryId} is "javax.xml.stream.XMLInputFactory",
286 * use the service-provider loading facility, defined by the
287 * {@link java.util.ServiceLoader} class, to attempt to {@linkplain
288 * java.util.ServiceLoader#load(java.lang.Class, java.lang.ClassLoader) locate and load}
289 * an implementation of the service using the specified {@code ClassLoader}.
290 * If {@code classLoader} is null, the {@linkplain
291 * java.util.ServiceLoader#load(java.lang.Class) default loading mechanism} will apply:
292 * That is, the service-provider loading facility will use the {@linkplain
293 * java.lang.Thread#getContextClassLoader() current thread's context class loader}
294 * to attempt to load the service. If the context class
295 * loader is null, the {@linkplain
296 * ClassLoader#getSystemClassLoader() system class loader} will be used.
297 * </li>
298 * <li>
299 * <p>
300 * Otherwise, throws a {@link FactoryConfigurationError}.
301 * </li>
302 * </ul>
303 *
304 * <p>
305 * Note that this is a new method that replaces the deprecated
306 * {@link #newInstance(java.lang.String, java.lang.ClassLoader)
307 * newInstance(String factoryId, ClassLoader classLoader)} method.
308 * No changes in behavior are defined by this replacement method relative
309 * to the deprecated method.
310 *
311 *
312 * @apiNote The parameter factoryId defined here is inconsistent with that
313 * of other JAXP factories where the first parameter is fully qualified
314 * factory class name that provides implementation of the factory.
315 *
316 * @param factoryId Name of the factory to find, same as
317 * a property name
318 * @param classLoader classLoader to use
319 * @return the factory implementation
320 * @throws FactoryConfigurationError in case of {@linkplain
321 * java.util.ServiceConfigurationError service configuration error} or if
322 * the implementation is not available or cannot be instantiated.
323 * @throws FactoryConfigurationError if an instance of this factory cannot be loaded
324 */
325 public static XMLInputFactory newFactory(String factoryId,
326 ClassLoader classLoader)
327 throws FactoryConfigurationError {
328 //do not fallback if given classloader can't find the class, throw exception
329 return FactoryFinder.find(XMLInputFactory.class, factoryId, classLoader, null);
330 }
331
332 /**
333 * Create a new XMLStreamReader from a reader.
334 * @param reader the XML data to read from
335 * @return an instance of the {@code XMLStreamReader}
336 * @throws XMLStreamException if an error occurs
337 */
338 public abstract XMLStreamReader createXMLStreamReader(java.io.Reader reader)
339 throws XMLStreamException;
340
341 /**
342 * Create a new XMLStreamReader from a JAXP source. This method is optional.
343 * @param source the source to read from
344 * @return an instance of the {@code XMLStreamReader}
345 * @throws UnsupportedOperationException if this method is not
346 * supported by this XMLInputFactory
347 * @throws XMLStreamException if an error occurs
348 */
349 public abstract XMLStreamReader createXMLStreamReader(Source source)
350 throws XMLStreamException;
351
352 /**
353 * Create a new XMLStreamReader from a java.io.InputStream.
354 * @param stream the InputStream to read from
355 * @return an instance of the {@code XMLStreamReader}
356 * @throws XMLStreamException if an error occurs
357 */
358 public abstract XMLStreamReader createXMLStreamReader(java.io.InputStream stream)
359 throws XMLStreamException;
360
361 /**
362 * Create a new XMLStreamReader from a java.io.InputStream.
363 * @param stream the InputStream to read from
364 * @param encoding the character encoding of the stream
365 * @return an instance of the {@code XMLStreamReader}
366 * @throws XMLStreamException if an error occurs
367 */
368 public abstract XMLStreamReader createXMLStreamReader(java.io.InputStream stream, String encoding)
369 throws XMLStreamException;
370
371 /**
372 * Create a new XMLStreamReader from a java.io.InputStream.
373 * @param systemId the system ID of the stream
374 * @param stream the InputStream to read from
375 * @return an instance of the {@code XMLStreamReader}
376 * @throws XMLStreamException if an error occurs
377 */
378 public abstract XMLStreamReader createXMLStreamReader(String systemId, java.io.InputStream stream)
379 throws XMLStreamException;
380
381 /**
382 * Create a new XMLStreamReader from a java.io.InputStream.
383 * @param systemId the system ID of the stream
384 * @param reader the InputStream to read from
385 * @return an instance of the {@code XMLStreamReader}
386 * @throws XMLStreamException if an error occurs
387 */
388 public abstract XMLStreamReader createXMLStreamReader(String systemId, java.io.Reader reader)
389 throws XMLStreamException;
390
391 /**
392 * Create a new XMLEventReader from a reader.
393 * @param reader the XML data to read from
394 * @return an instance of the {@code XMLEventReader}
395 * @throws XMLStreamException if an error occurs
396 */
397 public abstract XMLEventReader createXMLEventReader(java.io.Reader reader)
398 throws XMLStreamException;
399
400 /**
401 * Create a new XMLEventReader from a reader.
402 * @param systemId the system ID of the input
403 * @param reader the XML data to read from
404 * @return an instance of the {@code XMLEventReader}
405 * @throws XMLStreamException if an error occurs
406 */
407 public abstract XMLEventReader createXMLEventReader(String systemId, java.io.Reader reader)
408 throws XMLStreamException;
409
410 /**
411 * Create a new XMLEventReader from an XMLStreamReader. After being used
412 * to construct the XMLEventReader instance returned from this method
413 * the XMLStreamReader must not be used.
414 * @param reader the XMLStreamReader to read from (may not be modified)
415 * @return a new XMLEventReader
416 * @throws XMLStreamException if an error occurs
417 */
418 public abstract XMLEventReader createXMLEventReader(XMLStreamReader reader)
419 throws XMLStreamException;
420
421 /**
422 * Create a new XMLEventReader from a JAXP source.
423 * Support of this method is optional.
424 * @param source the source to read from
425 * @return an instance of the {@code XMLEventReader}
426 * @throws XMLStreamException if an error occurs
427 * @throws UnsupportedOperationException if this method is not
428 * supported by this XMLInputFactory
429 */
430 public abstract XMLEventReader createXMLEventReader(Source source)
431 throws XMLStreamException;
432
433 /**
434 * Create a new XMLEventReader from a java.io.InputStream
435 * @param stream the InputStream to read from
436 * @return an instance of the {@code XMLEventReader}
437 * @throws XMLStreamException if an error occurs
438 */
439 public abstract XMLEventReader createXMLEventReader(java.io.InputStream stream)
440 throws XMLStreamException;
441
442 /**
443 * Create a new XMLEventReader from a java.io.InputStream
444 * @param stream the InputStream to read from
445 * @param encoding the character encoding of the stream
446 * @return an instance of the {@code XMLEventReader}
447 * @throws XMLStreamException if an error occurs
448 */
449 public abstract XMLEventReader createXMLEventReader(java.io.InputStream stream, String encoding)
450 throws XMLStreamException;
451
452 /**
453 * Create a new XMLEventReader from a java.io.InputStream
454 * @param systemId the system ID of the stream
455 * @param stream the InputStream to read from
456 * @return an instance of the {@code XMLEventReader}
457 * @throws XMLStreamException if an error occurs
458 */
459 public abstract XMLEventReader createXMLEventReader(String systemId, java.io.InputStream stream)
460 throws XMLStreamException;
461
462 /**
463 * Create a filtered reader that wraps the filter around the reader
464 * @param reader the reader to filter
465 * @param filter the filter to apply to the reader
466 * @return an instance of the {@code XMLEventReader}
467 * @throws XMLStreamException if an error occurs
468 */
469 public abstract XMLStreamReader createFilteredReader(XMLStreamReader reader, StreamFilter filter)
470 throws XMLStreamException;
471
472 /**
473 * Create a filtered event reader that wraps the filter around the event reader
474 * @param reader the event reader to wrap
475 * @param filter the filter to apply to the event reader
476 * @return an instance of the {@code XMLEventReader}
477 * @throws XMLStreamException if an error occurs
478 */
479 public abstract XMLEventReader createFilteredReader(XMLEventReader reader, EventFilter filter)
480 throws XMLStreamException;
481
482 /**
483 * The resolver that will be set on any XMLStreamReader or XMLEventReader created
484 * by this factory instance.
485 * @return an instance of the {@code XMLResolver}
486 */
487 public abstract XMLResolver getXMLResolver();
488
489 /**
490 * The resolver that will be set on any XMLStreamReader or XMLEventReader created
491 * by this factory instance.
492 * @param resolver the resolver to use to resolve references
493 */
494 public abstract void setXMLResolver(XMLResolver resolver);
495
496 /**
497 * The reporter that will be set on any XMLStreamReader or XMLEventReader created
498 * by this factory instance.
499 * @return an instance of the {@code XMLReporter}
500 */
501 public abstract XMLReporter getXMLReporter();
502
503 /**
504 * The reporter that will be set on any XMLStreamReader or XMLEventReader created
505 * by this factory instance.
506 * @param reporter the resolver to use to report non fatal errors
507 */
508 public abstract void setXMLReporter(XMLReporter reporter);
509
510 /**
511 * Allows the user to set specific feature/property on the underlying
512 * implementation. The underlying implementation is not required to support
513 * every setting of every property in the specification and may use
514 * IllegalArgumentException to signal that an unsupported property may not be
515 * set with the specified value.
516 * <p>
517 * All implementations that implement JAXP 1.5 or newer are required to
518 * support the {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_DTD} property.
519 * <ul>
520 * <li>
521 * <p>
522 * Access to external DTDs, external Entity References is restricted to the
523 * protocols specified by the property. If access is denied during parsing
524 * due to the restriction of this property, {@link javax.xml.stream.XMLStreamException}
525 * will be thrown by the {@link javax.xml.stream.XMLStreamReader#next()} or
526 * {@link javax.xml.stream.XMLEventReader#nextEvent()} method.
527 *
528 * </li>
529 * </ul>
530 * @param name The name of the property (may not be null)
531 * @param value The value of the property
532 * @throws java.lang.IllegalArgumentException if the property is not supported
533 */
534 public abstract void setProperty(java.lang.String name, Object value)
535 throws java.lang.IllegalArgumentException;
536
537 /**
538 * Get the value of a feature/property from the underlying implementation
539 * @param name The name of the property (may not be null)
540 * @return The value of the property
541 * @throws IllegalArgumentException if the property is not supported
542 */
543 public abstract Object getProperty(java.lang.String name)
544 throws java.lang.IllegalArgumentException;
545
546
547 /**
548 * Query the set of properties that this factory supports.
549 *
550 * @param name The name of the property (may not be null)
551 * @return true if the property is supported and false otherwise
552 */
553 public abstract boolean isPropertySupported(String name);
554
555 /**
556 * Set a user defined event allocator for events
557 * @param allocator the user defined allocator
558 */
559 public abstract void setEventAllocator(XMLEventAllocator allocator);
560
561 /**
562 * Gets the allocator used by streams created with this factory
563 * @return an instance of the {@code XMLEventAllocator}
564 */
565 public abstract XMLEventAllocator getEventAllocator();
566
567 }