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 by Oracle Corporation. All Rights Reserved.
  27  */
  28 
  29 package javax.xml.stream;
  30 
  31 import javax.xml.transform.Source;
  32 import javax.xml.stream.util.XMLEventAllocator;
  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    * Create a new instance of the factory.
 148    * @throws FactoryConfigurationError if an instance of this factory cannot be loaded
 149    */
 150   public static XMLInputFactory newInstance()
 151     throws FactoryConfigurationError
 152   {
 153         return (XMLInputFactory) FactoryFinder.find(XMLInputFactory.class, 
 154       "javax.xml.stream.XMLInputFactory",
 155       DEFAULIMPL);
 156   }
 157 
 158   /**
 159    * <p>Create a new instance of the factory.
 160    * </p><p>This static method creates a new factory instance.
 161    * </p><p>This method uses the following ordered lookup procedure to determine
 162    * the XMLInputFactory implementation class to load:
 163    * <ul>
 164    * <li>
 165    *   Use the javax.xml.stream.XMLInputFactory system property.
 166    * </li>
 167    * <li>
 168    *   Use the properties file "lib/stax.properties" in the JRE directory.
 169    *     This configuration file is in standard java.util.Properties format
 170    *     and contains the fully qualified name of the implementation class
 171    *     with the key being the system property defined above.
 172    * </li>
 173    * <li>
 174    *   <p>Uses the service-provider loading facilities, defined by the {@link java.util.ServiceLoader} class, to attempt 
 175    *   to locate and load an implementation of the service. In case of multiple providers, the first non-default implementation
 176    *   shall be instantiated and returned.  The default implementation is returned if it is the only one
 177    *   found by the service loader.</p>
 178    *   <p>
 179    *   If a misconfigured provider is encountered and {@link java.util.ServiceConfigurationError} is thrown, the error will be wrapped 
 180    *   in a {@link javax.xml.stream.FactoryConfigurationError}.</p>
 181    * </li>
 182    * <li>
 183    *   Platform default XMLInputFactory instance.
 184    * </li>
 185    * </ul>
 186    *</p><p>
 187    *   Once an application has obtained a reference to a XMLInputFactory it
 188    *   can use the factory to configure and obtain stream instances.
 189    *</p><p>
 190    *   Note that this is a new method that replaces the deprecated newInstance() method.
 191    *     No changes in behavior are defined by this replacement method relative to
 192    *     the deprecated method.
 193    *</p>
 194    * @throws FactoryConfigurationError if an instance of this factory cannot be loaded
 195    */
 196   public static XMLInputFactory newFactory()
 197     throws FactoryConfigurationError
 198   {
 199     return (XMLInputFactory) FactoryFinder.find(XMLInputFactory.class, 
 200       "javax.xml.stream.XMLInputFactory",
 201       DEFAULIMPL);
 202   }
 203 
 204   /**
 205    * Create a new instance of the factory
 206    *
 207    * @param factoryId             Name of the factory to find, same as
 208    *                              a property name
 209    * @param classLoader           classLoader to use
 210    * @return the factory implementation
 211    * @throws FactoryConfigurationError if an instance of this factory cannot be loaded
 212    *
 213    * @deprecated  This method has been deprecated to maintain API consistency.
 214    *              All newInstance methods have been replaced with corresponding
 215    *              newFactory methods. The replacement {@link
 216    *              #newFactory(java.lang.String, java.lang.ClassLoader)} method
 217    *              defines no changes in behavior.
 218    */
 219   public static XMLInputFactory newInstance(String factoryId,
 220           ClassLoader classLoader)
 221           throws FactoryConfigurationError {
 222           //do not fallback if given classloader can't find the class, throw exception
 223         return (XMLInputFactory) FactoryFinder.find(XMLInputFactory.class, factoryId, classLoader, null);
 224       }
 225 
 226   /**
 227    * Create a new instance of the factory.
 228    * If the classLoader argument is null, then the ContextClassLoader is used.
 229    *
 230    * Note that this is a new method that replaces the deprecated
 231    *   newInstance(String factoryId, ClassLoader classLoader) method.
 232    * No changes in behavior are defined by this replacement method relative
 233    * to the deprecated method.
 234    *
 235    * @param factoryId             Name of the factory to find, same as
 236    *                              a property name
 237    * @param classLoader           classLoader to use
 238    * @return the factory implementation
 239    * @throws FactoryConfigurationError if an instance of this factory cannot be loaded
 240    */
 241   public static XMLInputFactory newFactory(String factoryId,
 242           ClassLoader classLoader)
 243           throws FactoryConfigurationError {
 244           //do not fallback if given classloader can't find the class, throw exception
 245         return (XMLInputFactory) FactoryFinder.find(XMLInputFactory.class, factoryId, classLoader, null);
 246       }
 247 
 248   /**
 249    * Create a new XMLStreamReader from a reader
 250    * @param reader the XML data to read from
 251    * @throws XMLStreamException
 252    */
 253   public abstract XMLStreamReader createXMLStreamReader(java.io.Reader reader)
 254     throws XMLStreamException;
 255 
 256   /**
 257    * Create a new XMLStreamReader from a JAXP source.  This method is optional.
 258    * @param source the source to read from
 259    * @throws UnsupportedOperationException if this method is not
 260    * supported by this XMLInputFactory
 261    * @throws XMLStreamException
 262    */
 263   public abstract XMLStreamReader createXMLStreamReader(Source source)
 264     throws XMLStreamException;
 265 
 266   /**
 267    * Create a new XMLStreamReader from a java.io.InputStream
 268    * @param stream the InputStream to read from
 269    * @throws XMLStreamException
 270    */
 271   public abstract XMLStreamReader createXMLStreamReader(java.io.InputStream stream)
 272     throws XMLStreamException;
 273 
 274   /**
 275    * Create a new XMLStreamReader from a java.io.InputStream
 276    * @param stream the InputStream to read from
 277    * @param encoding the character encoding of the stream
 278    * @throws XMLStreamException
 279    */
 280   public abstract XMLStreamReader createXMLStreamReader(java.io.InputStream stream, String encoding)
 281     throws XMLStreamException;
 282 
 283   /**
 284    * Create a new XMLStreamReader from a java.io.InputStream
 285    * @param systemId the system ID of the stream
 286    * @param stream the InputStream to read from
 287    */
 288   public abstract XMLStreamReader createXMLStreamReader(String systemId, java.io.InputStream stream)
 289     throws XMLStreamException;
 290 
 291   /**
 292    * Create a new XMLStreamReader from a java.io.InputStream
 293    * @param systemId the system ID of the stream
 294    * @param reader the InputStream to read from
 295    */
 296   public abstract XMLStreamReader createXMLStreamReader(String systemId, java.io.Reader reader)
 297     throws XMLStreamException;
 298 
 299   /**
 300    * Create a new XMLEventReader from a reader
 301    * @param reader the XML data to read from
 302    * @throws XMLStreamException
 303    */
 304   public abstract XMLEventReader createXMLEventReader(java.io.Reader reader)
 305     throws XMLStreamException;
 306 
 307   /**
 308    * Create a new XMLEventReader from a reader
 309    * @param systemId the system ID of the input
 310    * @param reader the XML data to read from
 311    * @throws XMLStreamException
 312    */
 313   public abstract XMLEventReader createXMLEventReader(String systemId, java.io.Reader reader)
 314     throws XMLStreamException;
 315 
 316   /**
 317    * Create a new XMLEventReader from an XMLStreamReader.  After being used
 318    * to construct the XMLEventReader instance returned from this method
 319    * the XMLStreamReader must not be used.
 320    * @param reader the XMLStreamReader to read from (may not be modified)
 321    * @return a new XMLEventReader
 322    * @throws XMLStreamException
 323    */
 324   public abstract XMLEventReader createXMLEventReader(XMLStreamReader reader)
 325     throws XMLStreamException;
 326 
 327   /**
 328    * Create a new XMLEventReader from a JAXP source.
 329    * Support of this method is optional.
 330    * @param source the source to read from
 331    * @throws UnsupportedOperationException if this method is not
 332    * supported by this XMLInputFactory
 333    */
 334   public abstract XMLEventReader createXMLEventReader(Source source)
 335     throws XMLStreamException;
 336 
 337   /**
 338    * Create a new XMLEventReader from a java.io.InputStream
 339    * @param stream the InputStream to read from
 340    * @throws XMLStreamException
 341    */
 342   public abstract XMLEventReader createXMLEventReader(java.io.InputStream stream)
 343     throws XMLStreamException;
 344 
 345   /**
 346    * Create a new XMLEventReader from a java.io.InputStream
 347    * @param stream the InputStream to read from
 348    * @param encoding the character encoding of the stream
 349    * @throws XMLStreamException
 350    */
 351   public abstract XMLEventReader createXMLEventReader(java.io.InputStream stream, String encoding)
 352     throws XMLStreamException;
 353 
 354   /**
 355    * Create a new XMLEventReader from a java.io.InputStream
 356    * @param systemId the system ID of the stream
 357    * @param stream the InputStream to read from
 358    * @throws XMLStreamException
 359    */
 360   public abstract XMLEventReader createXMLEventReader(String systemId, java.io.InputStream stream)
 361     throws XMLStreamException;
 362 
 363   /**
 364    * Create a filtered reader that wraps the filter around the reader
 365    * @param reader the reader to filter
 366    * @param filter the filter to apply to the reader
 367    * @throws XMLStreamException
 368    */
 369   public abstract XMLStreamReader createFilteredReader(XMLStreamReader reader, StreamFilter filter)
 370     throws XMLStreamException;
 371 
 372   /**
 373    * Create a filtered event reader that wraps the filter around the event reader
 374    * @param reader the event reader to wrap
 375    * @param filter the filter to apply to the event reader
 376    * @throws XMLStreamException
 377    */
 378   public abstract XMLEventReader createFilteredReader(XMLEventReader reader, EventFilter filter)
 379     throws XMLStreamException;
 380 
 381   /**
 382    * The resolver that will be set on any XMLStreamReader or XMLEventReader created
 383    * by this factory instance.
 384    */
 385   public abstract XMLResolver getXMLResolver();
 386 
 387   /**
 388    * The resolver that will be set on any XMLStreamReader or XMLEventReader created
 389    * by this factory instance.
 390    * @param resolver the resolver to use to resolve references
 391    */
 392   public abstract void  setXMLResolver(XMLResolver resolver);
 393 
 394   /**
 395    * The reporter that will be set on any XMLStreamReader or XMLEventReader created
 396    * by this factory instance.
 397    */
 398   public abstract XMLReporter getXMLReporter();
 399 
 400   /**
 401    * The reporter that will be set on any XMLStreamReader or XMLEventReader created
 402    * by this factory instance.
 403    * @param reporter the resolver to use to report non fatal errors
 404    */
 405   public abstract void setXMLReporter(XMLReporter reporter);
 406 
 407   /**
 408    * Allows the user to set specific feature/property on the underlying implementation. The underlying implementation
 409    * is not required to support every setting of every property in the specification and may use IllegalArgumentException
 410    * to signal that an unsupported property may not be set with the specified value.
 411    * @param name The name of the property (may not be null)
 412    * @param value The value of the property
 413    * @throws java.lang.IllegalArgumentException if the property is not supported
 414    */
 415   public abstract void setProperty(java.lang.String name, Object value)
 416     throws java.lang.IllegalArgumentException;
 417 
 418   /**
 419    * Get the value of a feature/property from the underlying implementation
 420    * @param name The name of the property (may not be null)
 421    * @return The value of the property
 422    * @throws IllegalArgumentException if the property is not supported
 423    */
 424   public abstract Object getProperty(java.lang.String name)
 425     throws java.lang.IllegalArgumentException;
 426 
 427 
 428   /**
 429    * Query the set of properties that this factory supports.
 430    *
 431    * @param name The name of the property (may not be null)
 432    * @return true if the property is supported and false otherwise
 433    */
 434   public abstract boolean isPropertySupported(String name);
 435 
 436   /**
 437    * Set a user defined event allocator for events
 438    * @param allocator the user defined allocator
 439    */
 440   public abstract void setEventAllocator(XMLEventAllocator allocator);
 441 
 442   /**
 443    * Gets the allocator used by streams created with this factory
 444    */
 445   public abstract XMLEventAllocator getEventAllocator();
 446 
 447 }