java.beans
Class XMLDecoder
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
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
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
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.
clone, equals, extends Object> getClass, finalize, hashCode, notify, notifyAll, toString, wait, wait, wait |
XMLDecoder
public XMLDecoder(InputStream in)
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.
in - InputStream to read XML data from.
XMLDecoder
public XMLDecoder(InputStream in,
Object owner)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.
in - InputStream to read XML data from.owner - Owner object which can be accessed and modified while parsing.
XMLDecoder
public XMLDecoder(InputStream in,
Object owner,
ExceptionListener exceptionListener)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.
in - InputStream to read XML data from.owner - Owner object which can be accessed and modified while parsing.exceptionListener - ExceptionListener instance to which exception notifications are send.
XMLDecoder
public XMLDecoder(InputStream in,
Object owner,
ExceptionListener listener,
ClassLoader cl)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.
in - InputStream to read XML data from.owner - Owner object which can be accessed and modified while parsing.cl - ClassLoader instance that is used for calls to Class.forName(String, boolean, ClassLoader)
close
public void close()
Closes the stream associated with this decoder. This should be done after having read all
decoded objects.
See the description of the
readObject() for the effect caused by
close.
getExceptionListener
public ExceptionListener getExceptionListener()
Returns the ExceptionListener instance associated with this decoder.
See the description of
XMLDecoder class for more information on the ExceptionListener.
- Current ExceptionListener of the decoder.
getOwner
public Object getOwner()
Returns the owner object of the decoder. This method is usually called
from within the parsed XML data.
See the description of
XMLDecoder class for more information on the owner object.
- The owner object of this decoder.
readObject
public Object readObject()
throws ArrayIndexOutOfBoundsExceptionReturns 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.
- The next object in a sequence decoded from XML data.
setExceptionListener
public void setExceptionListener(ExceptionListener listener)
Sets the ExceptionListener instance to which notifications of exceptions are send
while parsing the XML data.
See the description of
XMLDecoder class for more information on the ExceptionListener.
setOwner
public void setOwner(Object newOwner)
Sets the owner object which can be accessed from the parsed XML data.
See the description of
XMLDecoder class for more information on the owner object.
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.