src/javax/xml/stream/XMLInputFactory.java

Print this page




 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 




 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