src/javax/xml/stream/XMLOutputFactory.java

Print this page




 103  *
 104  * @version 1.2
 105  * @author Copyright (c) 2009 by Oracle Corporation. All Rights Reserved.
 106  * @see XMLInputFactory
 107  * @see XMLEventWriter
 108  * @see XMLStreamWriter
 109  * @since 1.6
 110  */
 111 public abstract class XMLOutputFactory {
 112   /**
 113    * Property used to set prefix defaulting on the output side
 114    */
 115   public static final String IS_REPAIRING_NAMESPACES=
 116     "javax.xml.stream.isRepairingNamespaces";
 117 
 118   static final String DEFAULIMPL = "com.sun.xml.internal.stream.XMLOutputFactoryImpl";
 119 
 120   protected XMLOutputFactory(){}
 121 
 122   /**
 123    * Create a new instance of the factory.

 124    * @throws FactoryConfigurationError if an instance of this factory cannot be loaded
 125    */
 126   public static XMLOutputFactory newInstance()
 127     throws FactoryConfigurationError
 128   {
 129     return (XMLOutputFactory) FactoryFinder.find("javax.xml.stream.XMLOutputFactory",
 130                                                  DEFAULIMPL);
 131   }
 132 
 133   /**
 134    * Create a new instance of the factory.

 135    * This static method creates a new factory instance. This method uses the
 136    * following ordered lookup procedure to determine the XMLOutputFactory
 137    * implementation class to load:



 138    *   Use the javax.xml.stream.XMLOutputFactory system property.


 139    *   Use the properties file "lib/stax.properties" in the JRE directory.
 140    *     This configuration file is in standard java.util.Properties format
 141    *     and contains the fully qualified name of the implementation class
 142    *     with the key being the system property defined above.
 143    *   Use the Services API (as detailed in the JAR specification), if available,
 144    *     to determine the classname. The Services API will look for a classname
 145    *     in the file META-INF/services/javax.xml.stream.XMLOutputFactory in jars
 146    *     available to the runtime.
 147    *   Platform default XMLOutputFactory instance.
 148    *




 149    * Once an application has obtained a reference to a XMLOutputFactory it
 150    * can use the factory to configure and obtain stream instances.
 151    *

 152    * Note that this is a new method that replaces the deprecated newInstance() method.
 153    *   No changes in behavior are defined by this replacement method relative to the
 154    *   deprecated method.
 155    *
 156    * @throws FactoryConfigurationError if an instance of this factory cannot be loaded


 157    */
 158   public static XMLOutputFactory newFactory()
 159     throws FactoryConfigurationError
 160   {
 161     return (XMLOutputFactory) FactoryFinder.find("javax.xml.stream.XMLOutputFactory",
 162                                                  DEFAULIMPL);
 163   }
 164 
 165   /**
 166    * Create a new instance of the factory.
 167    *
 168    * @param factoryId             Name of the factory to find, same as
 169    *                              a property name
 170    * @param classLoader           classLoader to use
 171    * @return the factory implementation
 172    * @throws FactoryConfigurationError if an instance of this factory cannot be loaded
 173    *
 174    * @deprecated  This method has been deprecated because it returns an
 175    *              instance of XMLInputFactory, which is of the wrong class.
 176    *              Use the new method {@link #newFactory(java.lang.String,
 177    *              java.lang.ClassLoader)} instead.
 178    */
 179   public static XMLInputFactory newInstance(String factoryId,
 180           ClassLoader classLoader)
 181           throws FactoryConfigurationError {
 182       try {
 183           //do not fallback if given classloader can't find the class, throw exception
 184           return (XMLInputFactory) FactoryFinder.find(factoryId, classLoader, null);
 185       } catch (FactoryFinder.ConfigurationError e) {
 186           throw new FactoryConfigurationError(e.getException(),
 187                   e.getMessage());
 188       }
 189   }
 190 
 191   /**
 192    * Create a new instance of the factory.
 193    * If the classLoader argument is null, then the ContextClassLoader is used.
























 194    *

 195    * Note that this is a new method that replaces the deprecated
 196    *   newInstance(String factoryId, ClassLoader classLoader) method.
 197    *
 198    *   No changes in behavior are defined by this replacement method relative
 199    *   to the deprecated method.
 200    *
 201    *
 202    * @param factoryId             Name of the factory to find, same as
 203    *                              a property name
 204    * @param classLoader           classLoader to use
 205    * @return the factory implementation
 206    * @throws FactoryConfigurationError if an instance of this factory cannot be loaded


 207    */
 208   public static XMLOutputFactory newFactory(String factoryId,
 209           ClassLoader classLoader)
 210           throws FactoryConfigurationError {
 211       try {
 212           //do not fallback if given classloader can't find the class, throw exception
 213           return (XMLOutputFactory) FactoryFinder.find(factoryId, classLoader, null);
 214       } catch (FactoryFinder.ConfigurationError e) {
 215           throw new FactoryConfigurationError(e.getException(),
 216                   e.getMessage());
 217       }
 218   }
 219 
 220   /**
 221    * Create a new XMLStreamWriter that writes to a writer
 222    * @param stream the writer to write to
 223    * @throws XMLStreamException
 224    */
 225   public abstract XMLStreamWriter createXMLStreamWriter(java.io.Writer stream) throws XMLStreamException;
 226 
 227   /**
 228    * Create a new XMLStreamWriter that writes to a stream
 229    * @param stream the stream to write to
 230    * @throws XMLStreamException
 231    */
 232   public abstract XMLStreamWriter createXMLStreamWriter(java.io.OutputStream stream) throws XMLStreamException;
 233 
 234   /**
 235    * Create a new XMLStreamWriter that writes to a stream
 236    * @param stream the stream to write to
 237    * @param encoding the encoding to use




 103  *
 104  * @version 1.2
 105  * @author Copyright (c) 2009 by Oracle Corporation. All Rights Reserved.
 106  * @see XMLInputFactory
 107  * @see XMLEventWriter
 108  * @see XMLStreamWriter
 109  * @since 1.6
 110  */
 111 public abstract class XMLOutputFactory {
 112   /**
 113    * Property used to set prefix defaulting on the output side
 114    */
 115   public static final String IS_REPAIRING_NAMESPACES=
 116     "javax.xml.stream.isRepairingNamespaces";
 117 
 118   static final String DEFAULIMPL = "com.sun.xml.internal.stream.XMLOutputFactoryImpl";
 119 
 120   protected XMLOutputFactory(){}
 121 
 122   /**
 123    * Creates a new instance of the factory in exactly the same manner as the
 124    * {@link #newFactory()} method.
 125    * @throws FactoryConfigurationError if an instance of this factory cannot be loaded
 126    */
 127   public static XMLOutputFactory newInstance()
 128     throws FactoryConfigurationError
 129   {
 130     return FactoryFinder.find(XMLOutputFactory.class, DEFAULIMPL);

 131   }
 132 
 133   /**
 134    * Create a new instance of the factory.
 135    * <p>
 136    * This static method creates a new factory instance. This method uses the
 137    * following ordered lookup procedure to determine the XMLOutputFactory
 138    * implementation class to load:
 139    * </p>
 140    * <ul>
 141    * <li>
 142    *   Use the javax.xml.stream.XMLOutputFactory system property.
 143    * </li>
 144    * <li>
 145    *   Use the properties file "lib/stax.properties" in the JRE directory.
 146    *     This configuration file is in standard java.util.Properties format
 147    *     and contains the fully qualified name of the implementation class
 148    *     with the key being the system property defined above.
 149    * </li>
 150    * <li>
 151    *   Use the service-provider loading facilities, defined by the
 152    *   {@link java.util.ServiceLoader} class, to attempt to locate and load an
 153    *   implementation of the service.
 154    * </li>
 155    * <li>
 156    *   Otherwise, the system-default implementation is returned.
 157    * </li>
 158    * <p>
 159    * Once an application has obtained a reference to a XMLOutputFactory it
 160    * can use the factory to configure and obtain stream instances.
 161    * </p>
 162    * <p>
 163    * Note that this is a new method that replaces the deprecated newInstance() method.
 164    *   No changes in behavior are defined by this replacement method relative to the
 165    *   deprecated method.
 166    * </p>
 167    * @throws FactoryConfigurationError in case of {@linkplain
 168    *   java.util.ServiceConfigurationError service configuration error} or if
 169    *   the implementation is not available or cannot be instantiated.
 170    */
 171   public static XMLOutputFactory newFactory()
 172     throws FactoryConfigurationError
 173   {
 174     return FactoryFinder.find(XMLOutputFactory.class, DEFAULIMPL);

 175   }
 176 
 177   /**
 178    * Create a new instance of the factory.
 179    *
 180    * @param factoryId             Name of the factory to find, same as
 181    *                              a property name
 182    * @param classLoader           classLoader to use
 183    * @return the factory implementation
 184    * @throws FactoryConfigurationError if an instance of this factory cannot be loaded
 185    *
 186    * @deprecated  This method has been deprecated because it returns an
 187    *              instance of XMLInputFactory, which is of the wrong class.
 188    *              Use the new method {@link #newFactory(java.lang.String,
 189    *              java.lang.ClassLoader)} instead.
 190    */
 191   public static XMLInputFactory newInstance(String factoryId,
 192           ClassLoader classLoader)
 193           throws FactoryConfigurationError {

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




 196   }
 197 
 198   /**
 199    * Create a new instance of the factory.
 200    * If the classLoader argument is null, then the ContextClassLoader is used.
 201    * <p>
 202    * This method uses the following ordered lookup procedure to determine
 203    * the XMLOutputFactory implementation class to load:
 204    * </p>
 205    * <ul>
 206    * <li>
 207    *   Use the value of the system property identified by {@code factoryId}.
 208    * </li>
 209    * <li>
 210    *   Use the properties file "lib/stax.properties" in the JRE directory.
 211    *     This configuration file is in standard java.util.Properties format
 212    *     and contains the fully qualified name of the implementation class
 213    *     with the key being the given {@code factoryId}.
 214    * </li>
 215    * <li>
 216    *   If {@code factoryId} is the base service class name,
 217    *   use the service-provider loading facilities, defined by the
 218    *   {@link java.util.ServiceLoader} class, to attempt to locate and load an
 219    *   implementation of the service.
 220    * </li>
 221    * <li>
 222    *   Otherwise, throws a {@link FactoryConfigurationError}.
 223    * </li>
 224    * </ul>
 225    *
 226    * <p>
 227    * Note that this is a new method that replaces the deprecated
 228    *   {@link #newInstance(java.lang.String, java.lang.ClassLoader)
 229    *   newInstance(String factoryId, ClassLoader classLoader)} method.
 230    * No changes in behavior are defined by this replacement method relative
 231    * to the deprecated method.
 232    * </p>
 233    *
 234    * @param factoryId             Name of the factory to find, same as
 235    *                              a property name
 236    * @param classLoader           classLoader to use
 237    * @return the factory implementation
 238    * @throws FactoryConfigurationError in case of {@linkplain
 239    *   java.util.ServiceConfigurationError service configuration error} or if
 240    *   the implementation is not available or cannot be instantiated.
 241    */
 242   public static XMLOutputFactory newFactory(String factoryId,
 243           ClassLoader classLoader)
 244           throws FactoryConfigurationError {

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




 247   }
 248 
 249   /**
 250    * Create a new XMLStreamWriter that writes to a writer
 251    * @param stream the writer to write to
 252    * @throws XMLStreamException
 253    */
 254   public abstract XMLStreamWriter createXMLStreamWriter(java.io.Writer stream) throws XMLStreamException;
 255 
 256   /**
 257    * Create a new XMLStreamWriter that writes to a stream
 258    * @param stream the stream to write to
 259    * @throws XMLStreamException
 260    */
 261   public abstract XMLStreamWriter createXMLStreamWriter(java.io.OutputStream stream) throws XMLStreamException;
 262 
 263   /**
 264    * Create a new XMLStreamWriter that writes to a stream
 265    * @param stream the stream to write to
 266    * @param encoding the encoding to use