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   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   namespaceURI,
77              CharSequence   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   prefix, CharSequence   localName,
90              CharSequence   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   namespaceURI,
102             CharSequence   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   prefix, CharSequence   localName,
115             CharSequence   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   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   localName, CharSequence   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   prefix, CharSequence   namespaceURI,
182             CharSequence   localName, CharSequence   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   namespaceURI,
198             CharSequence   localName, CharSequence   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   prefix, CharSequence   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   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   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   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   target,
252             CharSequence   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   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   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   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   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   encoding, CharSequence   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   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   getPrefix(CharSequence   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   prefix, CharSequence   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   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   getProperty(String   name)
370             throws IllegalArgumentException  ;
371 
372 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags