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.
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.