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