001    /* java.beans.XMLDecoder --
002       Copyright (C) 2004, 2005, 2006  Free Software Foundation, Inc.
003    
004    This file is part of GNU Classpath.
005    
006    GNU Classpath is free software; you can redistribute it and/or modify
007    it under the terms of the GNU General Public License as published by
008    the Free Software Foundation; either version 2, or (at your option)
009    any later version.
010    
011    GNU Classpath is distributed in the hope that it will be useful, but
012    WITHOUT ANY WARRANTY; without even the implied warranty of
013    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014    General Public License for more details.
015    
016    You should have received a copy of the GNU General Public License
017    along with GNU Classpath; see the file COPYING.  If not, write to the
018    Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
019    02110-1301 USA.
020    
021    Linking this library statically or dynamically with other modules is
022    making a combined work based on this library.  Thus, the terms and
023    conditions of the GNU General Public License cover the whole
024    combination.
025    
026    As a special exception, the copyright holders of this library give you
027    permission to link this library with independent modules to produce an
028    executable, regardless of the license terms of these independent
029    modules, and to copy and distribute the resulting executable under
030    terms of your choice, provided that you also meet, for each linked
031    independent module, the terms and conditions of the license of that
032    module.  An independent module is a module which is not derived from
033    or based on this library.  If you modify this library, you may extend
034    this exception to your version of the library, but you are not
035    obligated to do so.  If you do not wish to do so, delete this
036    exception statement from your version. */
037    
038    
039    package java.beans;
040    
041    import gnu.java.beans.DefaultExceptionListener;
042    import gnu.java.beans.decoder.PersistenceParser;
043    
044    import java.io.IOException;
045    import java.io.InputStream;
046    import java.util.Iterator;
047    import java.util.NoSuchElementException;
048    
049    /**
050     * The XMLDecoder reads XML data that is structured according to
051     * <a href="http://java.sun.com/products/jfc/tsc/articles/persistence3/javabeans.dtd">this</a> DTD
052     * and creates objects according to the content. Usually such data is generated using the
053     * {@link XMLEncoder} class.
054     * <p>
055     * An example XML document might look like this:
056     * <code>
057     * &lt;java&gt;
058     *      &lt;string&gt;Hello World&lt;/string&gt;
059     *      &lt;int&gt;200&lt;/int&gt;
060     * &lt;/java&gt;
061     * </code>
062     * <p>To read the <code>String</code> and the <code>Integer</code> instance the following can be used (assume
063     * the XML data can be obtained from the InputStream):</p>
064     * <code>
065     * XMLDecoder decoder = new XMLDecoder(inputStreamContainingXMLData);
066     * String message = (String) decoder.readObject();
067     * Integer number = (Integer) decoder.readObject();
068     * </code>
069     * <p>Besides this basic functionality the <code>XMLDecoder</code> has some more features that might come
070     * handy in certain situations:</p>
071     * <p>An owner object can be set using the <code>setOwner</code> method which can then be accessed when
072     * decoding. This feature is only useful if the XML data is aware of the owner object. Such data may
073     * look like this (assume that the owner object is a JFrame instance):</p>
074     * <code>
075     * &lt;java&gt;
076     *      &lt;void method="getOwner"&gt;
077     *              &lt;void method="setVisible"&gt;
078     *                      &lt;boolean&gt;true&lt;boolean&gt;
079     *              &lt;/void&gt;
080     *  &lt;/void&gt;
081     * &lt;/java&gt;
082     * </code>
083     * This accesses the <code>JFrame</code> and makes it visible using the <code>setVisible</code> method.
084     * <p>Please note that changing the owner <b>after</b> the having read the first object has no effect,
085     * because all object have been decoded then.</p>
086     * <p>If the <code>XMLDecoder</code> is created with no {@link ExceptionListener} instance a default one
087     * is used that prints an error message to <code>System.err</code> whenever a recoverable exception
088     * is thrown. Recovarable exceptions occur when the XML data cannot be interpreted correctly (e.g
089     * unknown classes or methods, invocation on null, ...). In general be very careful when the
090     * <code>XMLDecoder</code> provoked such exceptions because the resulting object(s) may be in an
091     * undesirable state.</p>
092     * <p>Note that changing the ExceptionListener instance after <code>readObject</code> has been called
093     * once has no effect because the decoding is completed then.</p>
094     * <p>At last one can provide a specific <code>ClassLoader</code> which is then used when <code>Class</code>
095     * objects are accessed. See {@link java.lang.Class#forName(String, boolean, ClassLoader)} for details
096     * on this.</p>
097     * <p>Note: If the <code>InputStream</code> instance given to any of the constructors is <code>null</code>
098     * the resulting <code>XMLDecoder</code> will be silently (without any exception) useless. Each call
099     * to <code>readObject</code> will return <code>null</code> and never throws an
100     * <code>ArrayIndexOutOfBoundsException</code>.</p>
101     *
102     * @author Robert Schuster
103     * @since 1.4
104     * @status updated to 1.5
105     */
106    public class XMLDecoder
107    {
108            private Object owner;
109    
110            private ExceptionListener exceptionListener;
111    
112            private InputStream inputStream;
113    
114            private boolean isStreamClosed;
115    
116            private ClassLoader classLoader;
117    
118            private Iterator iterator;
119    
120            /** Creates a XMLDecoder instance that parses the XML data of the given input stream.
121             * Using this constructor no special ClassLoader, a default ExceptionListener
122             * and no owner object is used.
123             *
124             * @param in InputStream to read XML data from.
125             */
126            public XMLDecoder(InputStream in)
127            {
128                    this(in, null);
129            }
130    
131            /** Creates a XMLDecoder instance that parses the XML data of the given input stream.
132             * Using this constructor no special ClassLoader and a default ExceptionListener
133             * is used.
134             *
135             * @param in InputStream to read XML data from.
136             * @param owner Owner object which can be accessed and modified while parsing.
137             */
138            public XMLDecoder(InputStream in, Object owner)
139            {
140                    this(in, owner, null);
141            }
142    
143            /** Creates a XMLDecoder instance that parses the XML data of the given input stream.
144             * If the ExceptionListener argument is null a default implementation is used.
145             *
146             * @param in InputStream to read XML data from.
147             * @param owner Owner object which can be accessed and modified while parsing.
148             * @param exceptionListener ExceptionListener instance to which exception notifications are send.
149             */
150            public XMLDecoder(
151                    InputStream in,
152                    Object owner,
153                    ExceptionListener exceptionListener)
154            {
155                    this(
156                            in,
157                            owner,
158                            exceptionListener,
159                            Thread.currentThread().getContextClassLoader());
160            }
161    
162            /** Creates a XMLDecoder instance that parses the XML data of the given input stream.
163             * If the ExceptionListener argument is null a default implementation is used.
164             *
165             * @param in InputStream to read XML data from.
166             * @param owner Owner object which can be accessed and modified while parsing.
167             * @param listener ExceptionListener instance to which exception notifications are send.
168             * @param cl ClassLoader instance that is used for calls to <code>Class.forName(String, boolean, ClassLoader)</code>
169             * @since 1.5
170             */
171            public XMLDecoder(
172                    InputStream in,
173                    Object owner,
174                    ExceptionListener listener,
175                    ClassLoader cl)
176            {
177                    // initially here was a check for the validity of the InputStream argument but some
178                    // great engineers decided that this API should silently discard this and behave rather
179                    // odd: readObject will always return null ...
180                    inputStream = in;
181    
182                    setExceptionListener(listener);
183    
184                    // validity of this object is checked in Class.forName() and therefore may be null
185                    classLoader = cl;
186    
187                    this.owner = owner;
188            }
189    
190            /** Closes the stream associated with this decoder. This should be done after having read all
191             * decoded objects.
192             * <p>See the description of the {@link #readObject()} for the effect caused by <code>close</code>.</p>
193             */
194            public void close()
195            {
196                    if (isStreamClosed)
197                    {
198                            return;
199                    }
200    
201                    try
202                    {
203                            inputStream.close();
204                            isStreamClosed = true;
205                    }
206                    catch (IOException e)
207                    {
208                            // bad style forced by original API design ...
209                    }
210            }
211    
212            /** Returns the ExceptionListener instance associated with this decoder.
213             * <p>See the description of {@link XMLDecoder} class for more information on the ExceptionListener.</p>
214             *
215             * @return Current ExceptionListener of the decoder.
216             */
217            public ExceptionListener getExceptionListener()
218            {
219                    return exceptionListener;
220            }
221    
222            /** Returns the owner object of the decoder. This method is usually called
223             * from within the parsed XML data.
224             * <p>See the description of {@link XMLDecoder} class for more information on the owner object.</p>
225             *
226             * @return The owner object of this decoder.
227             */
228            public Object getOwner()
229            {
230                    return owner;
231            }
232    
233            /** Returns the next available decoded object.
234             * <p>Note that the actual decoding takes place when the method is called for the first time.</p>
235             * <p>If the <code>close</code> method was already called a <code>NoSuchElementException</code>
236             * is thrown.</p>
237             * <p>If the InputStream instance used in the constructors was <code>null</code> this method
238             * will always return <code>null</code> itself.</p>
239             *
240             * @return The next object in a sequence decoded from XML data.
241             * @throws ArrayIndexOutOfBoundsException When no more objects are available.
242             */
243            public Object readObject() throws ArrayIndexOutOfBoundsException
244            {
245                    // note: the RI does it this way ...
246                    if(inputStream == null) {
247                            return null;
248                    }
249    
250                    // note: the original API documentation says nothing on what to do
251                    // when the stream was closed before readObject is called but it actually
252                    // throws a NoSuchElementException - this behaviour is imitated here
253                    if (isStreamClosed)
254                    {
255                            throw new NoSuchElementException("Cannot read any objects - XMLDecoder was already closed.");
256                    }
257    
258                    // creates the PersistenceParser (doing the parsing and decoding) and returns its
259                    // Iterator on first invocation
260                    if (iterator == null)
261                    {
262                            iterator =
263                                    new PersistenceParser(
264                                            inputStream,
265                                            exceptionListener,
266                                            classLoader,
267                                            this)
268                                            .iterator();
269                    }
270    
271                    // note: done according to the official documentation
272                    if (!iterator.hasNext())
273                    {
274                            throw new ArrayIndexOutOfBoundsException("No more objects available from this XMLDecoder.");
275                    }
276    
277                    // returns just the next object if there was no problem
278                    return iterator.next();
279            }
280    
281            /** Sets the ExceptionListener instance to which notifications of exceptions are send
282             * while parsing the XML data.
283             * <p>See the description of {@link XMLDecoder} class for more information on the ExceptionListener.</p>
284             *
285             * @param listener
286             */
287            public void setExceptionListener(ExceptionListener listener)
288            {
289                    // uses a default implementation when null
290                    if (listener == null)
291                    {
292                            listener = DefaultExceptionListener.INSTANCE;
293                    }
294                    exceptionListener = listener;
295            }
296    
297            /** Sets the owner object which can be accessed from the parsed XML data.
298             * <p>See the description of {@link XMLDecoder} class for more information on the owner object.</p>
299             *
300             * @param newOwner
301             */
302            public void setOwner(Object newOwner)
303            {
304                    owner = newOwner;
305            }
306    
307    }