JavaTM 2 Platform
Standard Ed. 5.0

java.beans
Class XMLEncoder

java.lang.Object
  extended by java.beans.Encoder
      extended by java.beans.XMLEncoder

public class XMLEncoder
extends Encoder

The XMLEncoder class is a complementary alternative to the ObjectOutputStream and can used to generate a textual representation of a JavaBean in the same way that the ObjectOutputStream can be used to create binary representation of Serializable objects. For example, the following fragment can be used to create a textual representation the supplied JavaBean and all its properties:

       XMLEncoder e = new XMLEncoder(
                          new BufferedOutputStream(
                              new FileOutputStream("Test.xml")));
       e.writeObject(new JButton("Hello, world"));
       e.close();
 
Despite the similarity of their APIs, the XMLEncoder class is exclusively designed for the purpose of archiving graphs of JavaBeans as textual representations of their public properties. Like Java source files, documents written this way have a natural immunity to changes in the implementations of the classes involved. The ObjectOutputStream continues to be recommended for interprocess communication and general purpose serialization.

The XMLEncoder class provides a default denotation for JavaBeans in which they are represented as XML documents complying with version 1.0 of the XML specification and the UTF-8 character encoding of the Unicode/ISO 10646 character set. The XML documents produced by the XMLEncoder class are:

Below is an example of an XML archive containing some user interface components from the swing toolkit:

 <?xml version="1.0" encoding="UTF-8"?>
 <java version="1.0" class="java.beans.XMLDecoder">
 <object class="javax.swing.JFrame">
   <void property="name">
     <string>frame1</string>
   </void>
   <void property="bounds">
     <object class="java.awt.Rectangle">
       <int>0</int>
       <int>0</int>
       <int>200</int>
       <int>200</int>
     </object>
   </void>
   <void property="contentPane">
     <void method="add">
       <object class="javax.swing.JButton">
         <void property="label">
           <string>Hello</string>
         </void>
       </object>
     </void>
   </void>
   <void property="visible">
     <boolean>true</boolean>
   </void>
 </object>
 </java>
 
The XML syntax uses the following conventions:

Although all object graphs may be written using just these three tags, the following definitions are included so that common data structures can be expressed more concisely:

For more information you might also want to check out Using XMLEncoder, an article in The Swing Connection.

Since:
1.4
See Also:
XMLDecoder, ObjectOutputStream

Constructor Summary
XMLEncoder(OutputStream out)
          Creates a new output stream for sending JavaBeans to the stream out using an XML encoding.
 
Method Summary
 void close()
          This method calls flush, writes the closing postamble and then closes the output stream associated with this stream.
 void flush()
          This method writes out the preamble associated with the XML encoding if it has not been written already and then writes out all of the values that been written to the stream since the last time flush was called.
 Object getOwner()
          Gets the owner of this encoder.
 void setOwner(Object owner)
          Sets the owner of this encoder to owner.
 void writeExpression(Expression oldExp)
          Records the Expression so that the Encoder will produce the actual output when the stream is flushed.
 void writeObject(Object o)
          Write an XML representation of the specified object to the output.
 void writeStatement(Statement oldStm)
          Records the Statement so that the Encoder will produce the actual output when the stream is flushed.
 
Methods inherited from class java.beans.Encoder
get, getExceptionListener, getPersistenceDelegate, remove, setExceptionListener, setPersistenceDelegate
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

XMLEncoder

public XMLEncoder(OutputStream out)
Creates a new output stream for sending JavaBeans to the stream out using an XML encoding.

Parameters:
out - The stream to which the XML representation of the objects will be sent.
See Also:
XMLDecoder.XMLDecoder(InputStream)
Method Detail

setOwner

public void setOwner(Object owner)
Sets the owner of this encoder to owner.

Parameters:
owner - The owner of this encoder.
See Also:
getOwner()

getOwner

public Object getOwner()
Gets the owner of this encoder.

Returns:
The owner of this encoder.
See Also:
setOwner(java.lang.Object)

writeObject

public void writeObject(Object o)
Write an XML representation of the specified object to the output.

Overrides:
writeObject in class Encoder
Parameters:
o - The object to be written to the stream.
See Also:
XMLDecoder.readObject()

writeStatement

public void writeStatement(Statement oldStm)
Records the Statement so that the Encoder will produce the actual output when the stream is flushed.

This method should only be invoked within the context of initializing a persistence delegate.

Overrides:
writeStatement in class Encoder
Parameters:
oldStm - The statement that will be written to the stream.
See Also:
PersistenceDelegate.initialize(java.lang.Class, java.lang.Object, java.lang.Object, java.beans.Encoder)

writeExpression

public void writeExpression(Expression oldExp)
Records the Expression so that the Encoder will produce the actual output when the stream is flushed.

This method should only be invoked within the context of initializing a persistence delegate or setting up an encoder to read from a resource bundle.

For more information about using resource bundles with the XMLEncoder, see http://java.sun.com/products/jfc/tsc/articles/persistence4/#i18n

Overrides:
writeExpression in class Encoder
Parameters:
oldExp - The expression that will be written to the stream.
See Also:
PersistenceDelegate.initialize(java.lang.Class, java.lang.Object, java.lang.Object, java.beans.Encoder)

flush

public void flush()
This method writes out the preamble associated with the XML encoding if it has not been written already and then writes out all of the values that been written to the stream since the last time flush was called. After flushing, all internal references to the values that were written to this stream are cleared.


close

public void close()
This method calls flush, writes the closing postamble and then closes the output stream associated with this stream.


JavaTM 2 Platform
Standard Ed. 5.0

Submit a bug or feature
For further API reference and developer documentation, see Java 2 SDK SE Developer Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.

Copyright 2004 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms. Also see the documentation redistribution policy.