001/* java.beans.XMLDecoder --
002   Copyright (C) 2004, 2005, 2006  Free Software Foundation, Inc.
003
004This file is part of GNU Classpath.
005
006GNU Classpath is free software; you can redistribute it and/or modify
007it under the terms of the GNU General Public License as published by
008the Free Software Foundation; either version 2, or (at your option)
009any later version.
010
011GNU Classpath is distributed in the hope that it will be useful, but
012WITHOUT ANY WARRANTY; without even the implied warranty of
013MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014General Public License for more details.
015
016You should have received a copy of the GNU General Public License
017along with GNU Classpath; see the file COPYING.  If not, write to the
018Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
01902110-1301 USA.
020
021Linking this library statically or dynamically with other modules is
022making a combined work based on this library.  Thus, the terms and
023conditions of the GNU General Public License cover the whole
024combination.
025
026As a special exception, the copyright holders of this library give you
027permission to link this library with independent modules to produce an
028executable, regardless of the license terms of these independent
029modules, and to copy and distribute the resulting executable under
030terms of your choice, provided that you also meet, for each linked
031independent module, the terms and conditions of the license of that
032module.  An independent module is a module which is not derived from
033or based on this library.  If you modify this library, you may extend
034this exception to your version of the library, but you are not
035obligated to do so.  If you do not wish to do so, delete this
036exception statement from your version. */
037
038
039package java.beans;
040
041import gnu.java.beans.DefaultExceptionListener;
042import gnu.java.beans.decoder.PersistenceParser;
043
044import java.io.IOException;
045import java.io.InputStream;
046import java.util.Iterator;
047import 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 */
106public class XMLDecoder
107  implements AutoCloseable
108{
109        private Object owner;
110
111        private ExceptionListener exceptionListener;
112
113        private InputStream inputStream;
114
115        private boolean isStreamClosed;
116
117        private ClassLoader classLoader;
118
119        private Iterator iterator;
120
121        /** Creates a XMLDecoder instance that parses the XML data of the given input stream.
122         * Using this constructor no special ClassLoader, a default ExceptionListener
123         * and no owner object is used.
124         *
125         * @param in InputStream to read XML data from.
126         */
127        public XMLDecoder(InputStream in)
128        {
129                this(in, null);
130        }
131
132        /** Creates a XMLDecoder instance that parses the XML data of the given input stream.
133         * Using this constructor no special ClassLoader and a default ExceptionListener
134         * is used.
135         *
136         * @param in InputStream to read XML data from.
137         * @param owner Owner object which can be accessed and modified while parsing.
138         */
139        public XMLDecoder(InputStream in, Object owner)
140        {
141                this(in, owner, null);
142        }
143
144        /** Creates a XMLDecoder instance that parses the XML data of the given input stream.
145         * If the ExceptionListener argument is null a default implementation is used.
146         *
147         * @param in InputStream to read XML data from.
148         * @param owner Owner object which can be accessed and modified while parsing.
149         * @param exceptionListener ExceptionListener instance to which exception notifications are send.
150         */
151        public XMLDecoder(
152                InputStream in,
153                Object owner,
154                ExceptionListener exceptionListener)
155        {
156                this(
157                        in,
158                        owner,
159                        exceptionListener,
160                        Thread.currentThread().getContextClassLoader());
161        }
162
163        /** Creates a XMLDecoder instance that parses the XML data of the given input stream.
164         * If the ExceptionListener argument is null a default implementation is used.
165         *
166         * @param in InputStream to read XML data from.
167         * @param owner Owner object which can be accessed and modified while parsing.
168         * @param listener ExceptionListener instance to which exception notifications are send.
169         * @param cl ClassLoader instance that is used for calls to <code>Class.forName(String, boolean, ClassLoader)</code>
170         * @since 1.5
171         */
172        public XMLDecoder(
173                InputStream in,
174                Object owner,
175                ExceptionListener listener,
176                ClassLoader cl)
177        {
178                // initially here was a check for the validity of the InputStream argument but some
179                // great engineers decided that this API should silently discard this and behave rather
180                // odd: readObject will always return null ...
181                inputStream = in;
182
183                setExceptionListener(listener);
184
185                // validity of this object is checked in Class.forName() and therefore may be null
186                classLoader = cl;
187
188                this.owner = owner;
189        }
190
191        /** Closes the stream associated with this decoder. This should be done after having read all
192         * decoded objects.
193         * <p>See the description of the {@link #readObject()} for the effect caused by <code>close</code>.</p>
194         */
195        public void close()
196        {
197                if (isStreamClosed)
198                {
199                        return;
200                }
201
202                try
203                {
204                        inputStream.close();
205                        isStreamClosed = true;
206                }
207                catch (IOException e)
208                {
209                        // bad style forced by original API design ...
210                }
211        }
212
213        /** Returns the ExceptionListener instance associated with this decoder.
214         * <p>See the description of {@link XMLDecoder} class for more information on the ExceptionListener.</p>
215         *
216         * @return Current ExceptionListener of the decoder.
217         */
218        public ExceptionListener getExceptionListener()
219        {
220                return exceptionListener;
221        }
222
223        /** Returns the owner object of the decoder. This method is usually called
224         * from within the parsed XML data.
225         * <p>See the description of {@link XMLDecoder} class for more information on the owner object.</p>
226         *
227         * @return The owner object of this decoder.
228         */
229        public Object getOwner()
230        {
231                return owner;
232        }
233
234        /** Returns the next available decoded object.
235         * <p>Note that the actual decoding takes place when the method is called for the first time.</p>
236         * <p>If the <code>close</code> method was already called a <code>NoSuchElementException</code>
237         * is thrown.</p>
238         * <p>If the InputStream instance used in the constructors was <code>null</code> this method
239         * will always return <code>null</code> itself.</p>
240         *
241         * @return The next object in a sequence decoded from XML data.
242         * @throws ArrayIndexOutOfBoundsException When no more objects are available.
243         */
244        public Object readObject() throws ArrayIndexOutOfBoundsException
245        {
246                // note: the RI does it this way ...
247                if(inputStream == null) {
248                        return null;
249                }
250
251                // note: the original API documentation says nothing on what to do
252                // when the stream was closed before readObject is called but it actually
253                // throws a NoSuchElementException - this behaviour is imitated here
254                if (isStreamClosed)
255                {
256                        throw new NoSuchElementException("Cannot read any objects - XMLDecoder was already closed.");
257                }
258
259                // creates the PersistenceParser (doing the parsing and decoding) and returns its
260                // Iterator on first invocation
261                if (iterator == null)
262                {
263                        iterator =
264                                new PersistenceParser(
265                                        inputStream,
266                                        exceptionListener,
267                                        classLoader,
268                                        this)
269                                        .iterator();
270                }
271
272                // note: done according to the official documentation
273                if (!iterator.hasNext())
274                {
275                        throw new ArrayIndexOutOfBoundsException("No more objects available from this XMLDecoder.");
276                }
277
278                // returns just the next object if there was no problem
279                return iterator.next();
280        }
281
282        /** Sets the ExceptionListener instance to which notifications of exceptions are send
283         * while parsing the XML data.
284         * <p>See the description of {@link XMLDecoder} class for more information on the ExceptionListener.</p>
285         *
286         * @param listener
287         */
288        public void setExceptionListener(ExceptionListener listener)
289        {
290                // uses a default implementation when null
291                if (listener == null)
292                {
293                        listener = DefaultExceptionListener.INSTANCE;
294                }
295                exceptionListener = listener;
296        }
297
298        /** Sets the owner object which can be accessed from the parsed XML data.
299         * <p>See the description of {@link XMLDecoder} class for more information on the owner object.</p>
300         *
301         * @param newOwner
302         */
303        public void setOwner(Object newOwner)
304        {
305                owner = newOwner;
306        }
307
308}