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