XMLOutputFactory


1   package javax.xml.stream;
2   
3   import javax.xml.transform.Result  ;
4   
5   /**
6    * Defines an abstract implementation of a factory for 
7    * getting XMLEventWriters and XMLStreamWriters.
8    *
9    * The following table defines the standard properties of this specification.  
10   * Each property varies in the level of support required by each implementation.
11   * The level of support required is described in the 'Required' column.
12   *
13   *     <table border="2" rules="all" cellpadding="4">
14   *     <thead>
15   *      <tr>
16   *        <th align="center" colspan="2">
17   *          Configuration parameters
18   *        </th>
19   *      </tr>
20   *    </thead>
21   *    <tbody>
22   *      <tr>
23   *        <th>Property Name</th>
24   *        <th>Behavior</th>
25   *        <th>Return type</th>
26   *        <th>Default Value</th>
27   *        <th>Required</th>
28   *              </tr>
29   *         <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>
30   *      </tbody>
31   *   </table>
32   *
33   * <p>The following paragraphs describe the namespace and prefix repair algorithm:</p>
34   *
35   * <p>The property can be set with the following code line:
36   * <code>setProperty("javax.xml.stream.isRepairingNamespaces",new Boolean(true|false));</code></p>
37   * 
38   * <p>This property specifies that the writer default namespace prefix declarations. 
39   * The default value is false. </p>
40   *
41   * <p>If a writer isRepairingNamespaces it will create a namespace declaration
42   * on the current StartElement for
43   * any attribute that does not 
44   * currently have a namespace declaration in scope.  If the StartElement
45   * has a uri but no prefix specified a prefix will be assigned, if the prefix
46   * has not been declared in a parent of the current StartElement it will be declared
47   * on the current StartElement.  If the defaultNamespace is bound and in scope
48   * and the default namespace matches the URI of the attribute or StartElement
49   * QName no prefix will be assigned.</p>
50   *
51   * <p>If an element or attribute name has a prefix, but is not 
52   * bound to any namespace URI, then the prefix will be removed 
53   * during serialization.</p> 
54   *
55   * <p>If element and/or attribute names in the same start or 
56   * empty-element tag are bound to different namespace URIs and 
57   * are using the same prefix then the element or the first 
58   * occurring attribute retains the original prefix and the 
59   * following attributes have their prefixes replaced with a 
60   * new prefix that is bound to the namespace URIs of those 
61   * attributes. </p>
62   *
63   * <p>If an element or attribute name uses a prefix that is 
64   * bound to a different URI than that inherited from the 
65   * namespace context of the parent of that element and there 
66   * is no namespace declaration in the context of the current 
67   * element then such a namespace declaration is added. </p>
68   *
69   * <p>If an element or attribute name is bound to a prefix and 
70   * there is a namespace declaration that binds that prefix 
71   * to a different URI then that namespace declaration is 
72   * either removed if the correct mapping is inherited from 
73   * the parent context of that element, or changed to the 
74   * namespace URI of the element or attribute using that prefix.</p> 
75   *
76   * @version 1.0 
77   * @author Copyright (c) 2003 by BEA Systems. All Rights Reserved.
78   * @see XMLInputFactory
79   * @see XMLEventWriter
80   * @see XMLStreamWriter
81   * @since 1.6
82   */
83  public abstract class XMLOutputFactory {
84    /** 
85     * Property used to set prefix defaulting on the output side 
86     */
87    public static final String   IS_REPAIRING_NAMESPACES=
88      "javax.xml.stream.isRepairingNamespaces";
89  
90    protected XMLOutputFactory(){}
91  
92    /**
93     * Create a new instance of the factory.
94     * @throws FactoryConfigurationError if an instance of this factory cannot be loaded
95     */
96    public static XMLOutputFactory newInstance() 
97      throws FactoryConfigurationError
98    {
99      return (XMLOutputFactory) FactoryFinder.find("javax.xml.stream.XMLOutputFactory",
100                                                  "com.sun.xml.internal.stream.XMLOutputFactoryImpl");
101   }
102 
103   /**
104    * Create a new instance of the factory. 
105    *
106    * @param factoryId             Name of the factory to find, same as
107    *                              a property name
108    * @param classLoader           classLoader to use
109    * @return the factory implementation
110    * @throws FactoryConfigurationError if an instance of this factory cannot be loaded
111    */
112   public static XMLInputFactory newInstance(String   factoryId,
113           ClassLoader   classLoader)
114           throws FactoryConfigurationError {
115       try {
116           //do not fallback if given classloader can't find the class, throw exception
117           return (XMLInputFactory) FactoryFinder.newInstance(factoryId, classLoader, false);
118       } catch (FactoryFinder.ConfigurationError e) {
119           throw new FactoryConfigurationError(e.getException(),
120                   e.getMessage());
121       }
122   }
123 
124   /**
125    * Create a new XMLStreamWriter that writes to a writer
126    * @param stream the writer to write to
127    * @throws XMLStreamException
128    */
129   public abstract XMLStreamWriter createXMLStreamWriter(java.io.Writer   stream) throws XMLStreamException;
130 
131   /**
132    * Create a new XMLStreamWriter that writes to a stream
133    * @param stream the stream to write to
134    * @throws XMLStreamException
135    */
136   public abstract XMLStreamWriter createXMLStreamWriter(java.io.OutputStream   stream) throws XMLStreamException;
137 
138   /**
139    * Create a new XMLStreamWriter that writes to a stream
140    * @param stream the stream to write to
141    * @param encoding the encoding to use
142    * @throws XMLStreamException
143    */
144   public abstract XMLStreamWriter createXMLStreamWriter(java.io.OutputStream   stream,
145                                          String   encoding) throws XMLStreamException;
146 
147   /**
148    * Create a new XMLStreamWriter that writes to a JAXP result.  This method is optional.
149    * @param result the result to write to
150    * @throws UnsupportedOperationException if this method is not 
151    * supported by this XMLOutputFactory
152    * @throws XMLStreamException 
153    */
154   public abstract XMLStreamWriter createXMLStreamWriter(Result   result) throws XMLStreamException;
155 
156 
157   /**
158    * Create a new XMLEventWriter that writes to a JAXP result.  This method is optional.
159    * @param result the result to write to
160    * @throws UnsupportedOperationException if this method is not 
161    * supported by this XMLOutputFactory
162    * @throws XMLStreamException 
163    */
164   public abstract XMLEventWriter createXMLEventWriter(Result   result) throws XMLStreamException;
165 
166   /**
167    * Create a new XMLEventWriter that writes to a stream
168    * @param stream the stream to write to
169    * @throws XMLStreamException
170    */
171   public abstract XMLEventWriter createXMLEventWriter(java.io.OutputStream   stream) throws XMLStreamException;
172 
173 
174 
175   /**
176    * Create a new XMLEventWriter that writes to a stream
177    * @param stream the stream to write to
178    * @param encoding the encoding to use
179    * @throws XMLStreamException
180    */
181   public abstract XMLEventWriter createXMLEventWriter(java.io.OutputStream   stream,
182                                                      String   encoding) throws XMLStreamException;
183 
184   /**
185    * Create a new XMLEventWriter that writes to a writer
186    * @param stream the stream to write to
187    * @throws XMLStreamException
188    */
189   public abstract XMLEventWriter createXMLEventWriter(java.io.Writer   stream) throws XMLStreamException;
190 
191   /**
192    * Allows the user to set specific features/properties on the underlying implementation. 
193    * @param name The name of the property
194    * @param value The value of the property
195    * @throws java.lang.IllegalArgumentException if the property is not supported
196    */
197   public abstract void setProperty(java.lang.String   name, 
198                                     Object   value) 
199     throws IllegalArgumentException  ;
200 
201   /**
202    * Get a feature/property on the underlying implementation
203    * @param name The name of the property
204    * @return The value of the property
205    * @throws java.lang.IllegalArgumentException if the property is not supported
206    */
207   public abstract Object   getProperty(java.lang.String   name)
208     throws IllegalArgumentException  ;
209 
210   /**
211    * Query the set of properties that this factory supports.
212    *
213    * @param name The name of the property (may not be null)
214    * @return true if the property is supported and false otherwise
215    */
216   public abstract boolean isPropertySupported(String   name);
217 }
218 
219 
220 
221 
222 
223 
224 
225 
226
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags