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 specified {@code ClassLoader}.
 252    *   If {@code classLoader} is null, the {@linkplain
 253    *   java.util.ServiceLoader#load(java.lang.Class) default loading mechanism} will apply:
 254    *   That is, the service-provider loading facility will use the {@linkplain
 255    *   java.lang.Thread#getContextClassLoader() current thread's context class loader}
 256    *   to attempt to load the service. If the context class
 257    *   loader is null, the {@linkplain
 258    *   ClassLoader#getSystemClassLoader() system class loader} will be used.
 259    * </li>
 260    * <li>
 261    *   Otherwise, throws a {@link FactoryConfigurationError}.
 262    * </li>
 263    * </ul>
 264    *
 265    * <p>
 266    * Note that this is a new method that replaces the deprecated
 267    *   {@link #newInstance(java.lang.String, java.lang.ClassLoader)
 268    *   newInstance(String factoryId, ClassLoader classLoader)} method.
 269    * No changes in behavior are defined by this replacement method relative
 270    * to the deprecated method.
 271    * </p>
 272    *
 273    * @apiNote The parameter factoryId defined here is inconsistent with that
 274    * of other JAXP factories where the first parameter is fully qualified
 275    * factory class name that provides implementation of the factory.
 276    *
 277    * @param factoryId             Name of the factory to find, same as
 278    *                              a property name
 279    * @param classLoader           classLoader to use
 280    * @return the factory implementation
 281    * @throws FactoryConfigurationError in case of {@linkplain
 282    *   java.util.ServiceConfigurationError service configuration error} or if
 283    *   the implementation is not available or cannot be instantiated.
 284    * @throws FactoryConfigurationError if an instance of this factory cannot be loaded
 285    */
 286   public static XMLInputFactory newFactory(String factoryId,
 287           ClassLoader classLoader)
 288           throws FactoryConfigurationError {
 289       //do not fallback if given classloader can't find the class, throw exception
 290       return FactoryFinder.find(XMLInputFactory.class, factoryId, classLoader, null);
 291   }
 292 
 293   /**
 294    * Create a new XMLStreamReader from a reader
 295    * @param reader the XML data to read from
 296    * @throws XMLStreamException
 297    */
 298   public abstract XMLStreamReader createXMLStreamReader(java.io.Reader reader)
 299     throws XMLStreamException;
 300 
 301   /**
 302    * Create a new XMLStreamReader from a JAXP source.  This method is optional.
 303    * @param source the source to read from
 304    * @throws UnsupportedOperationException if this method is not
 305    * supported by this XMLInputFactory
 306    * @throws XMLStreamException
 307    */
 308   public abstract XMLStreamReader createXMLStreamReader(Source source)
 309     throws XMLStreamException;
 310 
 311   /**
 312    * Create a new XMLStreamReader from a java.io.InputStream
 313    * @param stream the InputStream to read from
 314    * @throws XMLStreamException
 315    */
 316   public abstract XMLStreamReader createXMLStreamReader(java.io.InputStream stream)
 317     throws XMLStreamException;
 318 
 319   /**
 320    * Create a new XMLStreamReader from a java.io.InputStream
 321    * @param stream the InputStream to read from
 322    * @param encoding the character encoding of the stream
 323    * @throws XMLStreamException
 324    */
 325   public abstract XMLStreamReader createXMLStreamReader(java.io.InputStream stream, String encoding)
 326     throws XMLStreamException;
 327 
 328   /**
 329    * Create a new XMLStreamReader from a java.io.InputStream
 330    * @param systemId the system ID of the stream
 331    * @param stream the InputStream to read from
 332    */
 333   public abstract XMLStreamReader createXMLStreamReader(String systemId, java.io.InputStream stream)
 334     throws XMLStreamException;
 335 
 336   /**
 337    * Create a new XMLStreamReader from a java.io.InputStream
 338    * @param systemId the system ID of the stream
 339    * @param reader the InputStream to read from
 340    */
 341   public abstract XMLStreamReader createXMLStreamReader(String systemId, java.io.Reader reader)
 342     throws XMLStreamException;
 343 
 344   /**
 345    * Create a new XMLEventReader from a reader
 346    * @param reader the XML data to read from
 347    * @throws XMLStreamException
 348    */
 349   public abstract XMLEventReader createXMLEventReader(java.io.Reader reader)
 350     throws XMLStreamException;
 351 
 352   /**
 353    * Create a new XMLEventReader from a reader
 354    * @param systemId the system ID of the input
 355    * @param reader the XML data to read from
 356    * @throws XMLStreamException
 357    */
 358   public abstract XMLEventReader createXMLEventReader(String systemId, java.io.Reader reader)
 359     throws XMLStreamException;
 360 
 361   /**
 362    * Create a new XMLEventReader from an XMLStreamReader.  After being used
 363    * to construct the XMLEventReader instance returned from this method
 364    * the XMLStreamReader must not be used.
 365    * @param reader the XMLStreamReader to read from (may not be modified)
 366    * @return a new XMLEventReader
 367    * @throws XMLStreamException
 368    */
 369   public abstract XMLEventReader createXMLEventReader(XMLStreamReader reader)
 370     throws XMLStreamException;
 371 
 372   /**
 373    * Create a new XMLEventReader from a JAXP source.
 374    * Support of this method is optional.
 375    * @param source the source to read from
 376    * @throws UnsupportedOperationException if this method is not
 377    * supported by this XMLInputFactory
 378    */
 379   public abstract XMLEventReader createXMLEventReader(Source source)
 380     throws XMLStreamException;
 381 
 382   /**
 383    * Create a new XMLEventReader from a java.io.InputStream
 384    * @param stream the InputStream to read from
 385    * @throws XMLStreamException
 386    */
 387   public abstract XMLEventReader createXMLEventReader(java.io.InputStream stream)
 388     throws XMLStreamException;
 389 
 390   /**
 391    * Create a new XMLEventReader from a java.io.InputStream
 392    * @param stream the InputStream to read from
 393    * @param encoding the character encoding of the stream
 394    * @throws XMLStreamException
 395    */
 396   public abstract XMLEventReader createXMLEventReader(java.io.InputStream stream, String encoding)
 397     throws XMLStreamException;
 398 
 399   /**
 400    * Create a new XMLEventReader from a java.io.InputStream
 401    * @param systemId the system ID of the stream
 402    * @param stream the InputStream to read from
 403    * @throws XMLStreamException
 404    */
 405   public abstract XMLEventReader createXMLEventReader(String systemId, java.io.InputStream stream)
 406     throws XMLStreamException;
 407 
 408   /**
 409    * Create a filtered reader that wraps the filter around the reader
 410    * @param reader the reader to filter
 411    * @param filter the filter to apply to the reader
 412    * @throws XMLStreamException
 413    */
 414   public abstract XMLStreamReader createFilteredReader(XMLStreamReader reader, StreamFilter filter)
 415     throws XMLStreamException;
 416 
 417   /**
 418    * Create a filtered event reader that wraps the filter around the event reader
 419    * @param reader the event reader to wrap
 420    * @param filter the filter to apply to the event reader
 421    * @throws XMLStreamException
 422    */
 423   public abstract XMLEventReader createFilteredReader(XMLEventReader reader, EventFilter filter)
 424     throws XMLStreamException;
 425 
 426   /**
 427    * The resolver that will be set on any XMLStreamReader or XMLEventReader created
 428    * by this factory instance.
 429    */
 430   public abstract XMLResolver getXMLResolver();
 431 
 432   /**
 433    * The resolver that will be set on any XMLStreamReader or XMLEventReader created
 434    * by this factory instance.
 435    * @param resolver the resolver to use to resolve references
 436    */
 437   public abstract void  setXMLResolver(XMLResolver resolver);
 438 
 439   /**
 440    * The reporter that will be set on any XMLStreamReader or XMLEventReader created
 441    * by this factory instance.
 442    */
 443   public abstract XMLReporter getXMLReporter();
 444 
 445   /**
 446    * The reporter that will be set on any XMLStreamReader or XMLEventReader created
 447    * by this factory instance.
 448    * @param reporter the resolver to use to report non fatal errors
 449    */
 450   public abstract void setXMLReporter(XMLReporter reporter);
 451 
 452   /**
 453    * Allows the user to set specific feature/property on the underlying
 454    * implementation. The underlying implementation is not required to support
 455    * every setting of every property in the specification and may use
 456    * IllegalArgumentException to signal that an unsupported property may not be
 457    * set with the specified value.
 458    * <p>
 459    * All implementations that implement JAXP 1.5 or newer are required to
 460    * support the {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_DTD} property.
 461    * </p>
 462    * <ul>
 463    *   <li>
 464    *        <p>
 465    *        Access to external DTDs, external Entity References is restricted to the
 466    *        protocols specified by the property. If access is denied during parsing
 467    *        due to the restriction of this property, {@link javax.xml.stream.XMLStreamException}
 468    *        will be thrown by the {@link javax.xml.stream.XMLStreamReader#next()} or
 469    *        {@link javax.xml.stream.XMLEventReader#nextEvent()} method.
 470    *        </p>
 471    *   </li>
 472    * </ul>
 473    * @param name The name of the property (may not be null)
 474    * @param value The value of the property
 475    * @throws java.lang.IllegalArgumentException if the property is not supported
 476    */
 477   public abstract void setProperty(java.lang.String name, Object value)
 478     throws java.lang.IllegalArgumentException;
 479 
 480   /**
 481    * Get the value of a feature/property from the underlying implementation
 482    * @param name The name of the property (may not be null)
 483    * @return The value of the property
 484    * @throws IllegalArgumentException if the property is not supported
 485    */
 486   public abstract Object getProperty(java.lang.String name)
 487     throws java.lang.IllegalArgumentException;
 488 
 489 
 490   /**
 491    * Query the set of properties that this factory supports.
 492    *
 493    * @param name The name of the property (may not be null)
 494    * @return true if the property is supported and false otherwise
 495    */
 496   public abstract boolean isPropertySupported(String name);
 497 
 498   /**
 499    * Set a user defined event allocator for events
 500    * @param allocator the user defined allocator
 501    */
 502   public abstract void setEventAllocator(XMLEventAllocator allocator);
 503 
 504   /**
 505    * Gets the allocator used by streams created with this factory
 506    */
 507   public abstract XMLEventAllocator getEventAllocator();
 508 
 509 }