KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javolution > xml > stream > XMLStreamWriter


1 /*
2  * Javolution - Java(TM) Solution for Real-Time and Embedded Systems
3  * Copyright (C) 2006 - Javolution (http://javolution.org/)
4  * All rights reserved.
5  *
6  * Permission to use, copy, modify, and distribute this software is
7  * freely granted, provided that this notice is preserved.
8  */

9 package javolution.xml.stream;
10
11 import j2me.lang.CharSequence;
12
13 /**
14  * <p> This interface is similar to
15  * <code>javax.xml.stream.XMLStreamWriter</code>; but it does not forces
16  * dynamic allocation when formatting (any {@link CharSequence CharSequence}
17  * can be used instead of {@link String}).</p>
18  *
19  * <p> Except for the speed (faster) and the added flexibility, the
20  * usage/behavior is about the same as its StAX counterpart.</p>
21  *
22  * <p> This writer does not require creating new <code>String</code> objects
23  * during XML formatting. Attributes values can be held by a single/reusable
24  * {@link javolution.text.TextBuilder TextBuilder}
25  * (or <code>StringBuilder</code>)instance to avoid adverse effects
26  * on memory footprint (heap), garbage collection and performance.
27  * For example:[code]
28  *
29  * // Creates a new writer (potentially recycled).
30  * XMLOutputFactory factory = XMLOutputFactory.newInstance();
31  * XMLStreamWriter writer = factory.createXMLStreamWriter(outputStream);
32  *
33  * TextBuilder tmp = new TextBuilder();
34  * writer.writeStartDocument();
35  * ...
36  * writer.writeStartElement("Time");
37  * // Writes primitive types (int) attributes (no memory allocation).
38  * writer.writeAttribute("hour", tmp.clear().append(time.hour);
39  * writer.writeAttribute("minute", tmp.clear().append(time.minute);
40  * writer.writeAttribute("second", tmp.clear().append(time.second);
41  * writer.writeEndElement();
42  * ...
43  *
44  * writer.close(); // Recycles this writer.
45  * outputStream.close(); // Underlying stream has to be closed explicitly.
46  * [/code]</p>
47  *
48  * <p> Note: As always, <code>null</code> parameters are not allowed unless
49  * explicitly authorized.</p>
50  *
51  * @author <a HREF="mailto:jean-marie@dautelle.com">Jean-Marie Dautelle</a>
52  * @version 4.0, June 16, 2006
53  */

54 public interface XMLStreamWriter {
55
56     /**
57      * Writes a start tag to the output. All writeStartElement methods open a
58      * new scope in the internal namespace context. Writing the corresponding
59      * EndElement causes the scope to be closed.
60      *
61      * @param localName local name of the tag.
62      * @throws XMLStreamException
63      */

64     public void writeStartElement(CharSequence JavaDoc localName)
65             throws XMLStreamException;
66
67     /**
68      * Writes a start tag to the output.
69      *
70      * @param namespaceURI the namespaceURI of the prefix to use.
71      * @param localName local name of the tag.
72      * @throws XMLStreamException if the namespace URI has not been bound
73      * to a prefix and this writer does not {@link
74      * XMLOutputFactory#IS_REPAIRING_NAMESPACES repair namespaces}.
75      */

76     public void writeStartElement(CharSequence JavaDoc namespaceURI,
77             CharSequence JavaDoc localName) throws XMLStreamException;
78
79     /**
80      * Writes a start tag to the output.
81      *
82      * @param localName local name of the tag.
83      * @param prefix the prefix of the tag.
84      * @param namespaceURI the uri to bind the prefix to.
85      * @throws XMLStreamException if the namespace URI has not been bound
86      * to a prefix and this writer does not {@link
87      * XMLOutputFactory#IS_REPAIRING_NAMESPACES repair namespaces}.
88      */

89     public void writeStartElement(CharSequence JavaDoc prefix, CharSequence JavaDoc localName,
90             CharSequence JavaDoc namespaceURI) throws XMLStreamException;
91
92     /**
93      * Writes an empty element tag to the output.
94      *
95      * @param namespaceURI the uri to bind the tag to.
96      * @param localName local name of the tag.
97      * @throws XMLStreamException if the namespace URI has not been bound
98      * to a prefix and this writer does not {@link
99      * XMLOutputFactory#IS_REPAIRING_NAMESPACES repair namespaces}.
100      */

101     public void writeEmptyElement(CharSequence JavaDoc namespaceURI,
102             CharSequence JavaDoc localName) throws XMLStreamException;
103
104     /**
105      * Writes an empty element tag to the output.
106      *
107      * @param prefix the prefix of the tag.
108      * @param localName local name of the tag.
109      * @param namespaceURI the uri to bind the tag to.
110      * @throws XMLStreamException if the namespace URI has not been bound
111      * to a prefix and this writer does not {@link
112      * XMLOutputFactory#IS_REPAIRING_NAMESPACES repair namespaces}.
113      */

114     public void writeEmptyElement(CharSequence JavaDoc prefix, CharSequence JavaDoc localName,
115             CharSequence JavaDoc namespaceURI) throws XMLStreamException;
116
117     /**
118      * Writes an empty element tag to the output.
119      *
120      * @param localName local name of the tag.
121      * @throws XMLStreamException
122      */

123     public void writeEmptyElement(CharSequence JavaDoc localName) throws XMLStreamException;
124
125     /**
126      * Writes an end tag to the output relying on the internal state of the
127      * writer to determine the prefix and local name of the event.
128      *
129      * @throws XMLStreamException
130      */

131     public void writeEndElement() throws XMLStreamException;
132
133     /**
134      * Closes any start tags and writes corresponding end tags.
135      *
136      * @throws XMLStreamException
137      */

138     public void writeEndDocument() throws XMLStreamException;
139
140     /**
141      * Close this writer and free any resources associated with the writer. This
142      * must not close the underlying output stream.
143      *
144      * @throws XMLStreamException
145      */

146     public void close() throws XMLStreamException;
147
148     /**
149      * Write any cached data to the underlying output mechanism.
150      *
151      * @throws XMLStreamException
152      */

153     public void flush() throws XMLStreamException;
154
155     /**
156      * Writes an attribute to the output stream without a prefix.
157      *
158      * @param localName the local name of the attribute.
159      * @param value the value of the attribute.
160      * @throws IllegalStateException if the current state does not allow
161      * attribute writing.
162      * @throws XMLStreamException
163      */

164     public void writeAttribute(CharSequence JavaDoc localName, CharSequence JavaDoc value)
165             throws XMLStreamException;
166
167     /**
168      * Writes an attribute to the output stream.
169      *
170      * @param prefix the prefix for this attribute.
171      * @param namespaceURI the uri of the prefix for this attribute
172      * @param localName the local name of the attribute.
173      * @param value the value of the attribute.
174      * @throws IllegalStateException if the current state does not allow
175      * attribute writing.
176      * @throws XMLStreamException if the namespace URI has not been bound
177      * to a prefix and this writer does not {@link
178      * XMLOutputFactory#IS_REPAIRING_NAMESPACES repair namespaces}.
179      */

180
181     public void writeAttribute(CharSequence JavaDoc prefix, CharSequence JavaDoc namespaceURI,
182             CharSequence JavaDoc localName, CharSequence JavaDoc value)
183             throws XMLStreamException;
184
185     /**
186      * Writes an attribute to the output stream.
187      *
188      * @param namespaceURI the uri of the prefix for this attribute.
189      * @param localName the local name of the attribute.
190      * @param value the value of the attribute.
191      * @throws IllegalStateException if the current state does not allow
192      * attribute writing.
193      * @throws XMLStreamException if the namespace URI has not been bound
194      * to a prefix and this writer does not {@link
195      * XMLOutputFactory#IS_REPAIRING_NAMESPACES repair namespaces}.
196      */

197     public void writeAttribute(CharSequence JavaDoc namespaceURI,
198             CharSequence JavaDoc localName, CharSequence JavaDoc value)
199             throws XMLStreamException;
200
201     /**
202      * Writes a namespace to the output stream. If the prefix argument to this
203      * method is the empty string, "xmlns", or <code>null</code> this method
204      * will delegate to writeDefaultNamespace.
205      *
206      * @param prefix the prefix to bind this namespace to or <code>null</code>
207      * @param namespaceURI the uri to bind the prefix.
208      * @throws IllegalStateException if the current state does not allow
209      * namespace writing.
210      * @throws XMLStreamException
211      */

212     public void writeNamespace(CharSequence JavaDoc prefix, CharSequence JavaDoc namespaceURI)
213             throws XMLStreamException;
214
215     /**
216      * Writes the default namespace to the stream.
217      *
218      * @param namespaceURI the uri to bind the default namespace to or
219      * <code>null</code> (to map the prefix to <code>""</code> URI)
220      * @throws IllegalStateException if the current state does not allow
221      * namespace writing.
222      * @throws XMLStreamException
223      */

224     public void writeDefaultNamespace(CharSequence JavaDoc namespaceURI)
225             throws XMLStreamException;
226
227     /**
228      * Writes an xml comment with the data enclosed.
229      *
230      * @param data the data contained in the comment or <code>null</code>
231      * @throws XMLStreamException
232      */

233     public void writeComment(CharSequence JavaDoc data) throws XMLStreamException;
234
235     /**
236      * Writes a processing instruction.
237      *
238      * @param target the target of the processing instruction.
239      * @throws XMLStreamException
240      */

241     public void writeProcessingInstruction(CharSequence JavaDoc target)
242             throws XMLStreamException;
243
244     /**
245      * Writes a processing instruction
246      *
247      * @param target the target of the processing instruction.
248      * @param data the data contained in the processing instruction.
249      * @throws XMLStreamException
250      */

251     public void writeProcessingInstruction(CharSequence JavaDoc target,
252             CharSequence JavaDoc data) throws XMLStreamException;
253
254     /**
255      * Writes a CData section.
256      *
257      * @param data the data contained in the CData Section.
258      * @throws XMLStreamException
259      */

260     public void writeCData(CharSequence JavaDoc data) throws XMLStreamException;
261
262     /**
263      * Writes a DTD section (representing the entire doctypedecl
264      * production from the XML 1.0 specification).
265      *
266      * @param dtd the DTD to be written.
267      * @throws XMLStreamException
268      */

269     public void writeDTD(CharSequence JavaDoc dtd) throws XMLStreamException;
270
271     /**
272      * Writes an entity reference
273      *
274      * @param name the name of the entity.
275      * @throws XMLStreamException
276      */

277     public void writeEntityRef(CharSequence JavaDoc name) throws XMLStreamException;
278
279     /**
280      * Writes the XML Declaration. Defaults the XML version to 1.0 and the
281      * encoding (if any) to the one specified when the instance is created
282      * using {@link XMLOutputFactory}.
283      *
284      * @throws XMLStreamException
285      */

286     public void writeStartDocument() throws XMLStreamException;
287
288     /**
289      * Writes the XML Declaration. Default the encoding (if any) to the one
290      * specified when the instance is created using {@link XMLOutputFactory}.
291      *
292      * @param version the version of the xml document or <code>null</code>.
293      * @throws XMLStreamException
294      */

295     public void writeStartDocument(CharSequence JavaDoc version)
296             throws XMLStreamException;
297
298     /**
299      * Writes the XML Declaration. Note that the encoding parameter does not set
300      * the actual encoding of the underlying output. That must be set when the
301      * instance when the instance is created using {@link XMLOutputFactory}.
302      *
303      * @param encoding the encoding of the xml declaration or <code>null</code>.
304      * @param version the version of the xml document or <code>null</code>.
305      * @throws XMLStreamException
306      */

307     public void writeStartDocument(CharSequence JavaDoc encoding, CharSequence JavaDoc version)
308             throws XMLStreamException;
309
310     /**
311      * Writes text to the output.
312      *
313      * @param text the value to write or <code>null</code>.
314      * @throws XMLStreamException
315      */

316     public void writeCharacters(CharSequence JavaDoc text) throws XMLStreamException;
317
318     /**
319      * Writes text to the output.
320      *
321      * @param text the value to write
322      * @param start the starting position in the array.
323      * @param length the number of characters to write.
324      * @throws XMLStreamException
325      */

326     public void writeCharacters(char[] text, int start, int length)
327             throws XMLStreamException;
328
329     /**
330      * Gets the prefix the specified uri is bound to.
331      *
332      * @param uri namespace URI
333      * @return the prefix for the URI or <code>null</code>
334      * @throws XMLStreamException
335      */

336     public CharSequence JavaDoc getPrefix(CharSequence JavaDoc uri) throws XMLStreamException;
337
338     /**
339      * Sets the prefix the uri is bound to. This prefix is bound in the scope of
340      * the current START_ELEMENT / END_ELEMENT pair. If this method is called
341      * before a START_ELEMENT has been written the prefix is bound in the root
342      * scope.
343      *
344      * @param prefix the prefix to bind to the uri.
345      * @param uri the uri to bind to the prefix or <code>null</code>
346      * @throws XMLStreamException
347      */

348     public void setPrefix(CharSequence JavaDoc prefix, CharSequence JavaDoc uri)
349             throws XMLStreamException;
350
351     /**
352      * Binds a URI to the default namespace. This URI is bound in the scope of
353      * the current START_ELEMENT / END_ELEMENT pair. If this method is called
354      * before a START_ELEMENT has been written the uri is bound in the root
355      * scope.
356      *
357      * @param uri the uri to bind to the default namespace or <code>null</code>.
358      * @throws XMLStreamException
359      */

360     public void setDefaultNamespace(CharSequence JavaDoc uri) throws XMLStreamException;
361
362     /**
363      * Gets the value of a feature/property from the underlying implementation.
364      *
365      * @param name the name of the property.
366      * @return the value of the property.
367      * @throws IllegalArgumentException if the property is not supported.
368      */

369     public Object JavaDoc getProperty(String JavaDoc name)
370             throws IllegalArgumentException JavaDoc;
371
372 }
Popular Tags