[Top][All Lists]
[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,
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
* <a
href="http://java.sun.com/products/jfc/tsc/articles/persistence3/javabeans.dtd">this</a>
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>
* <java>
* <string>Hello World</string>
* <int>200</int>
* </java>
* </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>
* <java>
* <void method="getOwner">
* <void method="setVisible">
* <boolean>true<boolean>
* </void>
* </void>
* </java>
* </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;
}
}
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [cp-patches] java.beans.XMLDecoder,
Robert Schuster <=