src/javax/xml/stream/XMLInputFactory.java

Print this page
rev 406 : 8005954: JAXP Plugability Layer should use java.util.ServiceLoader
Summary: This fix replaces manual processing of files under META-INF/services in JAXP factories by calls to java.util.ServiceLoader.
Reviewed-by: alanb, joehw, mchung


   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>


 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 




   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>


 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.
 178    * </li>
 179    * <li>
 180    * Otherwise, the system-default implementation is returned.
 181    * </li>
 182    * </ul>
 183    * <p>
 184    *   Once an application has obtained a reference to a XMLInputFactory it
 185    *   can use the factory to configure and obtain stream instances.
 186    * </p>
 187    * <p>
 188    *   Note that this is a new method that replaces the deprecated newInstance() method.
 189    *     No changes in behavior are defined by this replacement method relative to
 190    *     the deprecated method.
 191    * </p>
 192    * @throws FactoryConfigurationError in case of {@linkplain
 193    *   java.util.ServiceConfigurationError service configuration error} or if
 194    *   the implementation is not available or cannot be instantiated.
 195    */
 196   public static XMLInputFactory newFactory()
 197     throws FactoryConfigurationError
 198   {
 199     return FactoryFinder.find(XMLInputFactory.class, DEFAULIMPL);


 200   }
 201 
 202   /**
 203    * Create a new instance of the factory
 204    *
 205    * @param factoryId             Name of the factory to find, same as
 206    *                              a property name
 207    * @param classLoader           classLoader to use
 208    * @return the factory implementation
 209    * @throws FactoryConfigurationError if an instance of this factory cannot be loaded
 210    *
 211    * @deprecated  This method has been deprecated to maintain API consistency.
 212    *              All newInstance methods have been replaced with corresponding
 213    *              newFactory methods. The replacement {@link
 214    *              #newFactory(java.lang.String, java.lang.ClassLoader)} method
 215    *              defines no changes in behavior.
 216    */
 217   public static XMLInputFactory newInstance(String factoryId,
 218           ClassLoader classLoader)
 219           throws FactoryConfigurationError {

 220       //do not fallback if given classloader can't find the class, throw exception
 221       return FactoryFinder.find(XMLInputFactory.class, factoryId, classLoader, null);




 222   }
 223 
 224   /**
 225    * Create a new instance of the factory.
 226    * If the classLoader argument is null, then the ContextClassLoader is used.
 227    * <p>
 228    * This method uses the following ordered lookup procedure to determine
 229    * the XMLInputFactory implementation class to load:
 230    * </p>
 231    * <ul>
 232    * <li>
 233    *   Use the value of the system property identified by {@code factoryId}.
 234    * </li>
 235    * <li>
 236    *   Use the properties file "lib/stax.properties" in the JRE directory.
 237    *     This configuration file is in standard java.util.Properties format
 238    *     and contains the fully qualified name of the implementation class
 239    *     with the key being the given {@code factoryId}.
 240    * </li>
 241    * <li>
 242    *   If {@code factoryId} is "javax.xml.stream.XMLInputFactory",
 243    *   use the service-provider loading facilities, defined by the
 244    *   {@link java.util.ServiceLoader} class, to attempt to locate and load an
 245    *   implementation of the service.
 246    * </li>
 247    * <li>
 248    *   Otherwise, throws a {@link FactoryConfigurationError}.
 249    * </li>
 250    * </ul>
 251    *
 252    * <p>
 253    * Note that this is a new method that replaces the deprecated
 254    *   {@link #newInstance(java.lang.String, java.lang.ClassLoader)
 255    *   newInstance(String factoryId, ClassLoader classLoader)} method.
 256    * No changes in behavior are defined by this replacement method relative
 257    * to the deprecated method.
 258    * </p>
 259    *
 260    * @param factoryId             Name of the factory to find, same as
 261    *                              a property name
 262    * @param classLoader           classLoader to use
 263    * @return the factory implementation
 264    * @throws FactoryConfigurationError in case of {@linkplain
 265    *   java.util.ServiceConfigurationError service configuration error} or if
 266    *   the implementation is not available or cannot be instantiated.
 267    * @throws FactoryConfigurationError if an instance of this factory cannot be loaded
 268    */
 269   public static XMLInputFactory newFactory(String factoryId,
 270           ClassLoader classLoader)
 271           throws FactoryConfigurationError {

 272       //do not fallback if given classloader can't find the class, throw exception
 273       return FactoryFinder.find(XMLInputFactory.class, factoryId, classLoader, null);




 274   }
 275 
 276   /**
 277    * Create a new XMLStreamReader from a reader
 278    * @param reader the XML data to read from
 279    * @throws XMLStreamException
 280    */
 281   public abstract XMLStreamReader createXMLStreamReader(java.io.Reader reader)
 282     throws XMLStreamException;
 283 
 284   /**
 285    * Create a new XMLStreamReader from a JAXP source.  This method is optional.
 286    * @param source the source to read from
 287    * @throws UnsupportedOperationException if this method is not
 288    * supported by this XMLInputFactory
 289    * @throws XMLStreamException
 290    */
 291   public abstract XMLStreamReader createXMLStreamReader(Source source)
 292     throws XMLStreamException;
 293