/* java.beans.XMLDecoder -- Copyright (C) 2004, 2005, 2006 Free Software Foundation, Inc. This file is part of GNU Classpath. GNU Classpath is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version. GNU Classpath is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with GNU Classpath; see the file COPYING. If not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. Linking this library statically or dynamically with other modules is making a combined work based on this library. Thus, the terms and conditions of the GNU General Public License cover the whole combination. As a special exception, the copyright holders of this library give you permission to link this library with independent modules to produce an executable, regardless of the license terms of these independent modules, and to copy and distribute the resulting executable under terms of your choice, provided that you also meet, for each linked independent module, the terms and conditions of the license of that module. An independent module is a module which is not derived from or based on this library. If you modify this library, you may extend this exception to your version of the library, but you are not obligated to do so. If you do not wish to do so, delete this exception statement from your version. */ package java.beans; import gnu.java.beans.DefaultExceptionListener; import gnu.java.beans.decoder.PersistenceParser; import java.io.IOException; import java.io.InputStream; import java.util.Iterator; import java.util.NoSuchElementException; /** * The XMLDecoder reads XML data that is structured according to * this DTD * and creates objects according to the content. Usually such data is generated using the * {@link XMLEncoder} class. *

* An example XML document might look like this: * * <java> * <string>Hello World</string> * <int>200</int> * </java> * *

To read the String and the Integer instance the following can be used (assume * the XML data can be obtained from the InputStream):

* * XMLDecoder decoder = new XMLDecoder(inputStreamContainingXMLData); * String message = (String) decoder.readObject(); * Integer number = (Integer) decoder.readObject(); * *

Besides this basic functionality the XMLDecoder has some more features that might come * handy in certain situations:

*

An owner object can be set using the setOwner method which can then be accessed when * decoding. This feature is only useful if the XML data is aware of the owner object. Such data may * look like this (assume that the owner object is a JFrame instance):

* * <java> * <void method="getOwner"> * <void method="setVisible"> * <boolean>true<boolean> * </void> * </void> * </java> * * This accesses the JFrame and makes it visible using the setVisible method. *

Please note that changing the owner after the having read the first object has no effect, * because all object have been decoded then.

*

If the XMLDecoder is created with no {@link ExceptionListener} instance a default one * is used that prints an error message to System.err whenever a recoverable exception * is thrown. Recovarable exceptions occur when the XML data cannot be interpreted correctly (e.g * unknown classes or methods, invocation on null, ...). In general be very careful when the * XMLDecoder provoked such exceptions because the resulting object(s) may be in an * undesirable state.

*

Note that changing the ExceptionListener instance after readObject has been called * once has no effect because the decoding is completed then.

*

At last one can provide a specific ClassLoader which is then used when Class * objects are accessed. See {@link java.lang.Class#forName(String, boolean, ClassLoader)} for details * on this.

*

Note: If the InputStream instance given to any of the constructors is null * the resulting XMLDecoder will be silently (without any exception) useless. Each call * to readObject will return null and never throws an * ArrayIndexOutOfBoundsException.

* * @author Robert Schuster * @since 1.4 * @status updated to 1.5 */ public class XMLDecoder { private Object owner; private ExceptionListener exceptionListener; private InputStream inputStream; private boolean isStreamClosed; private ClassLoader classLoader; private Iterator iterator; /** Creates a XMLDecoder instance that parses the XML data of the given input stream. * Using this constructor no special ClassLoader, a default ExceptionListener * and no owner object is used. * * @param in InputStream to read XML data from. */ public XMLDecoder(InputStream in) { this(in, null); } /** Creates a XMLDecoder instance that parses the XML data of the given input stream. * Using this constructor no special ClassLoader and a default ExceptionListener * is used. * * @param in InputStream to read XML data from. * @param owner Owner object which can be accessed and modified while parsing. */ public XMLDecoder(InputStream in, Object owner) { this(in, owner, null); } /** Creates a XMLDecoder instance that parses the XML data of the given input stream. * If the ExceptionListener argument is null a default implementation is used. * * @param in InputStream to read XML data from. * @param owner Owner object which can be accessed and modified while parsing. * @param exceptionListener ExceptionListener instance to which exception notifications are send. */ public XMLDecoder( InputStream in, Object owner, ExceptionListener exceptionListener) { this( in, owner, exceptionListener, Thread.currentThread().getContextClassLoader()); } /** Creates a XMLDecoder instance that parses the XML data of the given input stream. * If the ExceptionListener argument is null a default implementation is used. * * @param in InputStream to read XML data from. * @param owner Owner object which can be accessed and modified while parsing. * @param listener ExceptionListener instance to which exception notifications are send. * @param cl ClassLoader instance that is used for calls to Class.forName(String, boolean, ClassLoader) * @since 1.5 */ public XMLDecoder( InputStream in, Object owner, ExceptionListener listener, ClassLoader cl) { // initially here was a check for the validity of the InputStream argument but some // great engineers decided that this API should silently discard this and behave rather // odd: readObject will always return null ... inputStream = in; setExceptionListener(listener); // validity of this object is checked in Class.forName() and therefore may be null classLoader = cl; this.owner = owner; } /** Closes the stream associated with this decoder. This should be done after having read all * decoded objects. *

See the description of the {@link #readObject()} for the effect caused by close.

*/ public void close() { if (isStreamClosed) { return; } try { inputStream.close(); isStreamClosed = true; } catch (IOException e) { // bad style forced by original API design ... } } /** Returns the ExceptionListener instance associated with this decoder. *

See the description of {@link XMLDecoder} class for more information on the ExceptionListener.

* * @return Current ExceptionListener of the decoder. */ public ExceptionListener getExceptionListener() { return exceptionListener; } /** Returns the owner object of the decoder. This method is usually called * from within the parsed XML data. *

See the description of {@link XMLDecoder} class for more information on the owner object.

* * @return The owner object of this decoder. */ public Object getOwner() { return owner; } /** Returns the next available decoded object. *

Note that the actual decoding takes place when the method is called for the first time.

*

If the close method was already called a NoSuchElementException * is thrown.

*

If the InputStream instance used in the constructors was null this method * will always return null itself.

* * @return The next object in a sequence decoded from XML data. * @throws ArrayIndexOutOfBoundsException When no more objects are available. */ public Object readObject() throws ArrayIndexOutOfBoundsException { // note: the RI does it this way ... if(inputStream == null) { return null; } // note: the original API documentation says nothing on what to do // when the stream was closed before readObject is called but it actually // throws a NoSuchElementException - this behaviour is imitated here if (isStreamClosed) { throw new NoSuchElementException("Cannot read any objects - XMLDecoder was already closed."); } // creates the PersistenceParser (doing the parsing and decoding) and returns its // Iterator on first invocation if (iterator == null) { iterator = new PersistenceParser( inputStream, exceptionListener, classLoader, this) .iterator(); } // note: done according to the official documentation if (!iterator.hasNext()) { throw new ArrayIndexOutOfBoundsException("No more objects available from this XMLDecoder."); } // returns just the next object if there was no problem return iterator.next(); } /** Sets the ExceptionListener instance to which notifications of exceptions are send * while parsing the XML data. *

See the description of {@link XMLDecoder} class for more information on the ExceptionListener.

* * @param listener */ public void setExceptionListener(ExceptionListener listener) { // uses a default implementation when null if (listener == null) { listener = DefaultExceptionListener.INSTANCE; } exceptionListener = listener; } /** Sets the owner object which can be accessed from the parsed XML data. *

See the description of {@link XMLDecoder} class for more information on the owner object.

* * @param newOwner */ public void setOwner(Object newOwner) { owner = newOwner; } }