KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javolution > xml > XMLObjectWriter


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;
10
11 import j2me.lang.IllegalStateException;
12
13 import java.io.IOException JavaDoc;
14 import java.io.OutputStream JavaDoc;
15 import java.io.Writer JavaDoc;
16
17 import javolution.context.ObjectFactory;
18 import javolution.lang.Reusable;
19 import javolution.xml.stream.XMLStreamException;
20 import javolution.xml.stream.XMLStreamWriter;
21 import javolution.xml.stream.XMLStreamWriterImpl;
22
23 /**
24  * <p> This class takes an object and formats it to XML; the resulting
25  * XML can be deserialized using a {@link XMLObjectReader}.</p>
26  *
27  * <p> When an object is formatted, the {@link XMLFormat} of the
28  * object's class as identified by the {@link XMLBinding} is used to
29  * write its XML representation.</p>
30  *
31  * <p> Multiple objects can be written to the same XML output.
32  * For example:[code]
33  * XMLObjectWriter writer = XMLObjectWriter.newInstance(outputStream);
34  * while (true)) {
35  * Message message = ...
36  * writer.write(message, "Message", Message.class);
37  * }
38  * writer.close(); // Writer is recycled, the underlying stream is closed.
39  * [/code]</p>
40  *
41  * @author <a HREF="mailto:jean-marie@dautelle.com">Jean-Marie Dautelle</a>
42  * @version 4.0, September 4, 2006
43  */
44 public class XMLObjectWriter implements Reusable {
45
46     /**
47      * Holds the associated factory.
48      */
49     private static final ObjectFactory FACTORY = new ObjectFactory() {
50
51         protected Object JavaDoc create() {
52             return new XMLObjectWriter();
53         }
54         protected void cleanup(Object JavaDoc obj) {
55             ((XMLObjectWriter)obj).reset();
56         }
57     };
58
59     /**
60      * Hold the xml element used when formatting.
61      */
62     private final XMLFormat.OutputElement _xml
63         = new XMLFormat.OutputElement();
64
65     /**
66      * Holds writer if any.
67      */
68     private Writer JavaDoc _writer;
69
70     /**
71      * Holds input stream if any.
72      */
73     private OutputStream JavaDoc _outputStream;
74
75     /**
76      * Indicates if factory produced.
77      */
78     private boolean _isFactoryProduced;
79
80     /**
81      * Default constructor.
82      */
83     public XMLObjectWriter() {
84     }
85
86     /**
87      * Returns a XML object writer (potentially recycled) having the specified
88      * output stream as output.
89      *
90      * @param out the output stream.
91      */
92     public static XMLObjectWriter newInstance(OutputStream JavaDoc out) throws XMLStreamException {
93         XMLObjectWriter writer = (XMLObjectWriter) FACTORY.object();
94         writer._isFactoryProduced = true;
95         writer.setOutput(out);
96         return writer;
97     }
98
99     /**
100      * Returns a XML object writer (potentially recycled) having the specified
101      * output stream/encoding as output.
102      *
103      * @param out the output stream.
104      * @param encoding the output stream encoding.
105      */
106     public static XMLObjectWriter newInstance(OutputStream JavaDoc out, String JavaDoc encoding) throws XMLStreamException {
107         XMLObjectWriter writer = (XMLObjectWriter) FACTORY.object();
108         writer._isFactoryProduced = true;
109         writer.setOutput(out, encoding);
110         return writer;
111     }
112
113     /**
114      * Returns a XML object writer (potentially recycled) having the specified
115      * writer as output.
116      *
117      * @param out the writer output.
118      */
119     public static XMLObjectWriter newInstance(Writer JavaDoc out) throws XMLStreamException {
120         XMLObjectWriter writer = (XMLObjectWriter) FACTORY.object();
121         writer._isFactoryProduced = true;
122         writer.setOutput(out);
123         return writer;
124     }
125
126     /**
127      * Returns the stream writer used by this object writer (it can be used
128      * to write prolog, write namespaces, etc). The stream writer is setup to
129      * automatically repair namespaces and to automatically output empty
130      * elements when a start element is immediately followed by matching end
131      * element.
132      *
133      * @return the stream writer.
134      */
135     public XMLStreamWriter getStreamWriter() {
136         return _xml._writer;
137     }
138
139     /**
140      * Sets the output stream for this XML object writer.
141      *
142      * @param out the output stream destination.
143      * @return <code>this</code>
144      * @see XMLStreamWriterImpl#setOutput(OutputStream)
145      */
146     public XMLObjectWriter setOutput(OutputStream JavaDoc out) throws XMLStreamException {
147         if ((_outputStream != null) || (_writer != null))
148             throw new IllegalStateException JavaDoc("Writer not closed or reset");
149         _xml._writer.setOutput(out);
150         _outputStream = out;
151         _xml._writer.writeStartDocument();
152         return this;
153     }
154     
155     /**
156      * Sets the output stream and encoding for this XML object writer.
157      *
158      * @param out the output stream destination.
159      * @param encoding the stream encoding.
160      * @return <code>this</code>
161      * @see XMLStreamWriterImpl#setOutput(OutputStream, String)
162      */
163     public XMLObjectWriter setOutput(OutputStream JavaDoc out, String JavaDoc encoding) throws XMLStreamException {
164         if ((_outputStream != null) || (_writer != null))
165             throw new IllegalStateException JavaDoc("Writer not closed or reset");
166         _xml._writer.setOutput(out, encoding);
167         _outputStream = out;
168         _xml._writer.writeStartDocument();
169         return this;
170     }
171     
172     /**
173      * Sets the output writer for this XML object writer.
174      *
175      * @param out the writer destination.
176      * @return <code>this</code>
177      * @see XMLStreamWriterImpl#setOutput(Writer)
178      */
179     public XMLObjectWriter setOutput(Writer JavaDoc out) throws XMLStreamException {
180         if ((_outputStream != null) || (_writer != null))
181             throw new IllegalStateException JavaDoc("Writer not closed or reset");
182         _xml._writer.setOutput(out);
183         _writer = out;
184         _xml._writer.writeStartDocument();
185         return this;
186     }
187     
188     /**
189      * Sets the XML binding to use with this object writer.
190      *
191      * @param binding the XML binding to use.
192      * @return <code>this</code>
193      */
194     public XMLObjectWriter setBinding(XMLBinding binding) {
195         _xml.setBinding(binding);
196         return this;
197     }
198
199     /**
200      * Sets the indentation to be used by this writer (no indentation
201      * by default).
202      *
203      * @param indentation the indentation string.
204      * @return <code>this</code>
205      */
206     public XMLObjectWriter setIndentation(String JavaDoc indentation) {
207         _xml._writer.setIndentation(indentation);
208         return this;
209     }
210
211     /**
212      * Sets the XML reference resolver to use with this object writer
213      * (the same reference resolver can be used accross multiple writers).
214      *
215      * @param referenceResolver the XML reference resolver.
216      * @return <code>this</code>
217      */
218     public XMLObjectWriter setReferenceResolver(XMLReferenceResolver referenceResolver) {
219         _xml.setReferenceResolver(referenceResolver);
220         return this;
221     }
222
223     /**
224      * Writes the specified object as an anonymous nested element of
225      * unknown type.
226      *
227      * @param obj the object written as nested element or <code>null</code>.
228      * @see XMLFormat.OutputElement#add(Object)
229      */
230     public void write(Object JavaDoc obj) throws XMLStreamException {
231         _xml.add(obj);
232     }
233
234     /**
235      * Writes the specified object as a named nested element of unknown type
236      * (<code>null</code> objects are ignored). The nested XML element
237      * may contain a class attribute identifying the object type.
238      *
239      * @param obj the object added as nested element or <code>null</code>.
240      * @param name the name of the nested element.
241      * @see XMLFormat.OutputElement#add(Object, String)
242      */
243     public void write(Object JavaDoc obj, String JavaDoc name) throws XMLStreamException {
244         _xml.add(obj, name);
245     }
246
247     /**
248      * Writes the specified object as a fully qualified nested element of
249      * unknown type (<code>null</code> objects are ignored).
250      * The nested XML element may contain a class attribute identifying
251      * the object type.
252      *
253      * @param obj the object added as nested element or <code>null</code>.
254      * @param localName the local name of the nested element.
255      * @param uri the namespace URI of the nested element.
256      * @see XMLFormat.OutputElement#add(Object, String, String)
257      */
258     public void write(Object JavaDoc obj, String JavaDoc localName, String JavaDoc uri)
259             throws XMLStreamException {
260         _xml.add(obj, localName, uri);
261     }
262
263     /**
264      * Writes the specified object as a named nested element of actual type
265      * known (<code>null</code> objects are ignored).
266      *
267      * @param obj the object added as nested element or <code>null</code>.
268      * @param name the name of the nested element.
269      * @param cls the non-abstract class identifying the XML format to use.
270      * @see XMLFormat.OutputElement#add(Object, String, Class)
271      */
272     public /*<T>*/ void write(Object JavaDoc/*{T}*/ obj, String JavaDoc name, Class JavaDoc/*<T>*/ cls)
273             throws XMLStreamException {
274         _xml.add(obj, name, cls);
275     }
276
277     /**
278      * Writes the specified object as a fully qualified nested element of
279      * actual type known (<code>null</code> objects are ignored).
280      *
281      * @param obj the object added as nested element or <code>null</code>.
282      * @param localName the local name of the nested element.
283      * @param uri the namespace URI of the nested element.
284      * @param cls the class identifying the XML format to use.
285      * @see XMLFormat.OutputElement#add(Object, String, String, Class)
286      */
287     public /*<T>*/ void write(Object JavaDoc/*{T}*/ obj, String JavaDoc localName, String JavaDoc uri, Class JavaDoc/*<T>*/ cls)
288             throws XMLStreamException {
289         _xml.add(obj, localName, uri, cls);
290     }
291     
292     /**
293      * Flushes the output stream of this writer (automatically done
294      * when {@link #close() closing}).
295      */
296     public void flush() throws XMLStreamException {
297         _xml._writer.flush();
298     }
299     
300     /**
301      * Ends document writting, closes this writer and its underlying
302      * output then {@link #reset reset} this Writer for potential reuse.
303      */
304     public void close() throws XMLStreamException {
305         try {
306             if (_outputStream != null) {
307                 _xml._writer.writeEndDocument();
308                 _xml._writer.close();
309                 _outputStream.close();
310                 reset();
311             } else if (_writer != null) {
312                 _xml._writer.writeEndDocument();
313                 _xml._writer.close();
314                 _writer.close();
315                 reset();
316             }
317             if (_isFactoryProduced) {
318                 FACTORY.recycle(this);
319             }
320             
321         } catch (IOException JavaDoc e) {
322             throw new XMLStreamException(e);
323         }
324     }
325
326     /**
327      * Resets this object writer for reuse.
328      */
329     public void reset() {
330         _xml.reset();
331         _outputStream = null;
332         _writer = null;
333     }
334 }
Popular Tags