src/javax/xml/stream/XMLOutputFactory.java

Print this page




 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




 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    * Same as {@link #newFactory()}.
 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    *   if present, otherwise, use the properties file "lib/jaxp.properties"
 147    *   in the JRE directory.
 148    *     These configuration files are in standard java.util.Properties format
 149    *     and contain the fully qualified name of the implementation class
 150    *     with the key being the system property defined above.
 151    * </li>
 152    * <li>
 153    *   Use the service-provider loading facilities, defined by the
 154    *   {@link java.util.ServiceLoader} class, to attempt to locate and load an
 155    *   implementation of the service.
 156    * </li>
 157    * <li>
 158    *   Otherwise, the system-default implementation is returned.
 159    * </li>
 160    * <p>
 161    * Once an application has obtained a reference to a XMLOutputFactory it
 162    * can use the factory to configure and obtain stream instances.
 163    * </p>
 164    * <p>
 165    * Note that this is a new method that replaces the deprecated newInstance() method.
 166    *   No changes in behavior are defined by this replacement method relative to the
 167    *   deprecated method.
 168    * </p>
 169    * @throws FactoryConfigurationError in case of {@linkplain
 170    *   java.util.ServiceConfigurationError service configuration error} or if
 171    *   the implementation is not available or cannot be instantiated.
 172    */
 173   public static XMLOutputFactory newFactory()
 174     throws FactoryConfigurationError
 175   {
 176     return FactoryFinder.find(XMLOutputFactory.class, DEFAULIMPL);

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

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




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

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




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