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