1 /* 2 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 3 * 4 * This code is free software; you can redistribute it and/or modify it 5 * under the terms of the GNU General Public License version 2 only, as 6 * published by the Free Software Foundation. Oracle designates this 7 * particular file as subject to the "Classpath" exception as provided 8 * by Oracle in the LICENSE file that accompanied this code. 9 * 10 * This code is distributed in the hope that it will be useful, but WITHOUT 11 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 12 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 13 * version 2 for more details (a copy is included in the LICENSE file that 14 * accompanied this code). 15 * 16 * You should have received a copy of the GNU General Public License version 17 * 2 along with this work; if not, write to the Free Software Foundation, 18 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 19 * 20 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 21 * or visit www.oracle.com if you need additional information or have any 22 * questions. 23 */ 24 25 /* 26 * Copyright (c) 2009, 2013, by Oracle Corporation. All Rights Reserved. 27 */ 28 29 package javax.xml.stream; 30 31 import javax.xml.stream.util.XMLEventAllocator; 32 import javax.xml.transform.Source; 33 34 /** 35 * Defines an abstract implementation of a factory for getting streams. 36 * 37 * The following table defines the standard properties of this specification. 38 * Each property varies in the level of support required by each implementation. 39 * The level of support required is described in the 'Required' column. 40 * 41 * <table border="2" rules="all" cellpadding="4"> 42 * <thead> 43 * <tr> 44 * <th align="center" colspan="5"> 45 * Configuration parameters 46 * </th> 47 * </tr> 48 * </thead> 49 * <tbody> 50 * <tr> 51 * <th>Property Name</th> 52 * <th>Behavior</th> 53 * <th>Return type</th> 54 * <th>Default Value</th> 55 * <th>Required</th> 56 * </tr> 57 * <tr><td>javax.xml.stream.isValidating</td><td>Turns on/off implementation specific DTD validation</td><td>Boolean</td><td>False</td><td>No</td></tr> 58 * <tr><td>javax.xml.stream.isNamespaceAware</td><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> 59 * <tr><td>javax.xml.stream.isCoalescing</td><td>Requires the processor to coalesce adjacent character data</td><td>Boolean</td><td>False</td><td>Yes</td></tr> 60 * <tr><td>javax.xml.stream.isReplacingEntityReferences</td><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> 61 *<tr><td>javax.xml.stream.isSupportingExternalEntities</td><td>Resolve external parsed entities</td><td>Boolean</td><td>Unspecified</td><td>Yes</td></tr> 62 *<tr><td>javax.xml.stream.supportDTD</td><td>Use this property to request processors that do not support DTDs</td><td>Boolean</td><td>True</td><td>Yes</td></tr> 63 *<tr><td>javax.xml.stream.reporter</td><td>sets/gets the impl of the XMLReporter </td><td>javax.xml.stream.XMLReporter</td><td>Null</td><td>Yes</td></tr> 64 *<tr><td>javax.xml.stream.resolver</td><td>sets/gets the impl of the XMLResolver interface</td><td>javax.xml.stream.XMLResolver</td><td>Null</td><td>Yes</td></tr> 65 *<tr><td>javax.xml.stream.allocator</td><td>sets/gets the impl of the XMLEventAllocator interface</td><td>javax.xml.stream.util.XMLEventAllocator</td><td>Null</td><td>Yes</td></tr> 66 * </tbody> 67 * </table> 68 * 69 * 70 * @version 1.2 71 * @author Copyright (c) 2009 by Oracle Corporation. All Rights Reserved. 72 * @see XMLOutputFactory 73 * @see XMLEventReader 74 * @see XMLStreamReader 75 * @see EventFilter 76 * @see XMLReporter 77 * @see XMLResolver 78 * @see javax.xml.stream.util.XMLEventAllocator 79 * @since 1.6 80 */ 81 82 public abstract class XMLInputFactory { 83 /** 84 * The property used to turn on/off namespace support, 85 * this is to support XML 1.0 documents, 86 * only the true setting must be supported 87 */ 88 public static final String IS_NAMESPACE_AWARE= 89 "javax.xml.stream.isNamespaceAware"; 90 91 /** 92 * The property used to turn on/off implementation specific validation 93 */ 94 public static final String IS_VALIDATING= 95 "javax.xml.stream.isValidating"; 96 97 /** 98 * The property that requires the parser to coalesce adjacent character data sections 99 */ 100 public static final String IS_COALESCING= 101 "javax.xml.stream.isCoalescing"; 102 103 /** 104 * Requires the parser to replace internal 105 * entity references with their replacement 106 * text and report them as characters 107 */ 108 public static final String IS_REPLACING_ENTITY_REFERENCES= 109 "javax.xml.stream.isReplacingEntityReferences"; 110 111 /** 112 * The property that requires the parser to resolve external parsed entities 113 */ 114 public static final String IS_SUPPORTING_EXTERNAL_ENTITIES= 115 "javax.xml.stream.isSupportingExternalEntities"; 116 117 /** 118 * The property that requires the parser to support DTDs 119 */ 120 public static final String SUPPORT_DTD= 121 "javax.xml.stream.supportDTD"; 122 123 /** 124 * The property used to 125 * set/get the implementation of the XMLReporter interface 126 */ 127 public static final String REPORTER= 128 "javax.xml.stream.reporter"; 129 130 /** 131 * The property used to set/get the implementation of the XMLResolver 132 */ 133 public static final String RESOLVER= 134 "javax.xml.stream.resolver"; 135 136 /** 137 * The property used to set/get the implementation of the allocator 138 */ 139 public static final String ALLOCATOR= 140 "javax.xml.stream.allocator"; 141 142 static final String DEFAULIMPL = "com.sun.xml.internal.stream.XMLInputFactoryImpl"; 143 144 protected XMLInputFactory(){} 145 146 /** 147 * Creates a new instance of the factory in exactly the same manner as the 148 * {@link #newFactory()} method. 149 * @throws FactoryConfigurationError if an instance of this factory cannot be loaded 150 */ 151 public static XMLInputFactory newInstance() 152 throws FactoryConfigurationError 153 { 154 return FactoryFinder.find(XMLInputFactory.class, DEFAULIMPL); 155 } 156 157 /** 158 * Create a new instance of the factory. 159 * <p> 160 * This static method creates a new factory instance. 161 * This method uses the following ordered lookup procedure to determine 162 * the XMLInputFactory implementation class to load: 163 * </p> 164 * <ul> 165 * <li> 166 * Use the javax.xml.stream.XMLInputFactory system property. 167 * </li> 168 * <li> 169 * Use the properties file "lib/stax.properties" in the JRE directory. 170 * This configuration file is in standard java.util.Properties format 171 * and contains the fully qualified name of the implementation class 172 * with the key being the system property defined above. 173 * </li> 174 * <li> 175 * Use the service-provider loading facilities, defined by the 176 * {@link java.util.ServiceLoader} class, to attempt to locate and load an 177 * implementation of the service using the {@linkplain 178 * java.util.ServiceLoader#load(java.lang.Class) default loading mechanism}: 179 * the service-provider loading facility will use the {@linkplain 180 * java.lang.Thread#getContextClassLoader() current thread's context class loader} 181 * to attempt to load the service. If the context class 182 * loader is null, the {@linkplain 183 * ClassLoader#getSystemClassLoader() system class loader} will be used. 184 * </li> 185 * <li> 186 * Otherwise, the system-default implementation is returned. 187 * </li> 188 * </ul> 189 * <p> 190 * Once an application has obtained a reference to a XMLInputFactory it 191 * can use the factory to configure and obtain stream instances. 192 * </p> 193 * <p> 194 * Note that this is a new method that replaces the deprecated newInstance() method. 195 * No changes in behavior are defined by this replacement method relative to 196 * the deprecated method. 197 * </p> 198 * @throws FactoryConfigurationError in case of {@linkplain 199 * java.util.ServiceConfigurationError service configuration error} or if 200 * the implementation is not available or cannot be instantiated. 201 */ 202 public static XMLInputFactory newFactory() 203 throws FactoryConfigurationError 204 { 205 return FactoryFinder.find(XMLInputFactory.class, DEFAULIMPL); 206 } 207 208 /** 209 * Create a new instance of the factory 210 * 211 * @param factoryId Name of the factory to find, same as 212 * a property name 213 * @param classLoader classLoader to use 214 * @return the factory implementation 215 * @throws FactoryConfigurationError if an instance of this factory cannot be loaded 216 * 217 * @deprecated This method has been deprecated to maintain API consistency. 218 * All newInstance methods have been replaced with corresponding 219 * newFactory methods. The replacement {@link 220 * #newFactory(java.lang.String, java.lang.ClassLoader)} method 221 * defines no changes in behavior. 222 */ 223 public static XMLInputFactory newInstance(String factoryId, 224 ClassLoader classLoader) 225 throws FactoryConfigurationError { 226 //do not fallback if given classloader can't find the class, throw exception 227 return FactoryFinder.find(XMLInputFactory.class, factoryId, classLoader, null); 228 } 229 230 /** 231 * Create a new instance of the factory. 232 * If the classLoader argument is null, then the ContextClassLoader is used. 233 * <p> 234 * This method uses the following ordered lookup procedure to determine 235 * the XMLInputFactory implementation class to load: 236 * </p> 237 * <ul> 238 * <li> 239 * Use the value of the system property identified by {@code factoryId}. 240 * </li> 241 * <li> 242 * Use the properties file "lib/stax.properties" in the JRE directory. 243 * This configuration file is in standard java.util.Properties format 244 * and contains the fully qualified name of the implementation class 245 * with the key being the given {@code factoryId}. 246 * </li> 247 * <li> 248 * If {@code factoryId} is "javax.xml.stream.XMLInputFactory", 249 * use the service-provider loading facilities, defined by the 250 * {@link java.util.ServiceLoader} class, to attempt to locate and load an 251 * implementation of the service using the {@linkplain 252 * java.util.ServiceLoader#load(java.lang.Class) default loading mechanism}: 253 * the service-provider loading facility will use the {@linkplain 254 * java.lang.Thread#getContextClassLoader() current thread's context class loader} 255 * to attempt to load the service. If the context class 256 * loader is null, the {@linkplain 257 * ClassLoader#getSystemClassLoader() system class loader} will be used. 258 * </li> 259 * <li> 260 * Otherwise, throws a {@link FactoryConfigurationError}. 261 * </li> 262 * </ul> 263 * 264 * <p> 265 * Note that this is a new method that replaces the deprecated 266 * {@link #newInstance(java.lang.String, java.lang.ClassLoader) 267 * newInstance(String factoryId, ClassLoader classLoader)} method. 268 * No changes in behavior are defined by this replacement method relative 269 * to the deprecated method. 270 * </p> 271 * 272 * @param factoryId Name of the factory to find, same as 273 * a property name 274 * @param classLoader classLoader to use 275 * @return the factory implementation 276 * @throws FactoryConfigurationError in case of {@linkplain 277 * java.util.ServiceConfigurationError service configuration error} or if 278 * the implementation is not available or cannot be instantiated. 279 * @throws FactoryConfigurationError if an instance of this factory cannot be loaded 280 */ 281 public static XMLInputFactory newFactory(String factoryId, 282 ClassLoader classLoader) 283 throws FactoryConfigurationError { 284 //do not fallback if given classloader can't find the class, throw exception 285 return FactoryFinder.find(XMLInputFactory.class, factoryId, classLoader, null); 286 } 287 288 /** 289 * Create a new XMLStreamReader from a reader 290 * @param reader the XML data to read from 291 * @throws XMLStreamException 292 */ 293 public abstract XMLStreamReader createXMLStreamReader(java.io.Reader reader) 294 throws XMLStreamException; 295 296 /** 297 * Create a new XMLStreamReader from a JAXP source. This method is optional. 298 * @param source the source to read from 299 * @throws UnsupportedOperationException if this method is not 300 * supported by this XMLInputFactory 301 * @throws XMLStreamException 302 */ 303 public abstract XMLStreamReader createXMLStreamReader(Source source) 304 throws XMLStreamException; 305 306 /** 307 * Create a new XMLStreamReader from a java.io.InputStream 308 * @param stream the InputStream to read from 309 * @throws XMLStreamException 310 */ 311 public abstract XMLStreamReader createXMLStreamReader(java.io.InputStream stream) 312 throws XMLStreamException; 313 314 /** 315 * Create a new XMLStreamReader from a java.io.InputStream 316 * @param stream the InputStream to read from 317 * @param encoding the character encoding of the stream 318 * @throws XMLStreamException 319 */ 320 public abstract XMLStreamReader createXMLStreamReader(java.io.InputStream stream, String encoding) 321 throws XMLStreamException; 322 323 /** 324 * Create a new XMLStreamReader from a java.io.InputStream 325 * @param systemId the system ID of the stream 326 * @param stream the InputStream to read from 327 */ 328 public abstract XMLStreamReader createXMLStreamReader(String systemId, java.io.InputStream stream) 329 throws XMLStreamException; 330 331 /** 332 * Create a new XMLStreamReader from a java.io.InputStream 333 * @param systemId the system ID of the stream 334 * @param reader the InputStream to read from 335 */ 336 public abstract XMLStreamReader createXMLStreamReader(String systemId, java.io.Reader reader) 337 throws XMLStreamException; 338 339 /** 340 * Create a new XMLEventReader from a reader 341 * @param reader the XML data to read from 342 * @throws XMLStreamException 343 */ 344 public abstract XMLEventReader createXMLEventReader(java.io.Reader reader) 345 throws XMLStreamException; 346 347 /** 348 * Create a new XMLEventReader from a reader 349 * @param systemId the system ID of the input 350 * @param reader the XML data to read from 351 * @throws XMLStreamException 352 */ 353 public abstract XMLEventReader createXMLEventReader(String systemId, java.io.Reader reader) 354 throws XMLStreamException; 355 356 /** 357 * Create a new XMLEventReader from an XMLStreamReader. After being used 358 * to construct the XMLEventReader instance returned from this method 359 * the XMLStreamReader must not be used. 360 * @param reader the XMLStreamReader to read from (may not be modified) 361 * @return a new XMLEventReader 362 * @throws XMLStreamException 363 */ 364 public abstract XMLEventReader createXMLEventReader(XMLStreamReader reader) 365 throws XMLStreamException; 366 367 /** 368 * Create a new XMLEventReader from a JAXP source. 369 * Support of this method is optional. 370 * @param source the source to read from 371 * @throws UnsupportedOperationException if this method is not 372 * supported by this XMLInputFactory 373 */ 374 public abstract XMLEventReader createXMLEventReader(Source source) 375 throws XMLStreamException; 376 377 /** 378 * Create a new XMLEventReader from a java.io.InputStream 379 * @param stream the InputStream to read from 380 * @throws XMLStreamException 381 */ 382 public abstract XMLEventReader createXMLEventReader(java.io.InputStream stream) 383 throws XMLStreamException; 384 385 /** 386 * Create a new XMLEventReader from a java.io.InputStream 387 * @param stream the InputStream to read from 388 * @param encoding the character encoding of the stream 389 * @throws XMLStreamException 390 */ 391 public abstract XMLEventReader createXMLEventReader(java.io.InputStream stream, String encoding) 392 throws XMLStreamException; 393 394 /** 395 * Create a new XMLEventReader from a java.io.InputStream 396 * @param systemId the system ID of the stream 397 * @param stream the InputStream to read from 398 * @throws XMLStreamException 399 */ 400 public abstract XMLEventReader createXMLEventReader(String systemId, java.io.InputStream stream) 401 throws XMLStreamException; 402 403 /** 404 * Create a filtered reader that wraps the filter around the reader 405 * @param reader the reader to filter 406 * @param filter the filter to apply to the reader 407 * @throws XMLStreamException 408 */ 409 public abstract XMLStreamReader createFilteredReader(XMLStreamReader reader, StreamFilter filter) 410 throws XMLStreamException; 411 412 /** 413 * Create a filtered event reader that wraps the filter around the event reader 414 * @param reader the event reader to wrap 415 * @param filter the filter to apply to the event reader 416 * @throws XMLStreamException 417 */ 418 public abstract XMLEventReader createFilteredReader(XMLEventReader reader, EventFilter filter) 419 throws XMLStreamException; 420 421 /** 422 * The resolver that will be set on any XMLStreamReader or XMLEventReader created 423 * by this factory instance. 424 */ 425 public abstract XMLResolver getXMLResolver(); 426 427 /** 428 * The resolver that will be set on any XMLStreamReader or XMLEventReader created 429 * by this factory instance. 430 * @param resolver the resolver to use to resolve references 431 */ 432 public abstract void setXMLResolver(XMLResolver resolver); 433 434 /** 435 * The reporter that will be set on any XMLStreamReader or XMLEventReader created 436 * by this factory instance. 437 */ 438 public abstract XMLReporter getXMLReporter(); 439 440 /** 441 * The reporter that will be set on any XMLStreamReader or XMLEventReader created 442 * by this factory instance. 443 * @param reporter the resolver to use to report non fatal errors 444 */ 445 public abstract void setXMLReporter(XMLReporter reporter); 446 447 /** 448 * Allows the user to set specific feature/property on the underlying 449 * implementation. The underlying implementation is not required to support 450 * every setting of every property in the specification and may use 451 * IllegalArgumentException to signal that an unsupported property may not be 452 * set with the specified value. 453 * <p> 454 * All implementations that implement JAXP 1.5 or newer are required to 455 * support the {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_DTD} property. 456 * </p> 457 * <ul> 458 * <li> 459 * <p> 460 * Access to external DTDs, external Entity References is restricted to the 461 * protocols specified by the property. If access is denied during parsing 462 * due to the restriction of this property, {@link javax.xml.stream.XMLStreamException} 463 * will be thrown by the {@link javax.xml.stream.XMLStreamReader#next()} or 464 * {@link javax.xml.stream.XMLEventReader#nextEvent()} method. 465 * </p> 466 * </li> 467 * </ul> 468 * @param name The name of the property (may not be null) 469 * @param value The value of the property 470 * @throws java.lang.IllegalArgumentException if the property is not supported 471 */ 472 public abstract void setProperty(java.lang.String name, Object value) 473 throws java.lang.IllegalArgumentException; 474 475 /** 476 * Get the value of a feature/property from the underlying implementation 477 * @param name The name of the property (may not be null) 478 * @return The value of the property 479 * @throws IllegalArgumentException if the property is not supported 480 */ 481 public abstract Object getProperty(java.lang.String name) 482 throws java.lang.IllegalArgumentException; 483 484 485 /** 486 * Query the set of properties that this factory supports. 487 * 488 * @param name The name of the property (may not be null) 489 * @return true if the property is supported and false otherwise 490 */ 491 public abstract boolean isPropertySupported(String name); 492 493 /** 494 * Set a user defined event allocator for events 495 * @param allocator the user defined allocator 496 */ 497 public abstract void setEventAllocator(XMLEventAllocator allocator); 498 499 /** 500 * Gets the allocator used by streams created with this factory 501 */ 502 public abstract XMLEventAllocator getEventAllocator(); 503 504 }