< prev index next >

src/java.xml/share/classes/javax/xml/stream/XMLOutputFactory.java

Print this page




  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="2">
  45  *          Configuration parameters
  46  *        </th>
  47  *      </tr>
  48  *    </thead>
  49  *    <tbody>
  50  *      <tr>
  51  *        <th>Property Name</th>
  52  *        <th>Behavior</th>
  53  *        <th>Return type</th>
  54  *        <th>Default Value</th>
  55  *        <th>Required</th>
  56  *              </tr>
  57  *         <tr><td>javax.xml.stream.isRepairingNamespaces</td><td>defaults prefixes on the output side</td><td>Boolean</td><td>False</td><td>Yes</td></tr>

  58  *      </tbody>
  59  *   </table>
  60  *
  61  * <p>The following paragraphs describe the namespace and prefix repair algorithm:</p>
  62  *
  63  * <p>The property can be set with the following code line:
  64  * <code>setProperty("javax.xml.stream.isRepairingNamespaces",new Boolean(true|false));</code></p>
  65  *
  66  * <p>This property specifies that the writer default namespace prefix declarations.
  67  * The default value is false. </p>
  68  *
  69  * <p>If a writer isRepairingNamespaces it will create a namespace declaration
  70  * on the current StartElement for
  71  * any attribute that does not
  72  * currently have a namespace declaration in scope.  If the StartElement
  73  * has a uri but no prefix specified a prefix will be assigned, if the prefix
  74  * has not been declared in a parent of the current StartElement it will be declared
  75  * on the current StartElement.  If the defaultNamespace is bound and in scope
  76  * and the default namespace matches the URI of the attribute or StartElement
  77  * QName no prefix will be assigned.</p>
  78  *
  79  * <p>If an element or attribute name has a prefix, but is not
  80  * bound to any namespace URI, then the prefix will be removed
  81  * during serialization.</p>
  82  *
  83  * <p>If element and/or attribute names in the same start or
  84  * empty-element tag are bound to different namespace URIs and
  85  * are using the same prefix then the element or the first
  86  * occurring attribute retains the original prefix and the
  87  * following attributes have their prefixes replaced with a
  88  * new prefix that is bound to the namespace URIs of those
  89  * attributes. </p>
  90  *
  91  * <p>If an element or attribute name uses a prefix that is
  92  * bound to a different URI than that inherited from the
  93  * namespace context of the parent of that element and there
  94  * is no namespace declaration in the context of the current
  95  * element then such a namespace declaration is added. </p>
  96  *
  97  * <p>If an element or attribute name is bound to a prefix and
  98  * there is a namespace declaration that binds that prefix
  99  * to a different URI then that namespace declaration is
 100  * either removed if the correct mapping is inherited from
 101  * the parent context of that element, or changed to the
 102  * namespace URI of the element or attribute using that prefix.</p>
 103  *
 104  * @version 1.2
 105  * @author Copyright (c) 2009, 2015 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    *   <p>
 146    *   Use the configuration file "stax.properties". The file is in standard
 147    *   {@link java.util.Properties} format and typically located in the
 148    *   {@code conf} directory of the Java installation. It contains the fully qualified
 149    *   name of the implementation class with the key being the system property
 150    *   defined above.
 151    *
 152    *   <p>
 153    *   The stax.properties file is read only once by the implementation
 154    *   and its values are then cached for future use.  If the file does not exist
 155    *   when the first attempt is made to read from it, no further attempts are
 156    *   made to check for its existence.  It is not possible to change the value
 157    *   of any property in stax.properties after it has been read for the first time.
 158    *
 159    *   <p>
 160    *   Use the jaxp configuration file "jaxp.properties". The file is in the same
 161    *   format as stax.properties and will only be read if stax.properties does
 162    *   not exist.
 163    * </li>
 164    * <li>
 165    *   <p>
 166    *   Use the service-provider loading facility, defined by the
 167    *   {@link java.util.ServiceLoader} class, to attempt to locate and load an
 168    *   implementation of the service using the {@linkplain
 169    *   java.util.ServiceLoader#load(java.lang.Class) default loading mechanism}:
 170    *   the service-provider loading facility will use the {@linkplain
 171    *   java.lang.Thread#getContextClassLoader() current thread's context class loader}
 172    *   to attempt to load the service. If the context class
 173    *   loader is null, the {@linkplain
 174    *   ClassLoader#getSystemClassLoader() system class loader} will be used.
 175    * </li>
 176    * <li>
 177    *   <p>
 178    *   Otherwise, the system-default implementation is returned.
 179    * </li>

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


 205    * @throws FactoryConfigurationError if an instance of this factory cannot be loaded
 206    *
 207    * @deprecated  This method has been deprecated because it returns an
 208    *              instance of XMLInputFactory, which is of the wrong class.
 209    *              Use the new method {@link #newFactory(java.lang.String,
 210    *              java.lang.ClassLoader)} instead.
 211    */
 212   public static XMLInputFactory newInstance(String factoryId,
 213           ClassLoader classLoader)
 214           throws FactoryConfigurationError {
 215       //do not fallback if given classloader can't find the class, throw exception
 216       return FactoryFinder.find(XMLInputFactory.class, factoryId, classLoader, null);
 217   }
 218 
 219   /**
 220    * Create a new instance of the factory.
 221    * If the classLoader argument is null, then the ContextClassLoader is used.
 222    * <p>
 223    * This method uses the following ordered lookup procedure to determine
 224    * the XMLOutputFactory implementation class to load:
 225    * <p>
 226    * <ul>
 227    * <li>
 228    *   Use the value of the system property identified by {@code factoryId}.
 229    * </li>
 230    * <li>
 231    *   <p>
 232    *   Use the configuration file "stax.properties". The file is in standard
 233    *   {@link java.util.Properties} format and typically located in the
 234    *   {@code conf} directory of the Java installation. It contains the fully qualified
 235    *   name of the implementation class with the key being the system property
 236    *   defined above.
 237    *
 238    *   <p>
 239    *   The stax.properties file is read only once by the implementation
 240    *   and its values are then cached for future use.  If the file does not exist
 241    *   when the first attempt is made to read from it, no further attempts are
 242    *   made to check for its existence.  It is not possible to change the value
 243    *   of any property in stax.properties after it has been read for the first time.
 244    *
 245    *   <p>




  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="2">
  45  *          Configuration parameters
  46  *        </th>
  47  *      </tr>
  48  *    </thead>
  49  *    <tbody>
  50  *      <tr>
  51  *        <th>Property Name</th>
  52  *        <th>Behavior</th>
  53  *        <th>Return type</th>
  54  *        <th>Default Value</th>
  55  *        <th>Required</th>
  56  *              </tr>
  57  *         <tr><td>javax.xml.stream.isRepairingNamespaces</td><td>defaults prefixes
  58  *                 on the output side</td><td>Boolean</td><td>False</td><td>Yes</td></tr>
  59  *      </tbody>
  60  *   </table>
  61  *
  62  * <p>The following paragraphs describe the namespace and prefix repair algorithm:
  63  *
  64  * <p>The property can be set with the following code line:
  65  * {@code setProperty("javax.xml.stream.isRepairingNamespaces", new Boolean(true|false));}
  66  *
  67  * <p>This property specifies that the writer default namespace prefix declarations.
  68  * The default value is false. 
  69  *
  70  * <p>If a writer isRepairingNamespaces it will create a namespace declaration
  71  * on the current StartElement for
  72  * any attribute that does not
  73  * currently have a namespace declaration in scope.  If the StartElement
  74  * has a uri but no prefix specified a prefix will be assigned, if the prefix
  75  * has not been declared in a parent of the current StartElement it will be declared
  76  * on the current StartElement.  If the defaultNamespace is bound and in scope
  77  * and the default namespace matches the URI of the attribute or StartElement
  78  * QName no prefix will be assigned.
  79  *
  80  * <p>If an element or attribute name has a prefix, but is not
  81  * bound to any namespace URI, then the prefix will be removed
  82  * during serialization.
  83  *
  84  * <p>If element and/or attribute names in the same start or
  85  * empty-element tag are bound to different namespace URIs and
  86  * are using the same prefix then the element or the first
  87  * occurring attribute retains the original prefix and the
  88  * following attributes have their prefixes replaced with a
  89  * new prefix that is bound to the namespace URIs of those
  90  * attributes. 
  91  *
  92  * <p>If an element or attribute name uses a prefix that is
  93  * bound to a different URI than that inherited from the
  94  * namespace context of the parent of that element and there
  95  * is no namespace declaration in the context of the current
  96  * element then such a namespace declaration is added. 
  97  *
  98  * <p>If an element or attribute name is bound to a prefix and
  99  * there is a namespace declaration that binds that prefix
 100  * to a different URI then that namespace declaration is
 101  * either removed if the correct mapping is inherited from
 102  * the parent context of that element, or changed to the
 103  * namespace URI of the element or attribute using that prefix.
 104  *
 105  * @version 1.2
 106  * @author Copyright (c) 2009, 2015 by Oracle Corporation. All Rights Reserved.
 107  * @see XMLInputFactory
 108  * @see XMLEventWriter
 109  * @see XMLStreamWriter
 110  * @since 1.6
 111  */
 112 public abstract class XMLOutputFactory {
 113   /**
 114    * Property used to set prefix defaulting on the output side
 115    */
 116   public static final String IS_REPAIRING_NAMESPACES=
 117     "javax.xml.stream.isRepairingNamespaces";
 118 
 119   static final String DEFAULIMPL = "com.sun.xml.internal.stream.XMLOutputFactoryImpl";
 120 
 121   protected XMLOutputFactory(){}
 122 
 123   /**
 124    * Creates a new instance of the factory in exactly the same manner as the
 125    * {@link #newFactory()} method.
 126    * @throws FactoryConfigurationError if an instance of this factory cannot be loaded
 127    */
 128   public static XMLOutputFactory newInstance()
 129     throws FactoryConfigurationError
 130   {
 131     return FactoryFinder.find(XMLOutputFactory.class, DEFAULIMPL);
 132   }
 133 
 134   /**
 135    * Create a new instance of the factory.
 136    * <p>
 137    * This static method creates a new factory instance. This method uses the
 138    * following ordered lookup procedure to determine the XMLOutputFactory
 139    * implementation class to load:

 140    * <ul>
 141    * <li>
 142    *   Use the javax.xml.stream.XMLOutputFactory system property.
 143    * </li>
 144    * <li>
 145    *   <p>
 146    *   Use the configuration file "stax.properties". The file is in standard
 147    *   {@link java.util.Properties} format and typically located in the
 148    *   {@code conf} directory of the Java installation. It contains the fully qualified
 149    *   name of the implementation class with the key being the system property
 150    *   defined above.
 151    *
 152    *   <p>
 153    *   The stax.properties file is read only once by the implementation
 154    *   and its values are then cached for future use.  If the file does not exist
 155    *   when the first attempt is made to read from it, no further attempts are
 156    *   made to check for its existence.  It is not possible to change the value
 157    *   of any property in stax.properties after it has been read for the first time.
 158    *
 159    *   <p>
 160    *   Use the jaxp configuration file "jaxp.properties". The file is in the same
 161    *   format as stax.properties and will only be read if stax.properties does
 162    *   not exist.
 163    * </li>
 164    * <li>
 165    *   <p>
 166    *   Use the service-provider loading facility, defined by the
 167    *   {@link java.util.ServiceLoader} class, to attempt to locate and load an
 168    *   implementation of the service using the {@linkplain
 169    *   java.util.ServiceLoader#load(java.lang.Class) default loading mechanism}:
 170    *   the service-provider loading facility will use the {@linkplain
 171    *   java.lang.Thread#getContextClassLoader() current thread's context class loader}
 172    *   to attempt to load the service. If the context class
 173    *   loader is null, the {@linkplain
 174    *   ClassLoader#getSystemClassLoader() system class loader} will be used.
 175    * </li>
 176    * <li>
 177    *   <p>
 178    *   Otherwise, the system-default implementation is returned.
 179    * </li>
 180    * </ul>
 181    * <p>
 182    * Once an application has obtained a reference to a XMLOutputFactory it
 183    * can use the factory to configure and obtain stream instances.
 184    * <p>
 185    * Note that this is a new method that replaces the deprecated newInstance() method.
 186    *   No changes in behavior are defined by this replacement method relative to the
 187    *   deprecated method.
 188    *
 189    * @throws FactoryConfigurationError in case of {@linkplain
 190    *   java.util.ServiceConfigurationError service configuration error} or if
 191    *   the implementation is not available or cannot be instantiated.
 192    */
 193   public static XMLOutputFactory newFactory()
 194     throws FactoryConfigurationError
 195   {
 196     return FactoryFinder.find(XMLOutputFactory.class, DEFAULIMPL);
 197   }
 198 
 199   /**
 200    * Create a new instance of the factory.


 206    * @throws FactoryConfigurationError if an instance of this factory cannot be loaded
 207    *
 208    * @deprecated  This method has been deprecated because it returns an
 209    *              instance of XMLInputFactory, which is of the wrong class.
 210    *              Use the new method {@link #newFactory(java.lang.String,
 211    *              java.lang.ClassLoader)} instead.
 212    */
 213   public static XMLInputFactory newInstance(String factoryId,
 214           ClassLoader classLoader)
 215           throws FactoryConfigurationError {
 216       //do not fallback if given classloader can't find the class, throw exception
 217       return FactoryFinder.find(XMLInputFactory.class, factoryId, classLoader, null);
 218   }
 219 
 220   /**
 221    * Create a new instance of the factory.
 222    * If the classLoader argument is null, then the ContextClassLoader is used.
 223    * <p>
 224    * This method uses the following ordered lookup procedure to determine
 225    * the XMLOutputFactory implementation class to load:

 226    * <ul>
 227    * <li>
 228    *   Use the value of the system property identified by {@code factoryId}.
 229    * </li>
 230    * <li>
 231    *   <p>
 232    *   Use the configuration file "stax.properties". The file is in standard
 233    *   {@link java.util.Properties} format and typically located in the
 234    *   {@code conf} directory of the Java installation. It contains the fully qualified
 235    *   name of the implementation class with the key being the system property
 236    *   defined above.
 237    *
 238    *   <p>
 239    *   The stax.properties file is read only once by the implementation
 240    *   and its values are then cached for future use.  If the file does not exist
 241    *   when the first attempt is made to read from it, no further attempts are
 242    *   made to check for its existence.  It is not possible to change the value
 243    *   of any property in stax.properties after it has been read for the first time.
 244    *
 245    *   <p>


< prev index next >