libjava/classpath/java/beans/XMLDecoder.java

   1 /* java.beans.XMLDecoder --
   2    Copyright (C) 2004, 2005, 2006  Free Software Foundation, Inc.
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpath is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2, or (at your option)
   9 any later version.
  10
  11 GNU Classpath is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Classpath; see the file COPYING.  If not, write to the
  18 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  19 02110-1301 USA.
  20
  21 Linking this library statically or dynamically with other modules is
  22 making a combined work based on this library.  Thus, the terms and
  23 conditions of the GNU General Public License cover the whole
  24 combination.
  25
  26 As a special exception, the copyright holders of this library give you
  27 permission to link this library with independent modules to produce an
  28 executable, regardless of the license terms of these independent
  29 modules, and to copy and distribute the resulting executable under
  30 terms of your choice, provided that you also meet, for each linked
  31 independent module, the terms and conditions of the license of that
  32 module.  An independent module is a module which is not derived from
  33 or based on this library.  If you modify this library, you may extend
  34 this exception to your version of the library, but you are not
  35 obligated to do so.  If you do not wish to do so, delete this
  36 exception statement from your version. */
  37
  38
  39 package java.beans;
  40
  41 import gnu.java.beans.DefaultExceptionListener;
  42 import gnu.java.beans.decoder.PersistenceParser;
  43
  44 import java.io.IOException;
  45 import java.io.InputStream;
  46 import java.util.Iterator;
  47 import java.util.NoSuchElementException;
  48
  49 /**
  50  * The XMLDecoder reads XML data that is structured according to
  51  * <a href="http://java.sun.com/products/jfc/tsc/articles/persistence3/javabeans.dtd">this</a> DTD
  52  * and creates objects according to the content. Usually such data is generated using the
  53  * {@link XMLEncoder} class.
  54  * <p>
  55  * An example XML document might look like this:
  56  * <code>
  57  * &lt;java&gt;
  58  *      &lt;string&gt;Hello World&lt;/string&gt;
  59  *      &lt;int&gt;200&lt;/int&gt;
  60  * &lt;/java&gt;
  61  * </code>
  62  * <p>To read the <code>String</code> and the <code>Integer</code> instance the following can be used (assume
  63  * the XML data can be obtained from the InputStream):</p>
  64  * <code>
  65  * XMLDecoder decoder = new XMLDecoder(inputStreamContainingXMLData);
  66  * String message = (String) decoder.readObject();
  67  * Integer number = (Integer) decoder.readObject();
  68  * </code>
  69  * <p>Besides this basic functionality the <code>XMLDecoder</code> has some more features that might come
  70  * handy in certain situations:</p>
  71  * <p>An owner object can be set using the <code>setOwner</code> method which can then be accessed when
  72  * decoding. This feature is only useful if the XML data is aware of the owner object. Such data may
  73  * look like this (assume that the owner object is a JFrame instance):</p>
  74  * <code>
  75  * &lt;java&gt;
  76  *      &lt;void method="getOwner"&gt;
  77  *              &lt;void method="setVisible"&gt;
  78  *                      &lt;boolean&gt;true&lt;boolean&gt;
  79  *              &lt;/void&gt;
  80  *  &lt;/void&gt;
  81  * &lt;/java&gt;
  82  * </code>
  83  * This accesses the <code>JFrame</code> and makes it visible using the <code>setVisible</code> method.
  84  * <p>Please note that changing the owner <b>after</b> the having read the first object has no effect,
  85  * because all object have been decoded then.</p>
  86  * <p>If the <code>XMLDecoder</code> is created with no {@link ExceptionListener} instance a default one
  87  * is used that prints an error message to <code>System.err</code> whenever a recoverable exception
  88  * is thrown. Recovarable exceptions occur when the XML data cannot be interpreted correctly (e.g
  89  * unknown classes or methods, invocation on null, ...). In general be very careful when the
  90  * <code>XMLDecoder</code> provoked such exceptions because the resulting object(s) may be in an
  91  * undesirable state.</p>
  92  * <p>Note that changing the ExceptionListener instance after <code>readObject</code> has been called
  93  * once has no effect because the decoding is completed then.</p>
  94  * <p>At last one can provide a specific <code>ClassLoader</code> which is then used when <code>Class</code>
  95  * objects are accessed. See {@link java.lang.Class#forName(String, boolean, ClassLoader)} for details
  96  * on this.</p>
  97  * <p>Note: If the <code>InputStream</code> instance given to any of the constructors is <code>null</code>
  98  * the resulting <code>XMLDecoder</code> will be silently (without any exception) useless. Each call
  99  * 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   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 }