XMLObjectReader


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  ;
14  import java.io.InputStream  ;
15  import java.io.Reader  ;
16  
17  import javolution.context.ObjectFactory;
18  import javolution.lang.Reusable;
19  import javolution.xml.stream.XMLStreamException;
20  import javolution.xml.stream.XMLStreamReader;
21  import javolution.xml.stream.XMLStreamReaderImpl;
22  
23  /**
24   * <p> This class restores objects which have been serialized in XML
25   *     format using an {@link XMLObjectWriter}.</p>
26   *     
27   * <p> When the XML document is parsed, each elements are recursively
28   *     processed and Java objects are created using the {@link XMLFormat}
29   *     of the class as identified by the {@link XMLBinding}.</p>
30   *     
31   * <p> Multiple objects can be read from the same XML input.
32   *     For example:[code]
33   *     XMLObjectReader reader = XMLObjectReader.newInstance(inputStream);
34   *     while (reader.hasNext()) {
35   *         Message message = reader.read("Message", Message.class);
36   *     }
37   *     reader.close(); // Reader is recycled, the underlying stream is closed.
38   *     [/code]</p>
39   *     
40   * @author  <a HREF="mailto:jean-marie@dautelle.com">Jean-Marie Dautelle</a>
41   * @version 4.0, September 4, 2006
42   */
43  public class XMLObjectReader implements Reusable {
44  
45      /**
46       * Holds the associated factory.
47       */
48      private static final ObjectFactory FACTORY = new ObjectFactory() {
49  
50          protected Object   create() {
51              return new XMLObjectReader();
52          } 
53          protected void cleanup(Object   obj) {
54              ((XMLObjectReader)obj).reset();
55          } 
56      };
57  
58      /**
59       * Hold the xml element used when parsing.
60       */
61      private final XMLFormat.InputElement _xml = new XMLFormat.InputElement();
62  
63      /**
64       * Holds reader if any.
65       */
66      private Reader   _reader;
67  
68      /**
69       * Holds input stream if any.
70       */
71      private InputStream   _inputStream;
72  
73      /**
74       * Indicates if factory produced.
75       */
76      private boolean _isFactoryProduced;
77  
78      /**
79       * Returns a XML object reader (potentially recycled) having the specified
80       * input stream as input.
81       * 
82       * @param in the input stream.
83       */
84      public static XMLObjectReader newInstance(InputStream   in) throws XMLStreamException {
85          XMLObjectReader reader = (XMLObjectReader) FACTORY.object();
86          reader._isFactoryProduced = true;
87          reader.setInput(in);
88          return reader;
89      }
90  
91      /**
92       * Returns a XML object reader (potentially recycled) having the specified
93       * input stream/encoding as input.
94       * 
95       * @param in the input stream.
96       * @param encoding the input stream encoding
97       */
98      public static XMLObjectReader newInstance(InputStream   in, String   encoding) throws XMLStreamException {
99          XMLObjectReader reader = (XMLObjectReader) FACTORY.object();
100         reader._isFactoryProduced = true;
101         reader.setInput(in, encoding);
102         return reader;
103     }
104 
105     /**
106      * Returns a XML object reader (potentially recycled) having the specified
107      * reader as input.
108      * 
109      * @param in the reader source.
110      */
111     public static XMLObjectReader newInstance(Reader   in) throws XMLStreamException {
112         XMLObjectReader reader = (XMLObjectReader) FACTORY.object();
113         reader._isFactoryProduced = true;
114         reader.setInput(in);
115         return reader;
116     }
117 
118     /**
119      * Default constructor.
120      */
121     public XMLObjectReader() {
122     }
123 
124     /**
125      * Returns the stream reader being used by this reader (it can be 
126      * used to set prefix, read prologs, etc).
127      * 
128      * @return the stream reader.
129      */
130     public XMLStreamReader getStreamReader() {
131         return _xml._reader;
132     }
133 
134     /**
135      * Sets the input stream source for this XML object reader
136      * (encoding retrieved from XML prolog if any).
137      * 
138      * @param  in the source input stream.
139      * @return <code>this</code>
140      * @see    XMLStreamReaderImpl#setInput(InputStream)
141      */
142     public XMLObjectReader setInput(InputStream   in) throws XMLStreamException {
143         if ((_inputStream != null) || (_reader != null))
144             throw new IllegalStateException  ("Reader not closed or reset");
145         _xml._reader.setInput(in);
146         _inputStream = in;
147         return this;
148     }
149 
150     /**
151      * Sets the input stream source and encoding for this XML object reader.
152      * 
153      * @param in the input source.
154      * @param encoding the associated encoding.
155      * @return <code>this</code>
156      * @see    XMLStreamReaderImpl#setInput(InputStream, String)
157      */
158     public XMLObjectReader setInput(InputStream   in, String   encoding)
159             throws XMLStreamException {
160         if ((_inputStream != null) || (_reader != null))
161             throw new IllegalStateException  ("Reader not closed or reset");
162         _xml._reader.setInput(in, encoding);
163         _inputStream = in;
164         return this;
165     }
166 
167     /**
168      * Sets the reader input source for this XML stream reader. 
169      * 
170      * @param  in the source reader.
171      * @return <code>this</code>
172      * @see    XMLStreamReaderImpl#setInput(Reader)
173      */
174     public XMLObjectReader setInput(Reader   in) throws XMLStreamException {
175         if ((_inputStream != null) || (_reader != null))
176             throw new IllegalStateException  ("Reader not closed or reset");
177         _xml._reader.setInput(in);
178         _reader = in;
179         return this;
180     }
181 
182     /**
183      * Sets the XML binding to use with this object reader.
184      * 
185      * @param binding the XML binding to use.
186      * @return <code>this</code>
187      */
188     public XMLObjectReader setBinding(XMLBinding binding) {
189         _xml.setBinding(binding);
190         return this;
191     }
192 
193     /**
194      * Sets the XML reference resolver to use with this object reader
195      * (the same resolver can be used accross multiple readers).
196      * 
197      * @param referenceResolver the XML reference resolver.
198      * @return <code>this</code>
199      */
200     public XMLObjectReader setReferenceResolver(
201             XMLReferenceResolver referenceResolver) {
202         _xml.setReferenceResolver(referenceResolver);
203         return this;
204     }
205 
206     /**
207      * Indicates if more elements can be read. This method 
208      * positions the reader at the start of the
209      * next element to be read (if any).
210      *
211      * @return <code>true</code> if more element/data to be read; 
212      *         <code>false</code> otherwise.
213      * @see    XMLFormat.InputElement#hasNext()
214      */
215     public boolean hasNext() throws XMLStreamException {
216         return _xml.hasNext();
217     }
218 
219     /**
220      * Returns the object corresponding to the next element/data.
221      *
222      * @return the next nested object (can be <code>null</code>)
223      * @throws XMLStreamException if <code>hasNext() == false</code>
224      * @see    XMLFormat.InputElement#getNext()
225      */
226     public /*<T>*/Object  /*{T}*/ read() throws XMLStreamException {
227         return (Object  /*{T}*/)_xml.getNext();
228     }
229 
230     /**
231      * Returns the object corresponding to the next nested element only 
232      * if it has the specified local name. 
233      *
234      * @param name the local name of the next element.
235      * @return the next content object or <code>null</code> if the 
236      *         local name does not match.
237      * @see    XMLFormat.InputElement#get(String)
238      */
239     public /*<T>*/Object  /*{T}*/ read(String   name) throws XMLStreamException {
240         return (Object  /*{T}*/) _xml.get(name);
241     }
242 
243     /**
244      * Returns the object corresponding to the next nested element only 
245      * if it has the specified local name and namespace URI.
246      *
247      * @param localName the local name.
248      * @param uri the namespace URI.
249      * @return the next content object or <code>null</code> if the 
250      *         name/uri does not match.
251      * @see    XMLFormat.InputElement#get(String, String)
252      */
253     public /*<T>*/Object  /*{T}*/ read(String   localName, String   uri)
254             throws XMLStreamException {
255         return (Object  /*{T}*/) _xml.get(localName, uri);
256     }
257 
258     /**
259      * Returns the object corresponding to the next nested element only 
260      * if it has the specified local name; the actual object type is identified 
261      * by the specified class parameter. 
262      *      
263      * @param name the name of the element to match.
264      * @param cls the non-abstract class identifying the object to return.
265      * @return <code>read(name, null, cls)</code>
266      */
267     public/*<T>*/Object  /*{T}*/read(String   name, Class  /*<T>*/cls)
268             throws XMLStreamException {
269         return _xml.get(name, cls);
270     }
271 
272     /**
273      * Returns the object corresponding to the next nested element only 
274      * if it has the specified local name and namespace URI; the 
275      * actual object type is identified by the specified class parameter. 
276      *      
277      * @param localName the local name.
278      * @param uri the namespace URI.
279      * @param cls the non-abstract class identifying the object to return.
280      * @return the next content object or <code>null</code> if no match.
281      */
282     public/*<T>*/Object  /*{T}*/read(String   localName, String   uri,
283             Class  /*<T>*/cls) throws XMLStreamException {
284         return _xml.get(localName, uri, cls);
285     }
286 
287     /**
288      * Closes this reader and its underlying input then {@link #reset reset}
289      * this reader for potential reuse.
290      */
291     public void close() throws XMLStreamException {
292         try {
293             if (_inputStream != null) {
294                 _inputStream.close();
295                 reset();
296             } else if (_reader != null) {
297                 _reader.close();
298                 reset();
299             }
300             if (_isFactoryProduced) {
301                 FACTORY.recycle(this);
302             }
303         } catch (IOException   e) {
304             throw new XMLStreamException(e);
305         }
306     }
307 
308     /**
309      * Resets this object reader for reuse.
310      */
311     public void reset() {
312         _xml.reset();
313         _reader = null;
314         _inputStream = null;
315     }
316 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags