< prev index next >
src/java.desktop/share/classes/java/beans/XMLEncoder.java
Print this page
*** 31,77 ****
import java.nio.charset.CharsetEncoder;
import java.nio.charset.IllegalCharsetNameException;
import java.nio.charset.UnsupportedCharsetException;
/**
! * The <code>XMLEncoder</code> class is a complementary alternative to
! * the <code>ObjectOutputStream</code> and can used to generate
* a textual representation of a <em>JavaBean</em> in the same
! * way that the <code>ObjectOutputStream</code> can
! * be used to create binary representation of <code>Serializable</code>
* objects. For example, the following fragment can be used to create
* a textual representation the supplied <em>JavaBean</em>
* and all its properties:
* <pre>
* XMLEncoder e = new XMLEncoder(
* new BufferedOutputStream(
* new FileOutputStream("Test.xml")));
* e.writeObject(new JButton("Hello, world"));
* e.close();
* </pre>
! * Despite the similarity of their APIs, the <code>XMLEncoder</code>
* class is exclusively designed for the purpose of archiving graphs
* of <em>JavaBean</em>s 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 <code>ObjectOutputStream</code> continues to be recommended
* for interprocess communication and general purpose serialization.
* <p>
! * The <code>XMLEncoder</code> class provides a default denotation for
* <em>JavaBean</em>s 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 <code>XMLEncoder</code> class are:
* <ul>
* <li>
* <em>Portable and version resilient</em>: they have no dependencies
* on the private implementation of any class and so, like Java source
* files, they may be exchanged between environments which may have
* different versions of some of the classes and between VMs from
* different vendors.
* <li>
! * <em>Structurally compact</em>: The <code>XMLEncoder</code> class
* uses a <em>redundancy elimination</em> algorithm internally so that the
* default values of a Bean's properties are not written to the stream.
* <li>
* <em>Fault tolerant</em>: Non-structural errors in the file,
* caused either by damage to the file or by API changes
--- 31,77 ----
import java.nio.charset.CharsetEncoder;
import java.nio.charset.IllegalCharsetNameException;
import java.nio.charset.UnsupportedCharsetException;
/**
! * The {@code XMLEncoder} class is a complementary alternative to
! * the {@code ObjectOutputStream} and can used to generate
* a textual representation of a <em>JavaBean</em> in the same
! * way that the {@code ObjectOutputStream} can
! * be used to create binary representation of {@code Serializable}
* objects. For example, the following fragment can be used to create
* a textual representation the supplied <em>JavaBean</em>
* and all its properties:
* <pre>
* XMLEncoder e = new XMLEncoder(
* new BufferedOutputStream(
* new FileOutputStream("Test.xml")));
* e.writeObject(new JButton("Hello, world"));
* e.close();
* </pre>
! * Despite the similarity of their APIs, the {@code XMLEncoder}
* class is exclusively designed for the purpose of archiving graphs
* of <em>JavaBean</em>s 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 {@code ObjectOutputStream} continues to be recommended
* for interprocess communication and general purpose serialization.
* <p>
! * The {@code XMLEncoder} class provides a default denotation for
* <em>JavaBean</em>s 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 {@code XMLEncoder} class are:
* <ul>
* <li>
* <em>Portable and version resilient</em>: they have no dependencies
* on the private implementation of any class and so, like Java source
* files, they may be exchanged between environments which may have
* different versions of some of the classes and between VMs from
* different vendors.
* <li>
! * <em>Structurally compact</em>: The {@code XMLEncoder} class
* uses a <em>redundancy elimination</em> algorithm internally so that the
* default values of a Bean's properties are not written to the stream.
* <li>
* <em>Fault tolerant</em>: Non-structural errors in the file,
* caused either by damage to the file or by API changes
*** 157,172 ****
* A reference to a java class is written in the form
* <class>javax.swing.JButton</class>.
* <li>
* Instances of the wrapper classes for Java's primitive types are written
* using the name of the primitive type as the tag. For example, an
! * instance of the <code>Integer</code> class could be written:
! * <int>123</int>. Note that the <code>XMLEncoder</code> class
* uses Java's reflection package in which the conversion between
* Java's primitive types and their associated "wrapper classes"
! * is handled internally. The API for the <code>XMLEncoder</code> class
! * itself deals only with <code>Object</code>s.
* <li>
* In an element representing a nullary method whose name
* starts with "get", the "method" attribute is replaced
* with a "property" attribute whose value is given by removing
* the "get" prefix and decapitalizing the result.
--- 157,172 ----
* A reference to a java class is written in the form
* <class>javax.swing.JButton</class>.
* <li>
* Instances of the wrapper classes for Java's primitive types are written
* using the name of the primitive type as the tag. For example, an
! * instance of the {@code Integer} class could be written:
! * <int>123</int>. Note that the {@code XMLEncoder} class
* uses Java's reflection package in which the conversion between
* Java's primitive types and their associated "wrapper classes"
! * is handled internally. The API for the {@code XMLEncoder} class
! * itself deals only with {@code Object}s.
* <li>
* In an element representing a nullary method whose name
* starts with "get", the "method" attribute is replaced
* with a "property" attribute whose value is given by removing
* the "get" prefix and decapitalizing the result.
*** 225,268 ****
public Expression exp = null;
}
/**
* Creates a new XML encoder to write out <em>JavaBeans</em>
! * to the stream <code>out</code> using an XML encoding.
*
* @param out the stream to which the XML representation of
* the objects will be written
*
* @throws IllegalArgumentException
! * if <code>out</code> is <code>null</code>
*
* @see XMLDecoder#XMLDecoder(InputStream)
*/
public XMLEncoder(OutputStream out) {
this(out, "UTF-8", true, 0);
}
/**
* Creates a new XML encoder to write out <em>JavaBeans</em>
! * to the stream <code>out</code> using the given <code>charset</code>
! * starting from the given <code>indentation</code>.
*
* @param out the stream to which the XML representation of
* the objects will be written
* @param charset the name of the requested charset;
* may be either a canonical name or an alias
* @param declaration whether the XML declaration should be generated;
! * set this to <code>false</code>
* when embedding the contents in another XML document
* @param indentation the number of space characters to indent the entire XML document by
*
* @throws IllegalArgumentException
! * if <code>out</code> or <code>charset</code> is <code>null</code>,
! * or if <code>indentation</code> is less than 0
*
* @throws IllegalCharsetNameException
! * if <code>charset</code> name is illegal
*
* @throws UnsupportedCharsetException
* if no support for the named charset is available
* in this instance of the Java virtual machine
*
--- 225,268 ----
public Expression exp = null;
}
/**
* Creates a new XML encoder to write out <em>JavaBeans</em>
! * to the stream {@code out} using an XML encoding.
*
* @param out the stream to which the XML representation of
* the objects will be written
*
* @throws IllegalArgumentException
! * if {@code out} is {@code null}
*
* @see XMLDecoder#XMLDecoder(InputStream)
*/
public XMLEncoder(OutputStream out) {
this(out, "UTF-8", true, 0);
}
/**
* Creates a new XML encoder to write out <em>JavaBeans</em>
! * to the stream {@code out} using the given {@code charset}
! * starting from the given {@code indentation}.
*
* @param out the stream to which the XML representation of
* the objects will be written
* @param charset the name of the requested charset;
* may be either a canonical name or an alias
* @param declaration whether the XML declaration should be generated;
! * set this to {@code false}
* when embedding the contents in another XML document
* @param indentation the number of space characters to indent the entire XML document by
*
* @throws IllegalArgumentException
! * if {@code out} or {@code charset} is {@code null},
! * or if {@code indentation} is less than 0
*
* @throws IllegalCharsetNameException
! * if {@code charset} name is illegal
*
* @throws UnsupportedCharsetException
* if no support for the named charset is available
* in this instance of the Java virtual machine
*
*** 290,300 ****
targetToStatementList = new IdentityHashMap<>();
nameGenerator = new NameGenerator();
}
/**
! * Sets the owner of this encoder to <code>owner</code>.
*
* @param owner The owner of this encoder.
*
* @see #getOwner
*/
--- 290,300 ----
targetToStatementList = new IdentityHashMap<>();
nameGenerator = new NameGenerator();
}
/**
! * Sets the owner of this encoder to {@code owner}.
*
* @param owner The owner of this encoder.
*
* @see #getOwner
*/
*** 457,467 ****
/**
* 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 <code>flush</code>
* was called. After flushing, all internal references to the
* values that were written to this stream are cleared.
*/
public void flush() {
if (!preambleWritten) { // Don't do this in constructor - it throws ... pending.
--- 457,467 ----
/**
* 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 {@code flush}
* was called. After flushing, all internal references to the
* values that were written to this stream are cleared.
*/
public void flush() {
if (!preambleWritten) { // Don't do this in constructor - it throws ... pending.
*** 519,529 ****
return null;
}
/**
! * This method calls <code>flush</code>, writes the closing
* postamble and then closes the output stream associated
* with this stream.
*/
public void close() {
flush();
--- 519,529 ----
return null;
}
/**
! * This method calls {@code flush}, writes the closing
* postamble and then closes the output stream associated
* with this stream.
*/
public void close() {
flush();
*** 548,574 ****
}
return d;
}
/**
! * Returns <code>true</code> if the argument,
* a Unicode code point, is valid in XML documents.
* Unicode characters fit into the low sixteen bits of a Unicode code point,
* and pairs of Unicode <em>surrogate characters</em> can be combined
* to encode Unicode code point in documents containing only Unicode.
! * (The <code>char</code> datatype in the Java Programming Language
* represents Unicode characters, including unpaired surrogates.)
* <par>
* [2] Char ::= #x0009 | #x000A | #x000D
* | [#x0020-#xD7FF]
* | [#xE000-#xFFFD]
* | [#x10000-#x10ffff]
* </par>
*
* @param code the 32-bit Unicode code point being tested
! * @return <code>true</code> if the Unicode code point is valid,
! * <code>false</code> otherwise
*/
private static boolean isValidCharCode(int code) {
return (0x0020 <= code && code <= 0xD7FF)
|| (0x000A == code)
|| (0x0009 == code)
--- 548,574 ----
}
return d;
}
/**
! * Returns {@code true} if the argument,
* a Unicode code point, is valid in XML documents.
* Unicode characters fit into the low sixteen bits of a Unicode code point,
* and pairs of Unicode <em>surrogate characters</em> can be combined
* to encode Unicode code point in documents containing only Unicode.
! * (The {@code char} datatype in the Java Programming Language
* represents Unicode characters, including unpaired surrogates.)
* <par>
* [2] Char ::= #x0009 | #x000A | #x000D
* | [#x0020-#xD7FF]
* | [#xE000-#xFFFD]
* | [#x10000-#x10ffff]
* </par>
*
* @param code the 32-bit Unicode code point being tested
! * @return {@code true} if the Unicode code point is valid,
! * {@code false} otherwise
*/
private static boolean isValidCharCode(int code) {
return (0x0020 <= code && code <= 0xD7FF)
|| (0x000A == code)
|| (0x0009 == code)
< prev index next >