/*
* Copyright (c) 2000, 2010, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code 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
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package java.beans;
import java.io.*;
import java.util.*;
import java.lang.reflect.*;
import java.nio.charset.Charset;
import java.nio.charset.CharsetEncoder;
import java.nio.charset.IllegalCharsetNameException;
import java.nio.charset.UnsupportedCharsetException;
/**
* 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:
*
*
* Portable and version resilient: 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.
*
* Structurally compact: The XMLEncoder class
* uses a redundancy elimination algorithm internally so that the
* default values of a Bean's properties are not written to the stream.
*
* Fault tolerant: Non-structural errors in the file,
* caused either by damage to the file or by API changes
* made to classes in an archive remain localized
* so that a reader can report the error and continue to load the parts
* of the document which were not affected by the error.
*
*
* Below is an example of an XML archive containing
* some user interface components from the swing toolkit:
*
* The XML syntax uses the following conventions:
*
*
* Each element represents a method call.
*
* The "object" tag denotes an expression whose value is
* to be used as the argument to the enclosing element.
*
* The "void" tag denotes a statement which will
* be executed, but whose result will not be used as an
* argument to the enclosing method.
*
* Elements which contain elements use those elements as arguments,
* unless they have the tag: "void".
*
* The name of the method is denoted by the "method" attribute.
*
* XML's standard "id" and "idref" attributes are used to make
* references to previous expressions - so as to deal with
* circularities in the object graph.
*
* The "class" attribute is used to specify the target of a static
* method or constructor explicitly; its value being the fully
* qualified name of the class.
*
* Elements with the "void" tag are executed using
* the outer context as the target if no target is defined
* by a "class" attribute.
*
* Java's String class is treated specially and is
* written <string>Hello, world</string> where
* the characters of the string are converted to bytes
* using the UTF-8 character encoding.
*
*
* 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:
*
*
*
* The default method name is "new".
*
* A reference to a java class is written in the form
* <class>javax.swing.JButton</class>.
*
* 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 Integer class could be written:
* <int>123</int>. Note that the 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 XMLEncoder class
* itself deals only with Objects.
*
* 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.
*
* In an element representing a monadic method whose name
* starts with "set", the "method" attribute is replaced
* with a "property" attribute whose value is given by removing
* the "set" prefix and decapitalizing the result.
*
* In an element representing a method named "get" taking one
* integer argument, the "method" attribute is replaced
* with an "index" attribute whose value the value of the
* first argument.
*
* In an element representing a method named "set" taking two arguments,
* the first of which is an integer, the "method" attribute is replaced
* with an "index" attribute whose value the value of the
* first argument.
*
* A reference to an array is written using the "array"
* tag. The "class" and "length" attributes specify the
* sub-type of the array and its length respectively.
*
*
*
* For more information you might also want to check out
* Using XMLEncoder,
* an article in The Swing Connection.
* @see XMLDecoder
* @see java.io.ObjectOutputStream
*
* @since 1.4
*
* @author Philip Milne
*/
public class XMLEncoder extends Encoder {
private final CharsetEncoder encoder;
private final String charset;
private final boolean declaration;
private OutputStreamWriter out;
private Object owner;
private int indentation = 0;
private boolean internal = false;
private Map