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