classpath-patches
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[cp-patches] java.beans.XMLDecoder


From: Robert Schuster
Subject: [cp-patches] java.beans.XMLDecoder
Date: Sat, 16 Oct 2004 21:53:27 +0200
User-agent: Mozilla/5.0 (X11; U; Linux i686; de-AT; rv:1.7.3) Gecko/20040930

Hi there,
here is the implementation of java.beans.XMLDecoder and the classes it is based on.

changelog.diff: the changelog entry
decoder-helper-classes.tar.gz: classes that make the object parsing and decoding. all 37 files should go into gnu/java/beans/decoder
XMLDecoder.java: the public API itself which should go into java/beans

Documentation for the API is IMHO complete but I plan to cleanup and write more in gnu/java/beans/decoder itself to make understanding
for other developers easier.

Btw: (GNU) JAXP is needed to use this.

cu
Robert
Index: ChangeLog
===================================================================
RCS file: /cvsroot/classpath/classpath/ChangeLog,v
retrieving revision 1.2649
diff -u -r1.2649 ChangeLog
--- ChangeLog   16 Oct 2004 16:15:50 -0000      1.2649
+++ ChangeLog   16 Oct 2004 19:43:58 -0000
@@ -1,3 +1,47 @@
+2004-10-16  Robert Schuster <address@hidden>
+
+       * java/beans/XMLDecoder.java: new file, should
+       be feature and documentation complete
+
+       * gnu/java/beans/decoder/AbstractContext.java,
+       gnu/java/beans/decoder/AbstractCreatableObjectContext.java,
+       gnu/java/beans/decoder/AbstractElementHandler.java,
+       gnu/java/beans/decoder/AbstractObjectContext.java,
+       gnu/java/beans/decoder/ArrayContext.java,
+       gnu/java/beans/decoder/ArrayHandler.java,
+       gnu/java/beans/decoder/AssemblyException.java,
+       gnu/java/beans/decoder/BooleanHandler.java,
+       gnu/java/beans/decoder/ByteHandler.java,
+       gnu/java/beans/decoder/CharHandler.java,
+       gnu/java/beans/decoder/ClassHandler.java,
+       gnu/java/beans/decoder/ConstructorContext.java,
+       gnu/java/beans/decoder/Context.java,
+       gnu/java/beans/decoder/DecoderContext.java,
+       gnu/java/beans/decoder/DefaultExceptionListener.java,
+       gnu/java/beans/decoder/DoubleHandler.java,
+       gnu/java/beans/decoder/DummyContext.java,
+       gnu/java/beans/decoder/DummyHandler.java,
+       gnu/java/beans/decoder/ElementHandler.java,
+       gnu/java/beans/decoder/FloatHandler.java,
+       gnu/java/beans/decoder/GrowableArrayContext.java,
+       gnu/java/beans/decoder/IndexContext.java,
+       gnu/java/beans/decoder/IntHandler.java,
+       gnu/java/beans/decoder/JavaHandler.java,
+       gnu/java/beans/decoder/LongHandler.java,
+       gnu/java/beans/decoder/MethodContext.java,
+       gnu/java/beans/decoder/MethodFinder.java,
+       gnu/java/beans/decoder/NullHandler.java,
+       gnu/java/beans/decoder/ObjectContext.java,
+       gnu/java/beans/decoder/ObjectHandler.java,
+       gnu/java/beans/decoder/PersistenceParser.java,
+       gnu/java/beans/decoder/PropertyContext.java,
+       gnu/java/beans/decoder/ShortHandler.java,
+       gnu/java/beans/decoder/SimpleHandler.java,
+       gnu/java/beans/decoder/StaticMethodContext.java,
+       gnu/java/beans/decoder/StringHandler.java,
+       gnu/java/beans/decoder/VoidHandler.java:
+               helper classes for java.beans.XMLDecoder
+
 2004-10-16  Thomas Fitzsimmons  <address@hidden>
 
        * gnu/java/awt/peer/gtk/GtkButtonPeer.java,

Attachment: decoder-helper-classes.tar.gz
Description: GNU Zip compressed data

/*
java.beans.XMLDecoder

Copyright (C) 1998 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., 59 Temple Place, Suite 330, Boston, MA
02111-1307 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 java.io.IOException;
import java.io.InputStream;
import java.util.Iterator;
import java.util.NoSuchElementException;

import gnu.java.beans.decoder.DefaultExceptionListener;
import gnu.java.beans.decoder.PersistenceParser;
import gnu.java.beans.decoder.DecoderContext;

/** The XMLDecoder reads XML data that is structured according to
 * &lta 
href="http://java.sun.com/products/jfc/tsc/articles/persistence3/javabeans.dtd"&gtthis&lt/a&gt
 DTD
 * and creates objects according to the content. Usually such data is generated 
using the
 * address@hidden XMLEncoder} class.
 * <p>
 * An example XML document might look like this:
 * <code>
 * &ltjava&gt
 *      &ltstring&gtHello World&lt/string&gt
 *      &ltint&gt200&lt/int&gt
 * &lt/java&gt
 * </code
 * To read the <code>String</code> and the <code>Integer</code> instance the 
following can be used (assume
 * the XML data can be obtained from the InputStream):
 * <code>
 * XMLDecoder decoder = new XMLDecoder(inputStreamContainingXMLData);
 * String message = (String) decoder.readObject();
 * Integer number = (Integer) decoder.readObject();
 * </code>
 * <p>
 * Besides this basic functionality the <code>XMLDecoder</code> has some more 
features that might come
 * handy in certain situations:
 * <p>
 * An owner object can be set using the <code>setOwner</code> 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):
 * <code> 
 * &ltjava&gt
 *      &ltvoid method="getOwner"&gt
 *              &ltvoid method="setVisible"&gt
 *                      &ltboolean&gttrue&ltboolean&gt
 *              &lt/void&gt
 *  &lt/void&gt
 * &lt/java&gt
 * </code>
 * This accesses the <code>JFrame</code> and makes it visible using the 
<code>setVisible</code> method.
 * <p>
 * Please note that changing the owner <b>after</b> the having read the first 
object has no effect,
 * because all object have been decoded then.
 * <p>  
 * If the <code>XMLDecoder</code> is created with no address@hidden 
ExceptionListener} instance a default one
 * is used that prints an error message to <code>System.err</code> 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
 * <code>XMLDecoder</code> provoked such exceptions because the resulting 
object(s) may be in an
 * undesirable state.
 * Note that changing the ExceptionListener instance after 
<code>readObject</code> has been called
 * once has no effect because the decoding is completed then.
 * <p>
 * At last one can provide a certain <code>ClassLoader</code> which is used 
when <code>Class</code>
 * objects are accessed. See address@hidden java.lang.Class#forName(String, 
boolean, ClassLoader)} for details
 * on this.
 * <p>
 * Note: If the <code>InputStream</code> instance given to any of the 
constructors is <code>null</code>
 * the resulting <code>XMLDecoder</code> will be silently (without any 
exception) useless. Each call
 * to <code>readObject</code> will return <code>null</code> and never throws an
 * <code>ArrayIndexOutOfBoundsException</code>.
 *  
 * @author Robert Schuster
 */
public class XMLDecoder
{

        private Object owner;

        private ExceptionListener exceptionListener;

        private InputStream inputStream;

        private boolean isStreamClosed;

        private DecoderContext decoderContext = new DecoderContext(this);

        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 exceptionListener ExceptionListener instance to which 
exception notifications are send.
         * @param cl ClassLoader instance that is used for calls to 
<code>Class.forName(String, boolean, ClassLoader)</code>
         */
        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.
         * <p>
         * See the description of the address@hidden #readObject()} for the 
effect caused by <code>close</code>. 
         */
        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.
         * <p>
         * See the description of address@hidden 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.
         * <p>
         * See the description of address@hidden 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.
         * <p>
         * Note that the actual decoding takes place when the method is called 
for the first time.
         * <p>
         * If the <code>close</code> method was already called a 
<code>NoSuchElementException</code>
         * is thrown.
         * <p>
         * If the InputStream instance used in the constructors was 
<code>null</code> this method
         * will always return <code>null</code> 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.
         * <p> 
         * See the description of address@hidden 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 = new DefaultExceptionListener();
                }
                exceptionListener = listener;
        }

        /** Sets the owner object which can be accessed from the parsed XML 
data.
         * <p>
         * See the description of address@hidden XMLDecoder} class for more 
information on the owner object.
         * 
         * @param newOwner
         */
        public void setOwner(Object newOwner)
        {
                owner = newOwner;
        }

}

reply via email to

[Prev in Thread] Current Thread [Next in Thread]