| Prev Class | Next Class | Frames | No Frames |
| Summary: Nested | Field | Method | Constr | Detail: Nested | Field | Method | Constr |
java.lang.Objectjava.beans.XMLDecoderXMLEncoder 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.
Constructor Summary | |
| |
| |
| |
| |
Method Summary | |
void |
|
ExceptionListener |
|
Object |
|
Object |
|
void |
|
void | |
Methods inherited from class java.lang.Object | |
clone, equals, extends Object> getClass, finalize, hashCode, notify, notifyAll, toString, wait, wait, wait | |
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.
- Parameters:
in- InputStream to read XML data from.
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.
- Parameters:
in- InputStream to read XML data from.owner- Owner object which can be accessed and modified while parsing.
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.
- Parameters:
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.
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.
- Parameters:
in- InputStream to read XML data from.owner- Owner object which can be accessed and modified while parsing.listener- ExceptionListener instance to which exception notifications are send.cl- ClassLoader instance that is used for calls toClass.forName(String, boolean, ClassLoader)
- Since:
- 1.5
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 byclose.
- Specified by:
- close in interface AutoCloseable
public ExceptionListener getExceptionListener()
Returns the ExceptionListener instance associated with this decoder.See the description of
XMLDecoderclass for more information on the ExceptionListener.
- Returns:
- Current ExceptionListener of the decoder.
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
XMLDecoderclass for more information on the owner object.
- Returns:
- The owner object of this decoder.
public Object readObject() throws ArrayIndexOutOfBoundsException
Returns the next available decoded object.Note that the actual decoding takes place when the method is called for the first time.
If the
closemethod was already called aNoSuchElementExceptionis thrown.If the InputStream instance used in the constructors was
nullthis method will always returnnullitself.
- Returns:
- The next object in a sequence decoded from XML data.
- Throws:
ArrayIndexOutOfBoundsException- When no more objects are available.
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
XMLDecoderclass for more information on the ExceptionListener.
- Parameters:
listener-
public void setOwner(Object newOwner)
Sets the owner object which can be accessed from the parsed XML data.See the description of
XMLDecoderclass for more information on the owner object.
- Parameters:
newOwner-