Java > Open Source Codes > javax > xml > stream > XMLStreamWriter


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

A to Z: JavaDoc & Examples

---

Daily Java News & Articles

---

Open Source Projects

---

Open Source Codes

---

Free Computer Books

---

Remove Frame

---

Popular Tags