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