1 /*
   2  * Copyright (c) 2009, 2017, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package javax.xml.stream;
  27 
  28 import com.sun.xml.internal.stream.XMLOutputFactoryImpl;
  29 import javax.xml.transform.Result;
  30 
  31 /**
  32  * Defines an abstract implementation of a factory for
  33  * getting XMLEventWriters and XMLStreamWriters.
  34  *
  35  * The following table defines the standard properties of this specification.
  36  * Each property varies in the level of support required by each implementation.
  37  * The level of support required is described in the 'Required' column.
  38  *
  39  *     <table class="striped">
  40  *     <caption>Configuration Parameters</caption>
  41  *     <thead>
  42  *      <tr>
  43  *        <th>Property Name</th>
  44  *        <th>Behavior</th>
  45  *        <th>Return type</th>
  46  *        <th>Default Value</th>
  47  *        <th>Required</th>
  48  *              </tr>
  49  *    </thead>
  50  *    <tbody>
  51  *         <tr><td>javax.xml.stream.isRepairingNamespaces</td><td>defaults prefixes
  52  *                 on the output side</td><td>Boolean</td><td>False</td><td>Yes</td></tr>
  53  *      </tbody>
  54  *   </table>
  55  *
  56  * <p>The following paragraphs describe the namespace and prefix repair algorithm:
  57  *
  58  * <p>The property can be set with the following code line:
  59  * {@code setProperty("javax.xml.stream.isRepairingNamespaces", new Boolean(true|false));}
  60  *
  61  * <p>This property specifies that the writer default namespace prefix declarations.
  62  * The default value is false.
  63  *
  64  * <p>If a writer isRepairingNamespaces it will create a namespace declaration
  65  * on the current StartElement for
  66  * any attribute that does not
  67  * currently have a namespace declaration in scope.  If the StartElement
  68  * has a uri but no prefix specified a prefix will be assigned, if the prefix
  69  * has not been declared in a parent of the current StartElement it will be declared
  70  * on the current StartElement.  If the defaultNamespace is bound and in scope
  71  * and the default namespace matches the URI of the attribute or StartElement
  72  * QName no prefix will be assigned.
  73  *
  74  * <p>If an element or attribute name has a prefix, but is not
  75  * bound to any namespace URI, then the prefix will be removed
  76  * during serialization.
  77  *
  78  * <p>If element and/or attribute names in the same start or
  79  * empty-element tag are bound to different namespace URIs and
  80  * are using the same prefix then the element or the first
  81  * occurring attribute retains the original prefix and the
  82  * following attributes have their prefixes replaced with a
  83  * new prefix that is bound to the namespace URIs of those
  84  * attributes.
  85  *
  86  * <p>If an element or attribute name uses a prefix that is
  87  * bound to a different URI than that inherited from the
  88  * namespace context of the parent of that element and there
  89  * is no namespace declaration in the context of the current
  90  * element then such a namespace declaration is added.
  91  *
  92  * <p>If an element or attribute name is bound to a prefix and
  93  * there is a namespace declaration that binds that prefix
  94  * to a different URI then that namespace declaration is
  95  * either removed if the correct mapping is inherited from
  96  * the parent context of that element, or changed to the
  97  * namespace URI of the element or attribute using that prefix.
  98  *
  99  * @version 1.2
 100  * @author Copyright (c) 2009, 2015 by Oracle Corporation. All Rights Reserved.
 101  * @see XMLInputFactory
 102  * @see XMLEventWriter
 103  * @see XMLStreamWriter
 104  * @since 1.6
 105  */
 106 public abstract class XMLOutputFactory {
 107   /**
 108    * Property used to set prefix defaulting on the output side
 109    */
 110   public static final String IS_REPAIRING_NAMESPACES=
 111     "javax.xml.stream.isRepairingNamespaces";
 112 
 113   static final String DEFAULIMPL = "com.sun.xml.internal.stream.XMLOutputFactoryImpl";
 114 
 115   protected XMLOutputFactory(){}
 116 
 117    /**
 118    * Creates a new instance of the {@code XMLOutputFactory} builtin
 119    * system-default implementation.
 120    *
 121    * @return A new instance of the {@code XMLOutputFactory} builtin
 122    *         system-default implementation.
 123    *
 124    * @since 9
 125    */
 126   public static XMLOutputFactory newDefaultFactory() {
 127       return new XMLOutputFactoryImpl();
 128   }
 129 
 130   /**
 131    * Creates a new instance of the factory in exactly the same manner as the
 132    * {@link #newFactory()} method.
 133    * @throws FactoryConfigurationError if an instance of this factory cannot be loaded
 134    */
 135   public static XMLOutputFactory newInstance()
 136     throws FactoryConfigurationError
 137   {
 138     return FactoryFinder.find(XMLOutputFactory.class, DEFAULIMPL);
 139   }
 140 
 141   /**
 142    * Create a new instance of the factory.
 143    * <p>
 144    * This static method creates a new factory instance. This method uses the
 145    * following ordered lookup procedure to determine the XMLOutputFactory
 146    * implementation class to load:
 147    * <ul>
 148    * <li>
 149    *   Use the javax.xml.stream.XMLOutputFactory system property.
 150    * </li>
 151    * <li>
 152    *   <p>
 153    *   Use the configuration file "stax.properties". The file is in standard
 154    *   {@link java.util.Properties} format and typically located in the
 155    *   {@code conf} directory of the Java installation. It contains the fully qualified
 156    *   name of the implementation class with the key being the system property
 157    *   defined above.
 158    *
 159    *   <p>
 160    *   The stax.properties file is read only once by the implementation
 161    *   and its values are then cached for future use.  If the file does not exist
 162    *   when the first attempt is made to read from it, no further attempts are
 163    *   made to check for its existence.  It is not possible to change the value
 164    *   of any property in stax.properties after it has been read for the first time.
 165    *
 166    *   <p>
 167    *   Use the jaxp configuration file "jaxp.properties". The file is in the same
 168    *   format as stax.properties and will only be read if stax.properties does
 169    *   not exist.
 170    * </li>
 171    * <li>
 172    *   <p>
 173    *   Use the service-provider loading facility, defined by the
 174    *   {@link java.util.ServiceLoader} class, to attempt to locate and load an
 175    *   implementation of the service using the {@linkplain
 176    *   java.util.ServiceLoader#load(java.lang.Class) default loading mechanism}:
 177    *   the service-provider loading facility will use the {@linkplain
 178    *   java.lang.Thread#getContextClassLoader() current thread's context class loader}
 179    *   to attempt to load the service. If the context class
 180    *   loader is null, the {@linkplain
 181    *   ClassLoader#getSystemClassLoader() system class loader} will be used.
 182    * </li>
 183    * <li>
 184    *   <p>
 185    *   Otherwise, the {@linkplain #newDefaultFactory() system-default}
 186    *   implementation is returned.
 187    * </li>
 188    * </ul>
 189    * <p>
 190    * Once an application has obtained a reference to a XMLOutputFactory it
 191    * can use the factory to configure and obtain stream instances.
 192    *
 193    * @throws FactoryConfigurationError in case of {@linkplain
 194    *   java.util.ServiceConfigurationError service configuration error} or if
 195    *   the implementation is not available or cannot be instantiated.
 196    */
 197   public static XMLOutputFactory newFactory()
 198     throws FactoryConfigurationError
 199   {
 200     return FactoryFinder.find(XMLOutputFactory.class, DEFAULIMPL);
 201   }
 202 
 203   /**
 204    * Create a new instance of the factory.
 205    *
 206    * @param factoryId             Name of the factory to find, same as
 207    *                              a property name
 208    * @param classLoader           classLoader to use
 209    * @return the factory implementation
 210    * @throws FactoryConfigurationError if an instance of this factory cannot be loaded
 211    *
 212    * @deprecated  This method has been deprecated because it returns an
 213    *              instance of XMLInputFactory, which is of the wrong class.
 214    *              Use the new method {@link #newFactory(java.lang.String,
 215    *              java.lang.ClassLoader)} instead.
 216    */
 217   @Deprecated(since="1.7")
 218   public static XMLInputFactory newInstance(String factoryId,
 219           ClassLoader classLoader)
 220           throws FactoryConfigurationError {
 221       //do not fallback if given classloader can't find the class, throw exception
 222       return FactoryFinder.find(XMLInputFactory.class, factoryId, classLoader, null);
 223   }
 224 
 225   /**
 226    * Create a new instance of the factory.
 227    * If the classLoader argument is null, then the ContextClassLoader is used.
 228    * <p>
 229    * This method uses the following ordered lookup procedure to determine
 230    * the XMLOutputFactory implementation class to load:
 231    * <ul>
 232    * <li>
 233    *   Use the value of the system property identified by {@code factoryId}.
 234    * </li>
 235    * <li>
 236    *   <p>
 237    *   Use the configuration file "stax.properties". The file is in standard
 238    *   {@link java.util.Properties} format and typically located in the
 239    *   {@code conf} directory of the Java installation. It contains the fully qualified
 240    *   name of the implementation class with the key being the system property
 241    *   defined above.
 242    *
 243    *   <p>
 244    *   The stax.properties file is read only once by the implementation
 245    *   and its values are then cached for future use.  If the file does not exist
 246    *   when the first attempt is made to read from it, no further attempts are
 247    *   made to check for its existence.  It is not possible to change the value
 248    *   of any property in stax.properties after it has been read for the first time.
 249    *
 250    *   <p>
 251    *   Use the jaxp configuration file "jaxp.properties". The file is in the same
 252    *   format as stax.properties and will only be read if stax.properties does
 253    *   not exist.
 254    * </li>
 255    * <li>
 256    *   <p>
 257    *   If {@code factoryId} is "javax.xml.stream.XMLOutputFactory",
 258    *   use the service-provider loading facility, defined by the
 259    *   {@link java.util.ServiceLoader} class, to attempt to {@linkplain
 260    *   java.util.ServiceLoader#load(java.lang.Class, java.lang.ClassLoader) locate and load}
 261    *   an implementation of the service using the specified {@code ClassLoader}.
 262    *   If {@code classLoader} is null, the {@linkplain
 263    *   java.util.ServiceLoader#load(java.lang.Class) default loading mechanism} will apply:
 264    *   That is, the service-provider loading facility will use the {@linkplain
 265    *   java.lang.Thread#getContextClassLoader() current thread's context class loader}
 266    *   to attempt to load the service. If the context class
 267    *   loader is null, the {@linkplain
 268    *   ClassLoader#getSystemClassLoader() system class loader} will be used.
 269    * </li>
 270    * <li>
 271    *   <p>
 272    *   Otherwise, throws a {@link FactoryConfigurationError}.
 273    * </li>
 274    * </ul>
 275    *
 276    * @apiNote The parameter factoryId defined here is inconsistent with that
 277    * of other JAXP factories where the first parameter is fully qualified
 278    * factory class name that provides implementation of the factory.
 279    *
 280    * <p>
 281    *   Note that this is a new method that replaces the deprecated
 282    *   {@link #newInstance(java.lang.String, java.lang.ClassLoader)
 283    *   newInstance(String factoryId, ClassLoader classLoader)} method.
 284    *   The original method was incorrectly defined to return XMLInputFactory.
 285    *
 286    *
 287    * @param factoryId             Name of the factory to find, same as
 288    *                              a property name
 289    * @param classLoader           classLoader to use
 290    * @return the factory implementation
 291    * @throws FactoryConfigurationError in case of {@linkplain
 292    *   java.util.ServiceConfigurationError service configuration error} or if
 293    *   the implementation is not available or cannot be instantiated.
 294    */
 295   public static XMLOutputFactory newFactory(String factoryId,
 296           ClassLoader classLoader)
 297           throws FactoryConfigurationError {
 298       //do not fallback if given classloader can't find the class, throw exception
 299       return FactoryFinder.find(XMLOutputFactory.class, factoryId, classLoader, null);
 300   }
 301 
 302   /**
 303    * Create a new XMLStreamWriter that writes to a writer
 304    * @param stream the writer to write to
 305    * @throws XMLStreamException
 306    */
 307   public abstract XMLStreamWriter createXMLStreamWriter(java.io.Writer stream) throws XMLStreamException;
 308 
 309   /**
 310    * Create a new XMLStreamWriter that writes to a stream
 311    * @param stream the stream to write to
 312    * @throws XMLStreamException
 313    */
 314   public abstract XMLStreamWriter createXMLStreamWriter(java.io.OutputStream stream) throws XMLStreamException;
 315 
 316   /**
 317    * Create a new XMLStreamWriter that writes to a stream
 318    * @param stream the stream to write to
 319    * @param encoding the encoding to use
 320    * @throws XMLStreamException
 321    */
 322   public abstract XMLStreamWriter createXMLStreamWriter(java.io.OutputStream stream,
 323                                          String encoding) throws XMLStreamException;
 324 
 325   /**
 326    * Create a new XMLStreamWriter that writes to a JAXP result.  This method is optional.
 327    * @param result the result to write to
 328    * @throws UnsupportedOperationException if this method is not
 329    * supported by this XMLOutputFactory
 330    * @throws XMLStreamException
 331    */
 332   public abstract XMLStreamWriter createXMLStreamWriter(Result result) throws XMLStreamException;
 333 
 334 
 335   /**
 336    * Create a new XMLEventWriter that writes to a JAXP result.  This method is optional.
 337    * @param result the result to write to
 338    * @throws UnsupportedOperationException if this method is not
 339    * supported by this XMLOutputFactory
 340    * @throws XMLStreamException
 341    */
 342   public abstract XMLEventWriter createXMLEventWriter(Result result) throws XMLStreamException;
 343 
 344   /**
 345    * Create a new XMLEventWriter that writes to a stream
 346    * @param stream the stream to write to
 347    * @throws XMLStreamException
 348    */
 349   public abstract XMLEventWriter createXMLEventWriter(java.io.OutputStream stream) throws XMLStreamException;
 350 
 351 
 352 
 353   /**
 354    * Create a new XMLEventWriter that writes to a stream
 355    * @param stream the stream to write to
 356    * @param encoding the encoding to use
 357    * @throws XMLStreamException
 358    */
 359   public abstract XMLEventWriter createXMLEventWriter(java.io.OutputStream stream,
 360                                                      String encoding) throws XMLStreamException;
 361 
 362   /**
 363    * Create a new XMLEventWriter that writes to a writer
 364    * @param stream the stream to write to
 365    * @throws XMLStreamException
 366    */
 367   public abstract XMLEventWriter createXMLEventWriter(java.io.Writer stream) throws XMLStreamException;
 368 
 369   /**
 370    * Allows the user to set specific features/properties on the underlying implementation.
 371    * @param name The name of the property
 372    * @param value The value of the property
 373    * @throws java.lang.IllegalArgumentException if the property is not supported
 374    */
 375   public abstract void setProperty(java.lang.String name,
 376                                     Object value)
 377     throws IllegalArgumentException;
 378 
 379   /**
 380    * Get a feature/property on the underlying implementation
 381    * @param name The name of the property
 382    * @return The value of the property
 383    * @throws java.lang.IllegalArgumentException if the property is not supported
 384    */
 385   public abstract Object getProperty(java.lang.String name)
 386     throws IllegalArgumentException;
 387 
 388   /**
 389    * Query the set of properties that this factory supports.
 390    *
 391    * @param name The name of the property (may not be null)
 392    * @return true if the property is supported and false otherwise
 393    */
 394   public abstract boolean isPropertySupported(String name);
 395 }