001: /*
002: * Javolution - Java(TM) Solution for Real-Time and Embedded Systems
003: * Copyright (C) 2006 - Javolution (http://javolution.org/)
004: * All rights reserved.
005: *
006: * Permission to use, copy, modify, and distribute this software is
007: * freely granted, provided that this notice is preserved.
008: */
009: package javolution.xml.stream;
010:
011: import j2me.lang.CharSequence;
012:
013: /**
014: * <p> This interface is similar to
015: * <code>javax.xml.stream.XMLStreamWriter</code>; but it does not forces
016: * dynamic allocation when formatting (any {@link CharSequence CharSequence}
017: * can be used instead of {@link String}).</p>
018: *
019: * <p> Except for the speed (faster) and the added flexibility, the
020: * usage/behavior is about the same as its StAX counterpart.</p>
021: *
022: * <p> This writer does not require creating new <code>String</code> objects
023: * during XML formatting. Attributes values can be held by a single/reusable
024: * {@link javolution.text.TextBuilder TextBuilder}
025: * (or <code>StringBuilder</code>) instance to avoid adverse effects
026: * on memory footprint (heap), garbage collection and performance.
027: * For example:[code]
028: *
029: * // Creates a new writer (potentially recycled).
030: * XMLOutputFactory factory = XMLOutputFactory.newInstance();
031: * XMLStreamWriter writer = factory.createXMLStreamWriter(outputStream);
032: *
033: * TextBuilder tmp = new TextBuilder();
034: * writer.writeStartDocument();
035: * ...
036: * writer.writeStartElement("Time");
037: * // Writes primitive types (int) attributes (no memory allocation).
038: * writer.writeAttribute("hour", tmp.clear().append(time.hour);
039: * writer.writeAttribute("minute", tmp.clear().append(time.minute);
040: * writer.writeAttribute("second", tmp.clear().append(time.second);
041: * writer.writeEndElement();
042: * ...
043: *
044: * writer.close(); // Recycles this writer.
045: * outputStream.close(); // Underlying stream has to be closed explicitly.
046: * [/code]</p>
047: *
048: * <p> Note: As always, <code>null</code> parameters are not allowed unless
049: * explicitly authorized.</p>
050: *
051: * @author <a href="mailto:jean-marie@dautelle.com">Jean-Marie Dautelle</a>
052: * @version 4.0, June 16, 2006
053: */
054: public interface XMLStreamWriter {
055:
056: /**
057: * Writes a start tag to the output. All writeStartElement methods open a
058: * new scope in the internal namespace context. Writing the corresponding
059: * EndElement causes the scope to be closed.
060: *
061: * @param localName local name of the tag.
062: * @throws XMLStreamException
063: */
064: public void writeStartElement(CharSequence localName)
065: throws XMLStreamException;
066:
067: /**
068: * Writes a start tag to the output.
069: *
070: * @param namespaceURI the namespaceURI of the prefix to use.
071: * @param localName local name of the tag.
072: * @throws XMLStreamException if the namespace URI has not been bound
073: * to a prefix and this writer does not {@link
074: * XMLOutputFactory#IS_REPAIRING_NAMESPACES repair namespaces}.
075: */
076: public void writeStartElement(CharSequence namespaceURI,
077: CharSequence localName) throws XMLStreamException;
078:
079: /**
080: * Writes a start tag to the output.
081: *
082: * @param localName local name of the tag.
083: * @param prefix the prefix of the tag.
084: * @param namespaceURI the uri to bind the prefix to.
085: * @throws XMLStreamException if the namespace URI has not been bound
086: * to a prefix and this writer does not {@link
087: * XMLOutputFactory#IS_REPAIRING_NAMESPACES repair namespaces}.
088: */
089: public void writeStartElement(CharSequence prefix,
090: CharSequence localName, CharSequence namespaceURI)
091: throws XMLStreamException;
092:
093: /**
094: * Writes an empty element tag to the output.
095: *
096: * @param namespaceURI the uri to bind the tag to.
097: * @param localName local name of the tag.
098: * @throws XMLStreamException if the namespace URI has not been bound
099: * to a prefix and this writer does not {@link
100: * XMLOutputFactory#IS_REPAIRING_NAMESPACES repair namespaces}.
101: */
102: public void writeEmptyElement(CharSequence namespaceURI,
103: CharSequence localName) throws XMLStreamException;
104:
105: /**
106: * Writes an empty element tag to the output.
107: *
108: * @param prefix the prefix of the tag.
109: * @param localName local name of the tag.
110: * @param namespaceURI the uri to bind the tag to.
111: * @throws XMLStreamException if the namespace URI has not been bound
112: * to a prefix and this writer does not {@link
113: * XMLOutputFactory#IS_REPAIRING_NAMESPACES repair namespaces}.
114: */
115: public void writeEmptyElement(CharSequence prefix,
116: CharSequence localName, CharSequence namespaceURI)
117: throws XMLStreamException;
118:
119: /**
120: * Writes an empty element tag to the output.
121: *
122: * @param localName local name of the tag.
123: * @throws XMLStreamException
124: */
125: public void writeEmptyElement(CharSequence localName)
126: throws XMLStreamException;
127:
128: /**
129: * Writes an end tag to the output relying on the internal state of the
130: * writer to determine the prefix and local name of the event.
131: *
132: * @throws XMLStreamException
133: */
134: public void writeEndElement() throws XMLStreamException;
135:
136: /**
137: * Closes any start tags and writes corresponding end tags.
138: *
139: * @throws XMLStreamException
140: */
141: public void writeEndDocument() throws XMLStreamException;
142:
143: /**
144: * Close this writer and free any resources associated with the writer. This
145: * must not close the underlying output stream.
146: *
147: * @throws XMLStreamException
148: */
149: public void close() throws XMLStreamException;
150:
151: /**
152: * Write any cached data to the underlying output mechanism.
153: *
154: * @throws XMLStreamException
155: */
156: public void flush() throws XMLStreamException;
157:
158: /**
159: * Writes an attribute to the output stream without a prefix.
160: *
161: * @param localName the local name of the attribute.
162: * @param value the value of the attribute.
163: * @throws IllegalStateException if the current state does not allow
164: * attribute writing.
165: * @throws XMLStreamException
166: */
167: public void writeAttribute(CharSequence localName,
168: CharSequence value) throws XMLStreamException;
169:
170: /**
171: * Writes an attribute to the output stream.
172: *
173: * @param prefix the prefix for this attribute.
174: * @param namespaceURI the uri of the prefix for this attribute
175: * @param localName the local name of the attribute.
176: * @param value the value of the attribute.
177: * @throws IllegalStateException if the current state does not allow
178: * attribute writing.
179: * @throws XMLStreamException if the namespace URI has not been bound
180: * to a prefix and this writer does not {@link
181: * XMLOutputFactory#IS_REPAIRING_NAMESPACES repair namespaces}.
182: */
183:
184: public void writeAttribute(CharSequence prefix,
185: CharSequence namespaceURI, CharSequence localName,
186: CharSequence value) throws XMLStreamException;
187:
188: /**
189: * Writes an attribute to the output stream.
190: *
191: * @param namespaceURI the uri of the prefix for this attribute.
192: * @param localName the local name of the attribute.
193: * @param value the value of the attribute.
194: * @throws IllegalStateException if the current state does not allow
195: * attribute writing.
196: * @throws XMLStreamException if the namespace URI has not been bound
197: * to a prefix and this writer does not {@link
198: * XMLOutputFactory#IS_REPAIRING_NAMESPACES repair namespaces}.
199: */
200: public void writeAttribute(CharSequence namespaceURI,
201: CharSequence localName, CharSequence value)
202: throws XMLStreamException;
203:
204: /**
205: * Writes a namespace to the output stream. If the prefix argument to this
206: * method is the empty string, "xmlns", or <code>null</code> this method
207: * will delegate to writeDefaultNamespace.
208: *
209: * @param prefix the prefix to bind this namespace to or <code>null</code>
210: * @param namespaceURI the uri to bind the prefix.
211: * @throws IllegalStateException if the current state does not allow
212: * namespace writing.
213: * @throws XMLStreamException
214: */
215: public void writeNamespace(CharSequence prefix,
216: CharSequence namespaceURI) throws XMLStreamException;
217:
218: /**
219: * Writes the default namespace to the stream.
220: *
221: * @param namespaceURI the uri to bind the default namespace to or
222: * <code>null</code> (to map the prefix to <code>""</code> URI)
223: * @throws IllegalStateException if the current state does not allow
224: * namespace writing.
225: * @throws XMLStreamException
226: */
227: public void writeDefaultNamespace(CharSequence namespaceURI)
228: throws XMLStreamException;
229:
230: /**
231: * Writes an xml comment with the data enclosed.
232: *
233: * @param data the data contained in the comment or <code>null</code>
234: * @throws XMLStreamException
235: */
236: public void writeComment(CharSequence data)
237: throws XMLStreamException;
238:
239: /**
240: * Writes a processing instruction.
241: *
242: * @param target the target of the processing instruction.
243: * @throws XMLStreamException
244: */
245: public void writeProcessingInstruction(CharSequence target)
246: throws XMLStreamException;
247:
248: /**
249: * Writes a processing instruction
250: *
251: * @param target the target of the processing instruction.
252: * @param data the data contained in the processing instruction.
253: * @throws XMLStreamException
254: */
255: public void writeProcessingInstruction(CharSequence target,
256: CharSequence data) throws XMLStreamException;
257:
258: /**
259: * Writes a CData section.
260: *
261: * @param data the data contained in the CData Section.
262: * @throws XMLStreamException
263: */
264: public void writeCData(CharSequence data) throws XMLStreamException;
265:
266: /**
267: * Writes a DTD section (representing the entire doctypedecl
268: * production from the XML 1.0 specification).
269: *
270: * @param dtd the DTD to be written.
271: * @throws XMLStreamException
272: */
273: public void writeDTD(CharSequence dtd) throws XMLStreamException;
274:
275: /**
276: * Writes an entity reference
277: *
278: * @param name the name of the entity.
279: * @throws XMLStreamException
280: */
281: public void writeEntityRef(CharSequence name)
282: throws XMLStreamException;
283:
284: /**
285: * Writes the XML Declaration. Defaults the XML version to 1.0 and the
286: * encoding (if any) to the one specified when the instance is created
287: * using {@link XMLOutputFactory}.
288: *
289: * @throws XMLStreamException
290: */
291: public void writeStartDocument() throws XMLStreamException;
292:
293: /**
294: * Writes the XML Declaration. Default the encoding (if any) to the one
295: * specified when the instance is created using {@link XMLOutputFactory}.
296: *
297: * @param version the version of the xml document or <code>null</code>.
298: * @throws XMLStreamException
299: */
300: public void writeStartDocument(CharSequence version)
301: throws XMLStreamException;
302:
303: /**
304: * Writes the XML Declaration. Note that the encoding parameter does not set
305: * the actual encoding of the underlying output. That must be set when the
306: * instance when the instance is created using {@link XMLOutputFactory}.
307: *
308: * @param encoding the encoding of the xml declaration or <code>null</code>.
309: * @param version the version of the xml document or <code>null</code>.
310: * @throws XMLStreamException
311: */
312: public void writeStartDocument(CharSequence encoding,
313: CharSequence version) throws XMLStreamException;
314:
315: /**
316: * Writes text to the output.
317: *
318: * @param text the value to write or <code>null</code>.
319: * @throws XMLStreamException
320: */
321: public void writeCharacters(CharSequence text)
322: throws XMLStreamException;
323:
324: /**
325: * Writes text to the output.
326: *
327: * @param text the value to write
328: * @param start the starting position in the array.
329: * @param length the number of characters to write.
330: * @throws XMLStreamException
331: */
332: public void writeCharacters(char[] text, int start, int length)
333: throws XMLStreamException;
334:
335: /**
336: * Gets the prefix the specified uri is bound to.
337: *
338: * @param uri namespace URI
339: * @return the prefix for the URI or <code>null</code>
340: * @throws XMLStreamException
341: */
342: public CharSequence getPrefix(CharSequence uri)
343: throws XMLStreamException;
344:
345: /**
346: * Sets the prefix the uri is bound to. This prefix is bound in the scope of
347: * the current START_ELEMENT / END_ELEMENT pair. If this method is called
348: * before a START_ELEMENT has been written the prefix is bound in the root
349: * scope.
350: *
351: * @param prefix the prefix to bind to the uri.
352: * @param uri the uri to bind to the prefix or <code>null</code>
353: * @throws XMLStreamException
354: */
355: public void setPrefix(CharSequence prefix, CharSequence uri)
356: throws XMLStreamException;
357:
358: /**
359: * Binds a URI to the default namespace. This URI is bound in the scope of
360: * the current START_ELEMENT / END_ELEMENT pair. If this method is called
361: * before a START_ELEMENT has been written the uri is bound in the root
362: * scope.
363: *
364: * @param uri the uri to bind to the default namespace or <code>null</code>.
365: * @throws XMLStreamException
366: */
367: public void setDefaultNamespace(CharSequence uri)
368: throws XMLStreamException;
369:
370: /**
371: * Gets the value of a feature/property from the underlying implementation.
372: *
373: * @param name the name of the property.
374: * @return the value of the property.
375: * @throws IllegalArgumentException if the property is not supported.
376: */
377: public Object getProperty(String name)
378: throws IllegalArgumentException;
379:
380: }
|