src/javax/xml/stream/XMLEventFactory.java

Print this page




  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 import javax.xml.stream.events.*;
  31 import javax.xml.namespace.NamespaceContext;
  32 import javax.xml.namespace.QName;
  33 import java.util.Iterator;
  34 /**
  35  * This interface defines a utility class for creating instances of
  36  * XMLEvents
  37  * @version 1.2
  38  * @author Copyright (c) 2009 by Oracle Corporation. All Rights Reserved.
  39  * @see javax.xml.stream.events.StartElement
  40  * @see javax.xml.stream.events.EndElement
  41  * @see javax.xml.stream.events.ProcessingInstruction
  42  * @see javax.xml.stream.events.Comment
  43  * @see javax.xml.stream.events.Characters
  44  * @see javax.xml.stream.events.StartDocument
  45  * @see javax.xml.stream.events.EndDocument
  46  * @see javax.xml.stream.events.DTD
  47  * @since 1.6
  48  */
  49 public abstract class XMLEventFactory {
  50   protected XMLEventFactory(){}
  51 
  52     static final String JAXPFACTORYID = "javax.xml.stream.XMLEventFactory";
  53     static final String DEFAULIMPL = "com.sun.xml.internal.stream.events.XMLEventFactoryImpl";
  54 
  55 
  56   /**
  57    * Create a new instance of the factory
  58    * @throws FactoryConfigurationError if an instance of this factory cannot be loaded
  59    */
  60   public static XMLEventFactory newInstance()
  61     throws FactoryConfigurationError
  62   {
  63     return (XMLEventFactory) FactoryFinder.find(
  64       JAXPFACTORYID,
  65       DEFAULIMPL);
  66   }
  67 
  68   /**
  69    * Create a new instance of the factory.

  70    * This static method creates a new factory instance.
  71    * This method uses the following ordered lookup procedure to determine
  72    * the XMLEventFactory implementation class to load:



  73    *   Use the javax.xml.stream.XMLEventFactory system property.


  74    *   Use the properties file "lib/stax.properties" in the JRE directory.
  75    *     This configuration file is in standard java.util.Properties format
  76    *     and contains the fully qualified name of the implementation class
  77    *     with the key being the system property defined above.
  78    *   Use the Services API (as detailed in the JAR specification), if available,
  79    *     to determine the classname. The Services API will look for a classname
  80    *     in the file META-INF/services/javax.xml.stream.XMLEventFactory in jars
  81    *     available to the runtime.
  82    *   Platform default XMLEventFactory instance.
  83    *





  84    *   Once an application has obtained a reference to a XMLEventFactory it
  85    *   can use the factory to configure and obtain stream instances.
  86    *

  87    *   Note that this is a new method that replaces the deprecated newInstance() method.
  88    *     No changes in behavior are defined by this replacement method relative to
  89    *     the deprecated method.
  90    *
  91    * @throws FactoryConfigurationError if an instance of this factory cannot be loaded


  92    */
  93   public static XMLEventFactory newFactory()
  94     throws FactoryConfigurationError
  95   {
  96     return (XMLEventFactory) FactoryFinder.find(
  97       JAXPFACTORYID,
  98       DEFAULIMPL);
  99   }
 100 
 101   /**
 102    * Create a new instance of the factory
 103    *
 104    * @param factoryId             Name of the factory to find, same as
 105    *                              a property name
 106    * @param classLoader           classLoader to use
 107    * @return the factory implementation
 108    * @throws FactoryConfigurationError if an instance of this factory cannot be loaded
 109    *
 110    * @deprecated  This method has been deprecated to maintain API consistency.
 111    *              All newInstance methods have been replaced with corresponding
 112    *              newFactory methods. The replacement {@link
 113    *              #newFactory(java.lang.String, java.lang.ClassLoader)}
 114    *              method defines no changes in behavior.
 115    */
 116   public static XMLEventFactory newInstance(String factoryId,
 117           ClassLoader classLoader)
 118           throws FactoryConfigurationError {
 119       try {
 120           //do not fallback if given classloader can't find the class, throw exception
 121           return (XMLEventFactory) FactoryFinder.find(factoryId, classLoader, null);
 122       } catch (FactoryFinder.ConfigurationError e) {
 123           throw new FactoryConfigurationError(e.getException(),
 124                   e.getMessage());
 125       }
 126   }
 127 
 128   /**
 129    * Create a new instance of the factory.
 130    * If the classLoader argument is null, then the ContextClassLoader is used.
 131    *
 132    * Note that this is a new method that replaces the deprecated
 133    *   newInstance(String factoryId, ClassLoader classLoader) method.
 134    * No changes in behavior are defined by this replacement method relative
 135    * to the deprecated method.
 136    *
 137    * @param factoryId             Name of the factory to find, same as
 138    *                              a property name
 139    * @param classLoader           classLoader to use
 140    * @return the factory implementation
 141    * @throws FactoryConfigurationError if an instance of this factory cannot be loaded
 142    */
 143   public static XMLEventFactory newFactory(String factoryId,
 144           ClassLoader classLoader)
 145           throws FactoryConfigurationError {
 146       try {
 147           //do not fallback if given classloader can't find the class, throw exception
 148           return (XMLEventFactory) FactoryFinder.find(factoryId, classLoader, null);
 149       } catch (FactoryFinder.ConfigurationError e) {
 150           throw new FactoryConfigurationError(e.getException(),
 151                   e.getMessage());
 152       }
 153   }
 154 
 155  /**
 156    * This method allows setting of the Location on each event that
 157    * is created by this factory.  The values are copied by value into
 158    * the events created by this factory.  To reset the location
 159    * information set the location to null.
 160    * @param location the location to set on each event created
 161    */
 162   public abstract void setLocation(Location location);
 163 
 164   /**
 165    * Create a new Attribute
 166    * @param prefix the prefix of this attribute, may not be null
 167    * @param namespaceURI the attribute value is set to this value, may not be null
 168    * @param localName the local name of the XML name of the attribute, localName cannot be null
 169    * @param value the attribute value to set, may not be null
 170    * @return the Attribute with specified values
 171    */
 172   public abstract Attribute createAttribute(String prefix, String namespaceURI, String localName, String value);




  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 import java.util.Iterator;
  31 import javax.xml.namespace.NamespaceContext;
  32 import javax.xml.namespace.QName;
  33 import javax.xml.stream.events.*;
  34 /**
  35  * This interface defines a utility class for creating instances of
  36  * XMLEvents
  37  * @version 1.2
  38  * @author Copyright (c) 2009 by Oracle Corporation. All Rights Reserved.
  39  * @see javax.xml.stream.events.StartElement
  40  * @see javax.xml.stream.events.EndElement
  41  * @see javax.xml.stream.events.ProcessingInstruction
  42  * @see javax.xml.stream.events.Comment
  43  * @see javax.xml.stream.events.Characters
  44  * @see javax.xml.stream.events.StartDocument
  45  * @see javax.xml.stream.events.EndDocument
  46  * @see javax.xml.stream.events.DTD
  47  * @since 1.6
  48  */
  49 public abstract class XMLEventFactory {
  50   protected XMLEventFactory(){}
  51 
  52     static final String JAXPFACTORYID = "javax.xml.stream.XMLEventFactory";
  53     static final String DEFAULIMPL = "com.sun.xml.internal.stream.events.XMLEventFactoryImpl";
  54 
  55 
  56   /**
  57    * Create a new instance of the factory
  58    * @throws FactoryConfigurationError if an instance of this factory cannot be loaded
  59    */
  60   public static XMLEventFactory newInstance()
  61     throws FactoryConfigurationError
  62   {
  63     return FactoryFinder.find(XMLEventFactory.class, DEFAULIMPL);


  64   }
  65 
  66   /**
  67    * Create a new instance of the factory.
  68    * <p>
  69    * This static method creates a new factory instance.
  70    * This method uses the following ordered lookup procedure to determine
  71    * the XMLEventFactory implementation class to load:
  72    * </p>
  73    * <ul>
  74    * <li>
  75    *   Use the javax.xml.stream.XMLEventFactory system property.
  76    * </li>
  77    * <li>
  78    *   Use the properties file "lib/stax.properties" in the JRE directory.
  79    *     This configuration file is in standard java.util.Properties format
  80    *     and contains the fully qualified name of the implementation class
  81    *     with the key being the system property defined above.
  82    * </li>
  83    * <li>
  84    *   Use the service-provider loading facilities, defined by the
  85    *   {@link java.util.ServiceLoader} class, to attempt to locate and load an
  86    *   implementation of the service.
  87    * </li>
  88    * <li>
  89    *   Otherwise, the system-default implementation is returned.
  90    * </li>
  91    * </ul>
  92    * <p>
  93    *   Once an application has obtained a reference to a XMLEventFactory it
  94    *   can use the factory to configure and obtain stream instances.
  95    * </p>
  96    * <p>
  97    *   Note that this is a new method that replaces the deprecated newInstance() method.
  98    *     No changes in behavior are defined by this replacement method relative to
  99    *     the deprecated method.
 100    * </p>
 101    * @throws FactoryConfigurationError in case of {@linkplain
 102    *   java.util.ServiceConfigurationError service configuration error} or if
 103    *   the implementation is not available or cannot be instantiated.
 104    */
 105   public static XMLEventFactory newFactory()
 106     throws FactoryConfigurationError
 107   {
 108     return FactoryFinder.find(XMLEventFactory.class, DEFAULIMPL);


 109   }
 110 
 111   /**
 112    * Create a new instance of the factory
 113    *
 114    * @param factoryId             Name of the factory to find, same as
 115    *                              a property name
 116    * @param classLoader           classLoader to use
 117    * @return the factory implementation
 118    * @throws FactoryConfigurationError if an instance of this factory cannot be loaded
 119    *
 120    * @deprecated  This method has been deprecated to maintain API consistency.
 121    *              All newInstance methods have been replaced with corresponding
 122    *              newFactory methods. The replacement {@link
 123    *              #newFactory(java.lang.String, java.lang.ClassLoader)}
 124    *              method defines no changes in behavior.
 125    */
 126   public static XMLEventFactory newInstance(String factoryId,
 127           ClassLoader classLoader)
 128           throws FactoryConfigurationError {

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




 131   }
 132 
 133   /**
 134    * Create a new instance of the factory.
 135    * If the classLoader argument is null, then the ContextClassLoader is used.
 136    *
 137    * Note that this is a new method that replaces the deprecated
 138    *   newInstance(String factoryId, ClassLoader classLoader) method.
 139    * No changes in behavior are defined by this replacement method relative
 140    * to the deprecated method.
 141    *
 142    * @param factoryId             Name of the factory to find, same as
 143    *                              a property name
 144    * @param classLoader           classLoader to use
 145    * @return the factory implementation
 146    * @throws FactoryConfigurationError if an instance of this factory cannot be loaded
 147    */
 148   public static XMLEventFactory newFactory(String factoryId,
 149                                            ClassLoader classLoader)
 150           throws FactoryConfigurationError {

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




 153   }
 154 
 155  /**
 156    * This method allows setting of the Location on each event that
 157    * is created by this factory.  The values are copied by value into
 158    * the events created by this factory.  To reset the location
 159    * information set the location to null.
 160    * @param location the location to set on each event created
 161    */
 162   public abstract void setLocation(Location location);
 163 
 164   /**
 165    * Create a new Attribute
 166    * @param prefix the prefix of this attribute, may not be null
 167    * @param namespaceURI the attribute value is set to this value, may not be null
 168    * @param localName the local name of the XML name of the attribute, localName cannot be null
 169    * @param value the attribute value to set, may not be null
 170    * @return the Attribute with specified values
 171    */
 172   public abstract Attribute createAttribute(String prefix, String namespaceURI, String localName, String value);