001 package javax.xml.stream;
002
003 import javax.xml.namespace.NamespaceContext;
004
005 /**
006 * The XMLStreamWriter interface specifies how to write XML. The XMLStreamWriter does
007 * not perform well formedness checking on its input. However
008 * the writeCharacters method is required to escape & , < and >
009 * For attribute values the writeAttribute method will escape the
010 * above characters plus " to ensure that all character content
011 * and attribute values are well formed.
012 *
013 * Each NAMESPACE
014 * and ATTRIBUTE must be individually written.
015 *
016 * <table border="1" cellpadding="2" cellspacing="0">
017 * <thead>
018 * <tr>
019 * <th colspan="5">XML Namespaces, <code>javax.xml.stream.isRepairingNamespaces</code> and write method behaviour</th>
020 * </tr>
021 * <tr>
022 * <th>Method</th> <!-- method -->
023 * <th colspan="2"><code>isRepairingNamespaces</code> == true</th>
024 * <th colspan="2"><code>isRepairingNamespaces</code> == false</th>
025 * </tr>
026 * <tr>
027 * <th></th> <!-- method -->
028 * <th>namespaceURI bound</th>
029 * <th>namespaceURI unbound</th>
030 * <th>namespaceURI bound</th>
031 * <th>namespaceURI unbound</th>
032 * </tr>
033 * </thead>
034 *
035 * <tbody>
036 * <tr>
037 * <th><code>writeAttribute(namespaceURI, localName, value)</code></th>
038 * <!-- isRepairingNamespaces == true -->
039 * <td>
040 * <!-- namespaceURI bound -->
041 * prefix:localName="value" <sup>[1]</sup>
042 * </td>
043 * <td>
044 * <!-- namespaceURI unbound -->
045 * xmlns:{generated}="namespaceURI" {generated}:localName="value"
046 * </td>
047 * <!-- isRepairingNamespaces == false -->
048 * <td>
049 * <!-- namespaceURI bound -->
050 * prefix:localName="value" <sup>[1]</sup>
051 * </td>
052 * <td>
053 * <!-- namespaceURI unbound -->
054 * <code>XMLStreamException</code>
055 * </td>
056 * </tr>
057 *
058 * <tr>
059 * <th><code>writeAttribute(prefix, namespaceURI, localName, value)</code></th>
060 * <!-- isRepairingNamespaces == true -->
061 * <td>
062 * <!-- namespaceURI bound -->
063 * bound to same prefix:<br />
064 * prefix:localName="value" <sup>[1]</sup><br />
065 * <br />
066 * bound to different prefix:<br />
067 * xmlns:{generated}="namespaceURI" {generated}:localName="value"
068 * </td>
069 * <td>
070 * <!-- namespaceURI unbound -->
071 * xmlns:prefix="namespaceURI" prefix:localName="value" <sup>[3]</sup>
072 * </td>
073 * <!-- isRepairingNamespaces == false -->
074 * <td>
075 * <!-- namespaceURI bound -->
076 * bound to same prefix:<br />
077 * prefix:localName="value" <sup>[1][2]</sup><br />
078 * <br />
079 * bound to different prefix:<br />
080 * <code>XMLStreamException</code><sup>[2]</sup>
081 * </td>
082 * <td>
083 * <!-- namespaceURI unbound -->
084 * xmlns:prefix="namespaceURI" prefix:localName="value" <sup>[2][5]</sup>
085 * </td>
086 * </tr>
087 *
088 * <tr>
089 * <th><code>writeStartElement(namespaceURI, localName)</code><br />
090 * <br />
091 * <code>writeEmptyElement(namespaceURI, localName)</code></th>
092 * <!-- isRepairingNamespaces == true -->
093 * <td >
094 * <!-- namespaceURI bound -->
095 * <prefix:localName> <sup>[1]</sup>
096 * </td>
097 * <td>
098 * <!-- namespaceURI unbound -->
099 * <{generated}:localName xmlns:{generated}="namespaceURI">
100 * </td>
101 * <!-- isRepairingNamespaces == false -->
102 * <td>
103 * <!-- namespaceURI bound -->
104 * <prefix:localName> <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 * <prefix:localName> <sup>[1]</sup><br />
121 * <br />
122 * bound to different prefix:<br />
123 * <{generated}:localName xmlns:{generated}="namespaceURI">
124 * </td>
125 * <td>
126 * <!-- namespaceURI unbound -->
127 * <prefix:localName xmlns:prefix="namespaceURI"> <sup>[4]</sup>
128 * </td>
129 * <!-- isRepairingNamespaces == false -->
130 * <td>
131 * <!-- namespaceURI bound -->
132 * bound to same prefix:<br />
133 * <prefix:localName> <sup>[1]</sup><br />
134 * <br />
135 * bound to different prefix:<br />
136 * <code>XMLStreamException</code>
137 * </td>
138 * <td>
139 * <!-- namespaceURI unbound -->
140 * <prefix:localName>
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, String localName,
196 String namespaceURI) throws XMLStreamException;
197
198 /**
199 * Writes an empty element tag to the output
200 * @param namespaceURI the uri to bind the tag to, may not be null
201 * @param localName local name of the tag, may not be null
202 * @throws XMLStreamException if the namespace URI has not been bound to a prefix and
203 * javax.xml.stream.isRepairingNamespaces has not been set to true
204 */
205 public void writeEmptyElement(String namespaceURI, String localName)
206 throws XMLStreamException;
207
208 /**
209 * Writes an empty element tag to the output
210 * @param prefix the prefix of the tag, may not be null
211 * @param localName local name of the tag, may not be null
212 * @param namespaceURI the uri to bind the tag to, may not be null
213 * @throws XMLStreamException
214 */
215 public void writeEmptyElement(String prefix, String localName,
216 String namespaceURI) throws XMLStreamException;
217
218 /**
219 * Writes an empty element tag to the output
220 * @param localName local name of the tag, may not be null
221 * @throws XMLStreamException
222 */
223 public void writeEmptyElement(String localName)
224 throws XMLStreamException;
225
226 /**
227 * Writes string data to the output without checking for well formedness.
228 * The data is opaque to the XMLStreamWriter, i.e. the characters are written
229 * blindly to the underlying output. If the method cannot be supported
230 * in the currrent writing context the implementation may throw a
231 * UnsupportedOperationException. For example note that any
232 * namespace declarations, end tags, etc. will be ignored and could
233 * interfere with proper maintanence of the writers internal state.
234 *
235 * @param data the data to write
236 */
237 // public void writeRaw(String data) throws XMLStreamException;
238 /**
239 * Writes an end tag to the output relying on the internal
240 * state of the writer to determine the prefix and local name
241 * of the event.
242 * @throws XMLStreamException
243 */
244 public void writeEndElement() throws XMLStreamException;
245
246 /**
247 * Closes any start tags and writes corresponding end tags.
248 * @throws XMLStreamException
249 */
250 public void writeEndDocument() throws XMLStreamException;
251
252 /**
253 * Close this writer and free any resources associated with the
254 * writer. This must not close the underlying output stream.
255 * @throws XMLStreamException
256 */
257 public void close() throws XMLStreamException;
258
259 /**
260 * Write any cached data to the underlying output mechanism.
261 * @throws XMLStreamException
262 */
263 public void flush() throws XMLStreamException;
264
265 /**
266 * Writes an attribute to the output stream without
267 * a prefix.
268 * @param localName the local name of the attribute
269 * @param value the value of the attribute
270 * @throws IllegalStateException if the current state does not allow Attribute writing
271 * @throws XMLStreamException
272 */
273 public void writeAttribute(String localName, String value)
274 throws XMLStreamException;
275
276 /**
277 * Writes an attribute to the output stream
278 * @param prefix the prefix for this attribute
279 * @param namespaceURI the uri of the prefix for this attribute
280 * @param localName the local name of the attribute
281 * @param value the value of the attribute
282 * @throws IllegalStateException if the current state does not allow Attribute writing
283 * @throws XMLStreamException if the namespace URI has not been bound to a prefix and
284 * javax.xml.stream.isRepairingNamespaces has not been set to true
285 */
286
287 public void writeAttribute(String prefix, String namespaceURI,
288 String localName, String value) throws XMLStreamException;
289
290 /**
291 * Writes an attribute to the output stream
292 * @param namespaceURI the uri of the prefix for this attribute
293 * @param localName the local name of the attribute
294 * @param value the value of the attribute
295 * @throws IllegalStateException if the current state does not allow Attribute writing
296 * @throws XMLStreamException if the namespace URI has not been bound to a prefix and
297 * javax.xml.stream.isRepairingNamespaces has not been set to true
298 */
299 public void writeAttribute(String namespaceURI, String localName,
300 String value) throws XMLStreamException;
301
302 /**
303 * Writes a namespace to the output stream
304 * If the prefix argument to this method is the empty string,
305 * "xmlns", or null this method will delegate to writeDefaultNamespace
306 *
307 * @param prefix the prefix to bind this namespace to
308 * @param namespaceURI the uri to bind the prefix to
309 * @throws IllegalStateException if the current state does not allow Namespace writing
310 * @throws XMLStreamException
311 */
312 public void writeNamespace(String prefix, String namespaceURI)
313 throws XMLStreamException;
314
315 /**
316 * Writes the default namespace to the stream
317 * @param namespaceURI the uri to bind the default namespace to
318 * @throws IllegalStateException if the current state does not allow Namespace writing
319 * @throws XMLStreamException
320 */
321 public void writeDefaultNamespace(String namespaceURI)
322 throws XMLStreamException;
323
324 /**
325 * Writes an xml comment with the data enclosed
326 * @param data the data contained in the comment, may be null
327 * @throws XMLStreamException
328 */
329 public void writeComment(String data) throws XMLStreamException;
330
331 /**
332 * Writes a processing instruction
333 * @param target the target of the processing instruction, may not be null
334 * @throws XMLStreamException
335 */
336 public void writeProcessingInstruction(String target)
337 throws XMLStreamException;
338
339 /**
340 * Writes a processing instruction
341 * @param target the target of the processing instruction, may not be null
342 * @param data the data contained in the processing instruction, may not be null
343 * @throws XMLStreamException
344 */
345 public void writeProcessingInstruction(String target, String data)
346 throws XMLStreamException;
347
348 /**
349 * Writes a CData section
350 * @param data the data contained in the CData Section, may not be null
351 * @throws XMLStreamException
352 */
353 public void writeCData(String data) throws XMLStreamException;
354
355 /**
356 * Write a DTD section. This string represents the entire doctypedecl production
357 * from the XML 1.0 specification.
358 *
359 * @param dtd the DTD to be written
360 * @throws XMLStreamException
361 */
362 public void writeDTD(String dtd) throws XMLStreamException;
363
364 /**
365 * Writes an entity reference
366 * @param name the name of the entity
367 * @throws XMLStreamException
368 */
369 public void writeEntityRef(String name) throws XMLStreamException;
370
371 /**
372 * Write the XML Declaration. Defaults the XML version to 1.0, and the encoding to utf-8
373 * @throws XMLStreamException
374 */
375 public void writeStartDocument() throws XMLStreamException;
376
377 /**
378 * Write the XML Declaration. Defaults the XML version to 1.0
379 * @param version version of the xml document
380 * @throws XMLStreamException
381 */
382 public void writeStartDocument(String version)
383 throws XMLStreamException;
384
385 /**
386 * Write the XML Declaration. Note that the encoding parameter does
387 * not set the actual encoding of the underlying output. That must
388 * be set when the instance of the XMLStreamWriter is created using the
389 * XMLOutputFactory
390 * @param encoding encoding of the xml declaration
391 * @param version version of the xml document
392 * @throws XMLStreamException If given encoding does not match encoding
393 * of the underlying stream
394 */
395 public void writeStartDocument(String encoding, String version)
396 throws XMLStreamException;
397
398 /**
399 * Write text to the output
400 * @param text the value to write
401 * @throws XMLStreamException
402 */
403 public void writeCharacters(String text) throws XMLStreamException;
404
405 /**
406 * Write text to the output
407 * @param text the value to write
408 * @param start the starting position in the array
409 * @param len the number of characters to write
410 * @throws XMLStreamException
411 */
412 public void writeCharacters(char[] text, int start, int len)
413 throws XMLStreamException;
414
415 /**
416 * Gets the prefix the uri is bound to
417 * @return the prefix or null
418 * @throws XMLStreamException
419 */
420 public String getPrefix(String uri) throws XMLStreamException;
421
422 /**
423 * Sets the prefix the uri is bound to. This prefix is bound
424 * in the scope of the current START_ELEMENT / END_ELEMENT pair.
425 * If this method is called before a START_ELEMENT has been written
426 * the prefix is bound in the root scope.
427 * @param prefix the prefix to bind to the uri, may not be null
428 * @param uri the uri to bind to the prefix, may be null
429 * @throws XMLStreamException
430 */
431 public void setPrefix(String prefix, String uri)
432 throws XMLStreamException;
433
434 /**
435 * Binds a URI to the default namespace
436 * This URI is bound
437 * in the scope of the current START_ELEMENT / END_ELEMENT pair.
438 * If this method is called before a START_ELEMENT has been written
439 * the uri is bound in the root scope.
440 * @param uri the uri to bind to the default namespace, may be null
441 * @throws XMLStreamException
442 */
443 public void setDefaultNamespace(String uri)
444 throws XMLStreamException;
445
446 /**
447 * Sets the current namespace context for prefix and uri bindings.
448 * This context becomes the root namespace context for writing and
449 * will replace the current root namespace context. Subsequent calls
450 * to setPrefix and setDefaultNamespace will bind namespaces using
451 * the context passed to the method as the root context for resolving
452 * namespaces. This method may only be called once at the start of
453 * the document. It does not cause the namespaces to be declared.
454 * If a namespace URI to prefix mapping is found in the namespace
455 * context it is treated as declared and the prefix may be used
456 * by the StreamWriter.
457 * @param context the namespace context to use for this writer, may not be null
458 * @throws XMLStreamException
459 */
460 public void setNamespaceContext(NamespaceContext context)
461 throws XMLStreamException;
462
463 /**
464 * Returns the current namespace context.
465 * @return the current NamespaceContext
466 */
467 public NamespaceContext getNamespaceContext();
468
469 /**
470 * Get the value of a feature/property from the underlying implementation
471 * @param name The name of the property, may not be null
472 * @return The value of the property
473 * @throws IllegalArgumentException if the property is not supported
474 * @throws NullPointerException if the name is null
475 */
476 public Object getProperty(java.lang.String name)
477 throws IllegalArgumentException;
478
479 }
|