View Javadoc
1   /*
2    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
3    *
4    * This code is free software; you can redistribute it and/or modify it
5    * under the terms of the GNU General Public License version 2 only, as
6    * published by the Free Software Foundation.  Oracle designates this
7    * particular file as subject to the "Classpath" exception as provided
8    * by Oracle in the LICENSE file that accompanied this code.
9    *
10   * This code is distributed in the hope that it will be useful, but WITHOUT
11   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12   * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
13   * version 2 for more details (a copy is included in the LICENSE file that
14   * accompanied this code).
15   *
16   * You should have received a copy of the GNU General Public License version
17   * 2 along with this work; if not, write to the Free Software Foundation,
18   * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
19   *
20   * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
21   * or visit www.oracle.com if you need additional information or have any
22   * questions.
23   */
24  
25  /*
26   * Copyright (c) 2009 by Oracle Corporation. All Rights Reserved.
27   */
28  
29  package javax.xml.stream;
30  
31  import javax.xml.namespace.NamespaceContext;
32  
33  /**
34   * The XMLStreamWriter interface specifies how to write XML.  The XMLStreamWriter  does
35   * not perform well formedness checking on its input.  However
36   * the writeCharacters method is required to escape & , < and >
37   * For attribute values the writeAttribute method will escape the
38   * above characters plus " to ensure that all character content
39   * and attribute values are well formed.
40   *
41   * Each NAMESPACE
42   * and ATTRIBUTE must be individually written.
43   *
44   * <table border="1" cellpadding="2" cellspacing="0">
45   *     <thead>
46   *         <tr>
47   *             <th colspan="5">XML Namespaces, <code>javax.xml.stream.isRepairingNamespaces</code> and write method behaviour</th>
48   *         </tr>
49   *         <tr>
50   *             <th>Method</th> <!-- method -->
51   *             <th colspan="2"><code>isRepairingNamespaces</code> == true</th>
52   *             <th colspan="2"><code>isRepairingNamespaces</code> == false</th>
53   *         </tr>
54   *         <tr>
55   *             <th></th> <!-- method -->
56   *             <th>namespaceURI bound</th>
57   *             <th>namespaceURI unbound</th>
58   *             <th>namespaceURI bound</th>
59   *             <th>namespaceURI unbound</th>
60   *         </tr>
61   *     </thead>
62   *
63   *     <tbody>
64   *         <tr>
65   *             <th><code>writeAttribute(namespaceURI, localName, value)</code></th>
66   *             <!-- isRepairingNamespaces == true -->
67   *             <td>
68   *                 <!-- namespaceURI bound -->
69   *                 prefix:localName="value"&nbsp;<sup>[1]</sup>
70   *             </td>
71   *             <td>
72   *                 <!-- namespaceURI unbound -->
73   *                 xmlns:{generated}="namespaceURI" {generated}:localName="value"
74   *             </td>
75   *             <!-- isRepairingNamespaces == false -->
76   *             <td>
77   *                 <!-- namespaceURI bound -->
78   *                 prefix:localName="value"&nbsp;<sup>[1]</sup>
79   *             </td>
80   *             <td>
81   *                 <!-- namespaceURI unbound -->
82   *                 <code>XMLStreamException</code>
83   *             </td>
84   *         </tr>
85   *
86   *         <tr>
87   *             <th><code>writeAttribute(prefix, namespaceURI, localName, value)</code></th>
88   *             <!-- isRepairingNamespaces == true -->
89   *             <td>
90   *                 <!-- namespaceURI bound -->
91   *                 bound to same prefix:<br />
92   *                 prefix:localName="value"&nbsp;<sup>[1]</sup><br />
93   *                 <br />
94   *                 bound to different prefix:<br />
95   *                 xmlns:{generated}="namespaceURI" {generated}:localName="value"
96   *             </td>
97   *             <td>
98   *                 <!-- namespaceURI unbound -->
99   *                 xmlns:prefix="namespaceURI" prefix:localName="value"&nbsp;<sup>[3]</sup>
100  *             </td>
101  *             <!-- isRepairingNamespaces == false -->
102  *             <td>
103  *                 <!-- namespaceURI bound -->
104  *                 bound to same prefix:<br />
105  *                 prefix:localName="value"&nbsp;<sup>[1][2]</sup><br />
106  *                 <br />
107  *                 bound to different prefix:<br />
108  *                 <code>XMLStreamException</code><sup>[2]</sup>
109  *             </td>
110  *             <td>
111  *                 <!-- namespaceURI unbound -->
112  *                 xmlns:prefix="namespaceURI" prefix:localName="value"&nbsp;<sup>[2][5]</sup>
113  *             </td>
114  *         </tr>
115  *
116  *         <tr>
117  *             <th><code>writeStartElement(namespaceURI, localName)</code><br />
118  *                 <br />
119  *                 <code>writeEmptyElement(namespaceURI, localName)</code></th>
120  *             <!-- isRepairingNamespaces == true -->
121  *             <td >
122  *                 <!-- namespaceURI bound -->
123  *                 &lt;prefix:localName&gt;&nbsp;<sup>[1]</sup>
124  *             </td>
125  *             <td>
126  *                 <!-- namespaceURI unbound -->
127  *                 &lt;{generated}:localName xmlns:{generated}="namespaceURI"&gt;
128  *             </td>
129  *             <!-- isRepairingNamespaces == false -->
130  *             <td>
131  *                 <!-- namespaceURI bound -->
132  *                 &lt;prefix:localName&gt;&nbsp;<sup>[1]</sup>
133  *             </td>
134  *             <td>
135  *                 <!-- namespaceURI unbound -->
136  *                 <code>XMLStreamException</code>
137  *             </td>
138  *         </tr>
139  *
140  *         <tr>
141  *             <th><code>writeStartElement(prefix, localName, namespaceURI)</code><br />
142  *                 <br />
143  *                 <code>writeEmptyElement(prefix, localName, namespaceURI)</code></th>
144  *             <!-- isRepairingNamespaces == true -->
145  *             <td>
146  *                 <!-- namespaceURI bound -->
147  *                 bound to same prefix:<br />
148  *                 &lt;prefix:localName&gt;&nbsp;<sup>[1]</sup><br />
149  *                 <br />
150  *                 bound to different prefix:<br />
151  *                 &lt;{generated}:localName xmlns:{generated}="namespaceURI"&gt;
152  *             </td>
153  *             <td>
154  *                 <!-- namespaceURI unbound -->
155  *                 &lt;prefix:localName xmlns:prefix="namespaceURI"&gt;&nbsp;<sup>[4]</sup>
156  *             </td>
157  *             <!-- isRepairingNamespaces == false -->
158  *             <td>
159  *                 <!-- namespaceURI bound -->
160  *                 bound to same prefix:<br />
161  *                 &lt;prefix:localName&gt;&nbsp;<sup>[1]</sup><br />
162  *                 <br />
163  *                 bound to different prefix:<br />
164  *                 <code>XMLStreamException</code>
165  *             </td>
166  *             <td>
167  *                 <!-- namespaceURI unbound -->
168  *                 &lt;prefix:localName&gt;&nbsp;
169  *             </td>
170  *         </tr>
171  *     </tbody>
172  *     <tfoot>
173  *         <tr>
174  *             <td colspan="5">
175  *                 Notes:
176  *                 <ul>
177  *                     <li>[1] if namespaceURI == default Namespace URI, then no prefix is written</li>
178  *                     <li>[2] if prefix == "" || null && namespaceURI == "", then no prefix or Namespace declaration is generated or written</li>
179  *                     <li>[3] if prefix == "" || null, then a prefix is randomly generated</li>
180  *                     <li>[4] if prefix == "" || null, then it is treated as the default Namespace and no prefix is generated or written, an xmlns declaration is generated and written if the namespaceURI is unbound</li>
181  *                     <li>[5] if prefix == "" || null, then it is treated as an invalid attempt to define the default Namespace and an XMLStreamException is thrown</li>
182  *                 </ul>
183  *             </td>
184  *         </tr>
185  *     </tfoot>
186  * </table>
187  *
188  * @version 1.0
189  * @author Copyright (c) 2009 by Oracle Corporation. All Rights Reserved.
190  * @see XMLOutputFactory
191  * @see XMLStreamReader
192  * @since 1.6
193  */
194 public interface XMLStreamWriter {
195 
196   /**
197    * Writes a start tag to the output.  All writeStartElement methods
198    * open a new scope in the internal namespace context.  Writing the
199    * corresponding EndElement causes the scope to be closed.
200    * @param localName local name of the tag, may not be null
201    * @throws XMLStreamException
202    */
203   public void writeStartElement(String localName)
204     throws XMLStreamException;
205 
206   /**
207    * Writes a start tag to the output
208    * @param namespaceURI the namespaceURI of the prefix to use, may not be null
209    * @param localName local name of the tag, may not be null
210    * @throws XMLStreamException if the namespace URI has not been bound to a prefix and
211    * javax.xml.stream.isRepairingNamespaces has not been set to true
212    */
213   public void writeStartElement(String namespaceURI, String localName)
214     throws XMLStreamException;
215 
216   /**
217    * Writes a start tag to the output
218    * @param localName local name of the tag, may not be null
219    * @param prefix the prefix of the tag, may not be null
220    * @param namespaceURI the uri to bind the prefix to, may not be null
221    * @throws XMLStreamException
222    */
223   public void writeStartElement(String prefix,
224                                 String localName,
225                                 String namespaceURI)
226     throws XMLStreamException;
227 
228   /**
229    * Writes an empty element tag to the output
230    * @param namespaceURI the uri to bind the tag to, may not be null
231    * @param localName local name of the tag, may not be null
232    * @throws XMLStreamException if the namespace URI has not been bound to a prefix and
233    * javax.xml.stream.isRepairingNamespaces has not been set to true
234    */
235   public void writeEmptyElement(String namespaceURI, String localName)
236     throws XMLStreamException;
237 
238   /**
239    * Writes an empty element tag to the output
240    * @param prefix the prefix of the tag, may not be null
241    * @param localName local name of the tag, may not be null
242    * @param namespaceURI the uri to bind the tag to, may not be null
243    * @throws XMLStreamException
244    */
245   public void writeEmptyElement(String prefix, String localName, String namespaceURI)
246     throws XMLStreamException;
247 
248   /**
249    * Writes an empty element tag to the output
250    * @param localName local name of the tag, may not be null
251    * @throws XMLStreamException
252    */
253   public void writeEmptyElement(String localName)
254     throws XMLStreamException;
255 
256   /**
257    * Writes string data to the output without checking for well formedness.
258    * The data is opaque to the XMLStreamWriter, i.e. the characters are written
259    * blindly to the underlying output.  If the method cannot be supported
260    * in the currrent writing context the implementation may throw a
261    * UnsupportedOperationException.  For example note that any
262    * namespace declarations, end tags, etc. will be ignored and could
263    * interfere with proper maintanence of the writers internal state.
264    *
265    * @param data the data to write
266    */
267   //  public void writeRaw(String data) throws XMLStreamException;
268 
269   /**
270    * Writes an end tag to the output relying on the internal
271    * state of the writer to determine the prefix and local name
272    * of the event.
273    * @throws XMLStreamException
274    */
275   public void writeEndElement()
276     throws XMLStreamException;
277 
278   /**
279    * Closes any start tags and writes corresponding end tags.
280    * @throws XMLStreamException
281    */
282   public void writeEndDocument()
283     throws XMLStreamException;
284 
285   /**
286    * Close this writer and free any resources associated with the
287    * writer.  This must not close the underlying output stream.
288    * @throws XMLStreamException
289    */
290   public void close()
291     throws XMLStreamException;
292 
293   /**
294    * Write any cached data to the underlying output mechanism.
295    * @throws XMLStreamException
296    */
297   public void flush()
298     throws XMLStreamException;
299 
300   /**
301    * Writes an attribute to the output stream without
302    * a prefix.
303    * @param localName the local name of the attribute
304    * @param value the value of the attribute
305    * @throws IllegalStateException if the current state does not allow Attribute writing
306    * @throws XMLStreamException
307    */
308   public void writeAttribute(String localName, String value)
309     throws XMLStreamException;
310 
311   /**
312    * Writes an attribute to the output stream
313    * @param prefix the prefix for this attribute
314    * @param namespaceURI the uri of the prefix for this attribute
315    * @param localName the local name of the attribute
316    * @param value the value of the attribute
317    * @throws IllegalStateException if the current state does not allow Attribute writing
318    * @throws XMLStreamException if the namespace URI has not been bound to a prefix and
319    * javax.xml.stream.isRepairingNamespaces has not been set to true
320    */
321 
322   public void writeAttribute(String prefix,
323                              String namespaceURI,
324                              String localName,
325                              String value)
326     throws XMLStreamException;
327 
328   /**
329    * Writes an attribute to the output stream
330    * @param namespaceURI the uri of the prefix for this attribute
331    * @param localName the local name of the attribute
332    * @param value the value of the attribute
333    * @throws IllegalStateException if the current state does not allow Attribute writing
334    * @throws XMLStreamException if the namespace URI has not been bound to a prefix and
335    * javax.xml.stream.isRepairingNamespaces has not been set to true
336    */
337   public void writeAttribute(String namespaceURI,
338                              String localName,
339                              String value)
340     throws XMLStreamException;
341 
342   /**
343    * Writes a namespace to the output stream
344    * If the prefix argument to this method is the empty string,
345    * "xmlns", or null this method will delegate to writeDefaultNamespace
346    *
347    * @param prefix the prefix to bind this namespace to
348    * @param namespaceURI the uri to bind the prefix to
349    * @throws IllegalStateException if the current state does not allow Namespace writing
350    * @throws XMLStreamException
351    */
352   public void writeNamespace(String prefix, String namespaceURI)
353     throws XMLStreamException;
354 
355   /**
356    * Writes the default namespace to the stream
357    * @param namespaceURI the uri to bind the default namespace to
358    * @throws IllegalStateException if the current state does not allow Namespace writing
359    * @throws XMLStreamException
360    */
361   public void writeDefaultNamespace(String namespaceURI)
362     throws XMLStreamException;
363 
364   /**
365    * Writes an xml comment with the data enclosed
366    * @param data the data contained in the comment, may be null
367    * @throws XMLStreamException
368    */
369   public void writeComment(String data)
370     throws XMLStreamException;
371 
372   /**
373    * Writes a processing instruction
374    * @param target the target of the processing instruction, may not be null
375    * @throws XMLStreamException
376    */
377   public void writeProcessingInstruction(String target)
378     throws XMLStreamException;
379 
380   /**
381    * Writes a processing instruction
382    * @param target the target of the processing instruction, may not be null
383    * @param data the data contained in the processing instruction, may not be null
384    * @throws XMLStreamException
385    */
386   public void writeProcessingInstruction(String target,
387                                          String data)
388     throws XMLStreamException;
389 
390   /**
391    * Writes a CData section
392    * @param data the data contained in the CData Section, may not be null
393    * @throws XMLStreamException
394    */
395   public void writeCData(String data)
396     throws XMLStreamException;
397 
398   /**
399    * Write a DTD section.  This string represents the entire doctypedecl production
400    * from the XML 1.0 specification.
401    *
402    * @param dtd the DTD to be written
403    * @throws XMLStreamException
404    */
405   public void writeDTD(String dtd)
406     throws XMLStreamException;
407 
408   /**
409    * Writes an entity reference
410    * @param name the name of the entity
411    * @throws XMLStreamException
412    */
413   public void writeEntityRef(String name)
414     throws XMLStreamException;
415 
416   /**
417    * Write the XML Declaration. Defaults the XML version to 1.0, and the encoding to utf-8
418    * @throws XMLStreamException
419    */
420   public void writeStartDocument()
421     throws XMLStreamException;
422 
423   /**
424    * Write the XML Declaration. Defaults the XML version to 1.0
425    * @param version version of the xml document
426    * @throws XMLStreamException
427    */
428   public void writeStartDocument(String version)
429     throws XMLStreamException;
430 
431   /**
432    * Write the XML Declaration.  Note that the encoding parameter does
433    * not set the actual encoding of the underlying output.  That must
434    * be set when the instance of the XMLStreamWriter is created using the
435    * XMLOutputFactory
436    * @param encoding encoding of the xml declaration
437    * @param version version of the xml document
438    * @throws XMLStreamException If given encoding does not match encoding
439    * of the underlying stream
440    */
441   public void writeStartDocument(String encoding,
442                                  String version)
443     throws XMLStreamException;
444 
445   /**
446    * Write text to the output
447    * @param text the value to write
448    * @throws XMLStreamException
449    */
450   public void writeCharacters(String text)
451     throws XMLStreamException;
452 
453   /**
454    * Write text to the output
455    * @param text the value to write
456    * @param start the starting position in the array
457    * @param len the number of characters to write
458    * @throws XMLStreamException
459    */
460   public void writeCharacters(char[] text, int start, int len)
461     throws XMLStreamException;
462 
463   /**
464    * Gets the prefix the uri is bound to
465    * @return the prefix or null
466    * @throws XMLStreamException
467    */
468   public String getPrefix(String uri)
469     throws XMLStreamException;
470 
471   /**
472    * Sets the prefix the uri is bound to.  This prefix is bound
473    * in the scope of the current START_ELEMENT / END_ELEMENT pair.
474    * If this method is called before a START_ELEMENT has been written
475    * the prefix is bound in the root scope.
476    * @param prefix the prefix to bind to the uri, may not be null
477    * @param uri the uri to bind to the prefix, may be null
478    * @throws XMLStreamException
479    */
480   public void setPrefix(String prefix, String uri)
481     throws XMLStreamException;
482 
483 
484   /**
485    * Binds a URI to the default namespace
486    * This URI is bound
487    * in the scope of the current START_ELEMENT / END_ELEMENT pair.
488    * If this method is called before a START_ELEMENT has been written
489    * the uri is bound in the root scope.
490    * @param uri the uri to bind to the default namespace, may be null
491    * @throws XMLStreamException
492    */
493   public void setDefaultNamespace(String uri)
494     throws XMLStreamException;
495 
496   /**
497    * Sets the current namespace context for prefix and uri bindings.
498    * This context becomes the root namespace context for writing and
499    * will replace the current root namespace context.  Subsequent calls
500    * to setPrefix and setDefaultNamespace will bind namespaces using
501    * the context passed to the method as the root context for resolving
502    * namespaces.  This method may only be called once at the start of
503    * the document.  It does not cause the namespaces to be declared.
504    * If a namespace URI to prefix mapping is found in the namespace
505    * context it is treated as declared and the prefix may be used
506    * by the StreamWriter.
507    * @param context the namespace context to use for this writer, may not be null
508    * @throws XMLStreamException
509    */
510   public void setNamespaceContext(NamespaceContext context)
511     throws XMLStreamException;
512 
513   /**
514    * Returns the current namespace context.
515    * @return the current NamespaceContext
516    */
517   public NamespaceContext getNamespaceContext();
518 
519   /**
520    * Get the value of a feature/property from the underlying implementation
521    * @param name The name of the property, may not be null
522    * @return The value of the property
523    * @throws IllegalArgumentException if the property is not supported
524    * @throws NullPointerException if the name is null
525    */
526   public Object getProperty(java.lang.String name) throws IllegalArgumentException;
527 
528 }