/* XMLElement.java                                                 NanoXML/Lite
    *
    * This file is part of NanoXML 2 Lite.
    * Copyright (C) 2000-2002 Marc De Scheemaecker, All Rights Reserved.
    *
    * This software is provided 'as-is', without any express or implied warranty.
    * In no event will the authors be held liable for any damages arising from the
    * use of this software.
    *
   * Permission is granted to anyone to use this software for any purpose,
   * including commercial applications, and to alter it and redistribute it
   * freely, subject to the following restrictions:
   *
   *  1. The origin of this software must not be misrepresented; you must not
   *     claim that you wrote the original software. If you use this software in
   *     a product, an acknowledgment in the product documentation would be
   *     appreciated but is not required.
   *
   *  2. Altered source versions must be plainly marked as such, and must not be
   *     misrepresented as being the original software.
   *
   *  3. This notice may not be removed or altered from any source distribution.
   */
  
  package nanoxml;
  
  import java.io.ByteArrayOutputStream;
  import java.io.CharArrayReader;
  import java.io.IOException;
  import java.io.OutputStreamWriter;
  import java.io.Reader;
  import java.io.StringReader;
  import java.io.Writer;
  import java.util.Enumeration;
  import java.util.HashMap;
  import java.util.Hashtable;
  import java.util.Iterator;
  import java.util.Map;
  import java.util.Vector;
  
  /**
   * XMLElement is a representation of an XML object. The object is able to parse
   * XML code.
   * <P>
   * <DL>
   * <DT><B>Parsing XML Data</B></DT>
   * <DD> You can parse XML data using the following code:
   * <UL>
   * <CODE>
   * XMLElement xml = new XMLElement();<BR>
   * FileReader reader = new FileReader("filename.xml");<BR>
   * xml.parseFromReader(reader);
   * </CODE>
   * </UL>
   * </DD>
   * </DL>
   * <DL>
   * <DT><B>Retrieving Attributes</B></DT>
   * <DD> You can enumerate the attributes of an element using the method
   * {@link #enumerateAttributeNames() enumerateAttributeNames}. The attribute
   * values can be retrieved using the method
   * {@link #getStringAttribute(java.lang.String) getStringAttribute}. The
   * following example shows how to list the attributes of an element:
   * <UL>
   * <CODE>
   * XMLElement element = ...;<BR>
   * Enumeration enum = element.getAttributeNames();<BR>
   * while (enum.hasMoreElements()) {<BR>
   * &nbsp;&nbsp;&nbsp;&nbsp;String key = (String) enum.nextElement();<BR>
   * &nbsp;&nbsp;&nbsp;&nbsp;String value = element.getStringAttribute(key);<BR>
   * &nbsp;&nbsp;&nbsp;&nbsp;System.out.println(key + " = " + value);<BR>
   * }
   * </CODE>
   * </UL>
   * </DD>
   * </DL>
   * <DL>
   * <DT><B>Retrieving Child Elements</B></DT>
   * <DD> You can enumerate the children of an element using
   * {@link #enumerateChildren() enumerateChildren}. The number of child elements
   * can be retrieved using {@link #countChildren() countChildren}. </DD>
   * </DL>
   * <DL>
   * <DT><B>Elements Containing Character Data</B></DT>
   * <DD> If an elements contains character data, like in the following example:
   * <UL>
   * <CODE>
   * &lt;title&gt;The Title&lt;/title&gt;
   * </CODE>
   * </UL>
   * you can retrieve that data using the method {@link #getContent() getContent}.
   * </DD>
   * </DL>
   * <DL>
   * <DT><B>Subclassing XMLElement</B></DT>
   * <DD> When subclassing XMLElement, you need to override the method
   * {@link #createAnotherElement() createAnotherElement} which has to return a
   * new copy of the receiver. </DD>
   * </DL>
  * <P>
  * 
  * @see nanoxml.XMLParseException
  * 
  * @author Marc De Scheemaecker &lt;<A
  *         href="mailto:cyberelf@mac.com">cyberelf@mac.com</A>&gt;
  */
 public class XMLElement {
 
 	/**
 	 * Serialization serial version ID.
 	 */
 	static final long serialVersionUID = 6685035139346394777L;
 
 	/**
 	 * Major version of NanoXML. Classes with the same major and minor version
 	 * are binary compatible. Classes with the same major version are source
 	 * compatible. If the major version is different, you may need to modify the
 	 * client source code.
 	 * 
 	 * @see nanoxml.XMLElement#NANOXML_MINOR_VERSION
 	 */
 	public static final int NANOXML_MAJOR_VERSION = 2;
 
 	/**
 	 * Minor version of NanoXML. Classes with the same major and minor version
 	 * are binary compatible. Classes with the same major version are source
 	 * compatible. If the major version is different, you may need to modify the
 	 * client source code.
 	 * 
 	 * @see nanoxml.XMLElement#NANOXML_MAJOR_VERSION
 	 */
 	public static final int NANOXML_MINOR_VERSION = 2;
 
 	/**
 	 * The attributes given to the element.
 	 * 
 	 * <dl>
 	 * <dt><b>Invariants:</b></dt>
 	 * <dd>
 	 * <ul>
 	 * <li>The field can be empty.
 	 * <li>The field is never <code>null</code>.
 	 * <li>The keys and the values are strings.
 	 * </ul>
 	 * </dd>
 	 * </dl>
 	 */
 	private Hashtable attributes;
 
 	/**
 	 * Child elements of the element.
 	 * 
 	 * <dl>
 	 * <dt><b>Invariants:</b></dt>
 	 * <dd>
 	 * <ul>
 	 * <li>The field can be empty.
 	 * <li>The field is never <code>null</code>.
 	 * <li>The elements are instances of <code>XMLElement</code> or a
 	 * subclass of <code>XMLElement</code>.
 	 * </ul>
 	 * </dd>
 	 * </dl>
 	 */
 	private Vector children;
 
 	/**
 	 * The name of the element.
 	 * 
 	 * <dl>
 	 * <dt><b>Invariants:</b></dt>
 	 * <dd>
 	 * <ul>
 	 * <li>The field is <code>null</code> iff the element is not initialized
 	 * by either parse or setName.
 	 * <li>If the field is not <code>null</code>, it's not empty.
 	 * <li>If the field is not <code>null</code>, it contains a valid XML
 	 * identifier.
 	 * </ul>
 	 * </dd>
 	 * </dl>
 	 */
 	private String name;
 
 	/**
 	 * The #PCDATA content of the object.
 	 * 
 	 * <dl>
 	 * <dt><b>Invariants:</b></dt>
 	 * <dd>
 	 * <ul>
 	 * <li>The field is <code>null</code> iff the element is not a #PCDATA
 	 * element.
 	 * <li>The field can be any string, including the empty string.
 	 * </ul>
 	 * </dd>
 	 * </dl>
 	 */
 	private String contents;
 
 	/**
 	 * Conversion table for &amp;...; entities. The keys are the entity names
 	 * without the &amp; and ; delimiters.
 	 * 
 	 * <dl>
 	 * <dt><b>Invariants:</b></dt>
 	 * <dd>
 	 * <ul>
 	 * <li>The field is never <code>null</code>.
 	 * <li>The field always contains the following associations:
 	 * "lt"&nbsp;=&gt;&nbsp;"&lt;", "gt"&nbsp;=&gt;&nbsp;"&gt;",
 	 * "quot"&nbsp;=&gt;&nbsp;"\"", "apos"&nbsp;=&gt;&nbsp;"'",
 	 * "amp"&nbsp;=&gt;&nbsp;"&amp;"
 	 * <li>The keys are strings
 	 * <li>The values are char arrays
 	 * </ul>
 	 * </dd>
 	 * </dl>
 	 */
 	private Hashtable entities;
 
 	/**
 	 * The line number where the element starts.
 	 * 
 	 * <dl>
 	 * <dt><b>Invariants:</b></dt>
 	 * <dd>
 	 * <ul>
 	 * <li><code>lineNr &gt= 0</code>
 	 * </ul>
 	 * </dd>
 	 * </dl>
 	 */
 	private int lineNr;
 
 	/**
 	 * <code>true</code> if the case of the element and attribute names are
 	 * case insensitive.
 	 */
 	private boolean ignoreCase;
 
 	/**
 	 * <code>true</code> if the leading and trailing whitespace of #PCDATA
 	 * sections have to be ignored.
 	 */
 	private boolean ignoreWhitespace;
 
 	/**
 	 * Character read too much. This character provides push-back functionality
 	 * to the input reader without having to use a PushbackReader. If there is
 	 * no such character, this field is '\0'.
 	 */
 	private char charReadTooMuch;
 
 	/**
 	 * The reader provided by the caller of the parse method.
 	 * 
 	 * <dl>
 	 * <dt><b>Invariants:</b></dt>
 	 * <dd>
 	 * <ul>
 	 * <li>The field is not <code>null</code> while the parse method is
 	 * running.
 	 * </ul>
 	 * </dd>
 	 * </dl>
 	 */
 	private Reader reader;
 
 	/**
 	 * The current line number in the source content.
 	 * 
 	 * <dl>
 	 * <dt><b>Invariants:</b></dt>
 	 * <dd>
 	 * <ul>
 	 * <li>parserLineNr &gt; 0 while the parse method is running.
 	 * </ul>
 	 * </dd>
 	 * </dl>
 	 */
 	private int parserLineNr;
 
 	/**
 	 * Creates and initializes a new XML element. Calling the construction is
 	 * equivalent to:
 	 * <ul>
 	 * <code>new XMLElement(new Hashtable(), false, true)
 	 * </code>
 	 * </ul>
 	 * 
 	 * <dl>
 	 * <dt><b>Postconditions:</b></dt>
 	 * <dd>
 	 * <ul>
 	 * <li>countChildren() => 0
 	 * <li>enumerateChildren() => empty enumeration
 	 * <li>enumeratePropertyNames() => empty enumeration
 	 * <li>getChildren() => empty vector
 	 * <li>getContent() => ""
 	 * <li>getLineNr() => 0
 	 * <li>getName() => null
 	 * </ul>
 	 * </dd>
 	 * </dl>
 	 * 
 	 * @see nanoxml.XMLElement#XMLElement(java.util.Hashtable)
 	 *      XMLElement(Hashtable)
 	 * @see nanoxml.XMLElement#XMLElement(boolean)
 	 * @see nanoxml.XMLElement#XMLElement(java.util.Hashtable,boolean)
 	 *      XMLElement(Hashtable, boolean)
 	 */
 	public XMLElement() {
 		this(new Hashtable(), false, true, true);
 	}
 
 	public XMLElement(boolean skipLeadingWhitespace, boolean ignoreCase) {
 		this(new Hashtable(), skipLeadingWhitespace, true, ignoreCase);
 	}
 
 	/**
 	 * Creates and initializes a new XML element. Calling the construction is
 	 * equivalent to:
 	 * <ul>
 	 * <code>new XMLElement(entities, false, true)
 	 * </code>
 	 * </ul>
 	 * 
 	 * @param entities
 	 *            The entity conversion table.
 	 * 
 	 * </dl>
 	 * <dl>
 	 * <dt><b>Preconditions:</b></dt>
 	 * <dd>
 	 * <ul>
 	 * <li><code>entities != null</code>
 	 * </ul>
 	 * </dd>
 	 * </dl>
 	 * 
 	 * <dl>
 	 * <dt><b>Postconditions:</b></dt>
 	 * <dd>
 	 * <ul>
 	 * <li>countChildren() => 0
 	 * <li>enumerateChildren() => empty enumeration
 	 * <li>enumeratePropertyNames() => empty enumeration
 	 * <li>getChildren() => empty vector
 	 * <li>getContent() => ""
 	 * <li>getLineNr() => 0
 	 * <li>getName() => null
 	 * </ul>
 	 * </dd>
 	 * </dl>
 	 * <dl>
 	 * 
 	 * @see nanoxml.XMLElement#XMLElement()
 	 * @see nanoxml.XMLElement#XMLElement(boolean)
 	 * @see nanoxml.XMLElement#XMLElement(java.util.Hashtable,boolean)
 	 *      XMLElement(Hashtable, boolean)
 	 */
 	public XMLElement(Hashtable entities) {
 		this(entities, false, true, true);
 	}
 
 	/**
 	 * Creates and initializes a new XML element. Calling the construction is
 	 * equivalent to:
 	 * <ul>
 	 * <code>new XMLElement(new Hashtable(), skipLeadingWhitespace, true)
 	 * </code>
 	 * </ul>
 	 * 
 	 * @param skipLeadingWhitespace
 	 *            <code>true</code> if leading and trailing whitespace in
 	 *            PCDATA content has to be removed.
 	 * 
 	 * </dl>
 	 * <dl>
 	 * <dt><b>Postconditions:</b></dt>
 	 * <dd>
 	 * <ul>
 	 * <li>countChildren() => 0
 	 * <li>enumerateChildren() => empty enumeration
 	 * <li>enumeratePropertyNames() => empty enumeration
 	 * <li>getChildren() => empty vector
 	 * <li>getContent() => ""
 	 * <li>getLineNr() => 0
 	 * <li>getName() => null
 	 * </ul>
 	 * </dd>
 	 * </dl>
 	 * <dl>
 	 * 
 	 * @see nanoxml.XMLElement#XMLElement()
 	 * @see nanoxml.XMLElement#XMLElement(java.util.Hashtable)
 	 *      XMLElement(Hashtable)
 	 * @see nanoxml.XMLElement#XMLElement(java.util.Hashtable,boolean)
 	 *      XMLElement(Hashtable, boolean)
 	 */
 	public XMLElement(boolean skipLeadingWhitespace) {
 		this(new Hashtable(), skipLeadingWhitespace, true, true);
 	}
 
 	/**
 	 * Creates and initializes a new XML element. Calling the construction is
 	 * equivalent to:
 	 * <ul>
 	 * <code>new XMLElement(entities, skipLeadingWhitespace, true)
 	 * </code>
 	 * </ul>
 	 * 
 	 * @param entities
 	 *            The entity conversion table.
 	 * @param skipLeadingWhitespace
 	 *            <code>true</code> if leading and trailing whitespace in
 	 *            PCDATA content has to be removed.
 	 * 
 	 * </dl>
 	 * <dl>
 	 * <dt><b>Preconditions:</b></dt>
 	 * <dd>
 	 * <ul>
 	 * <li><code>entities != null</code>
 	 * </ul>
 	 * </dd>
 	 * </dl>
 	 * 
 	 * <dl>
 	 * <dt><b>Postconditions:</b></dt>
 	 * <dd>
 	 * <ul>
 	 * <li>countChildren() => 0
 	 * <li>enumerateChildren() => empty enumeration
 	 * <li>enumeratePropertyNames() => empty enumeration
 	 * <li>getChildren() => empty vector
 	 * <li>getContent() => ""
 	 * <li>getLineNr() => 0
 	 * <li>getName() => null
 	 * </ul>
 	 * </dd>
 	 * </dl>
 	 * <dl>
 	 * 
 	 * @see nanoxml.XMLElement#XMLElement()
 	 * @see nanoxml.XMLElement#XMLElement(boolean)
 	 * @see nanoxml.XMLElement#XMLElement(java.util.Hashtable)
 	 *      XMLElement(Hashtable)
 	 */
 	public XMLElement(Hashtable entities, boolean skipLeadingWhitespace) {
 		this(entities, skipLeadingWhitespace, true, true);
 	}
 
 	/**
 	 * Creates and initializes a new XML element.
 	 * 
 	 * @param entities
 	 *            The entity conversion table.
 	 * @param skipLeadingWhitespace
 	 *            <code>true</code> if leading and trailing whitespace in
 	 *            PCDATA content has to be removed.
 	 * @param ignoreCase
 	 *            <code>true</code> if the case of element and attribute names
 	 *            have to be ignored.
 	 * 
 	 * </dl>
 	 * <dl>
 	 * <dt><b>Preconditions:</b></dt>
 	 * <dd>
 	 * <ul>
 	 * <li><code>entities != null</code>
 	 * </ul>
 	 * </dd>
 	 * </dl>
 	 * 
 	 * <dl>
 	 * <dt><b>Postconditions:</b></dt>
 	 * <dd>
 	 * <ul>
 	 * <li>countChildren() => 0
 	 * <li>enumerateChildren() => empty enumeration
 	 * <li>enumeratePropertyNames() => empty enumeration
 	 * <li>getChildren() => empty vector
 	 * <li>getContent() => ""
 	 * <li>getLineNr() => 0
 	 * <li>getName() => null
 	 * </ul>
 	 * </dd>
 	 * </dl>
 	 * <dl>
 	 * 
 	 * @see nanoxml.XMLElement#XMLElement()
 	 * @see nanoxml.XMLElement#XMLElement(boolean)
 	 * @see nanoxml.XMLElement#XMLElement(java.util.Hashtable)
 	 *      XMLElement(Hashtable)
 	 * @see nanoxml.XMLElement#XMLElement(java.util.Hashtable,boolean)
 	 *      XMLElement(Hashtable, boolean)
 	 */
 	public XMLElement(Hashtable entities, boolean skipLeadingWhitespace, boolean ignoreCase) {
 		this(entities, skipLeadingWhitespace, true, ignoreCase);
 	}
 
 	/**
 	 * Creates and initializes a new XML element.
 	 * <P>
 	 * This constructor should <I>only</I> be called from
 	 * {@link #createAnotherElement() createAnotherElement} to create child
 	 * elements.
 	 * 
 	 * @param entities
 	 *            The entity conversion table.
 	 * @param skipLeadingWhitespace
 	 *            <code>true</code> if leading and trailing whitespace in
 	 *            PCDATA content has to be removed.
 	 * @param fillBasicConversionTable
 	 *            <code>true</code> if the basic entities need to be added to
 	 *            the entity list.
 	 * @param ignoreCase
 	 *            <code>true</code> if the case of element and attribute names
 	 *            have to be ignored.
 	 * 
 	 * </dl>
 	 * <dl>
 	 * <dt><b>Preconditions:</b></dt>
 	 * <dd>
 	 * <ul>
 	 * <li><code>entities != null</code>
 	 * <li>if <code>fillBasicConversionTable == false</code> then
 	 * <code>entities</code> contains at least the following entries:
 	 * <code>amp</code>, <code>lt</code>, <code>gt</code>,
 	 * <code>apos</code> and <code>quot</code>
 	 * </ul>
 	 * </dd>
 	 * </dl>
 	 * 
 	 * <dl>
 	 * <dt><b>Postconditions:</b></dt>
 	 * <dd>
 	 * <ul>
 	 * <li>countChildren() => 0
 	 * <li>enumerateChildren() => empty enumeration
 	 * <li>enumeratePropertyNames() => empty enumeration
 	 * <li>getChildren() => empty vector
 	 * <li>getContent() => ""
 	 * <li>getLineNr() => 0
 	 * <li>getName() => null
 	 * </ul>
 	 * </dd>
 	 * </dl>
 	 * <dl>
 	 * 
 	 * @see nanoxml.XMLElement#createAnotherElement()
 	 */
 	protected XMLElement(Hashtable entities, boolean skipLeadingWhitespace, boolean fillBasicConversionTable,
 			boolean ignoreCase) {
 		this.ignoreWhitespace = skipLeadingWhitespace;
 		this.ignoreCase = ignoreCase;
 		this.name = null;
 		this.contents = "";
 		this.attributes = new Hashtable();
 		this.children = new Vector();
 		this.entities = entities;
 		this.lineNr = 0;
 
 		Enumeration en = this.entities.keys();
 
 		while (en.hasMoreElements()) {
 			Object key = en.nextElement();
 			Object value = this.entities.get(key);
 
 			if (value instanceof String) {
 				value = ((String) value).toCharArray();
 				this.entities.put(key, value);
 			}
 		}
 
 		if (fillBasicConversionTable) {
 			this.entities.put("amp", new char[] { '&' });
 			this.entities.put("quot", new char[] { '"' });
 			this.entities.put("apos", new char[] { '\'' });
 			this.entities.put("lt", new char[] { '<' });
 			this.entities.put("gt", new char[] { '>' });
 		}
 	}
 
 	/**
 	 * Adds a child element.
 	 * 
 	 * @param child
 	 *            The child element to add.
 	 * 
 	 * </dl>
 	 * <dl>
 	 * <dt><b>Preconditions:</b></dt>
 	 * <dd>
 	 * <ul>
 	 * <li><code>child != null</code>
 	 * <li><code>child.getName() != null</code>
 	 * <li><code>child</code> does not have a parent element
 	 * </ul>
 	 * </dd>
 	 * </dl>
 	 * 
 	 * <dl>
 	 * <dt><b>Postconditions:</b></dt>
 	 * <dd>
 	 * <ul>
 	 * <li>countChildren() => old.countChildren() + 1
 	 * <li>enumerateChildren() => old.enumerateChildren() + child
 	 * <li>getChildren() => old.enumerateChildren() + child
 	 * </ul>
 	 * </dd>
 	 * </dl>
 	 * <dl>
 	 * 
 	 * @see nanoxml.XMLElement#countChildren()
 	 * @see nanoxml.XMLElement#enumerateChildren()
 	 * @see nanoxml.XMLElement#getChildren()
 	 * @see nanoxml.XMLElement#removeChild(nanoxml.XMLElement)
 	 *      removeChild(XMLElement)
 	 */
 	public void addChild(XMLElement child) {
 		this.children.addElement(child);
 	}
 
 	public XMLElement addChild(String name) {
 		XMLElement xml = new XMLElement(true, false);
 		xml.setName(name);
 		this.addChild(xml);
 		return xml;
 	}
 
 	public XMLElement addChild(String name, String value) {
 		XMLElement xml = addChild(name);
 		xml.setContent(value);
 		return xml;
 	}
 
 	/**
 	 * Adds or modifies an attribute.
 	 * 
 	 * @param name
 	 *            The name of the attribute.
 	 * @param value
 	 *            The value of the attribute.
 	 * 
 	 * </dl>
 	 * <dl>
 	 * <dt><b>Preconditions:</b></dt>
 	 * <dd>
 	 * <ul>
 	 * <li><code>name != null</code>
 	 * <li><code>name</code> is a valid XML identifier
 	 * <li><code>value != null</code>
 	 * </ul>
 	 * </dd>
 	 * </dl>
 	 * 
 	 * <dl>
 	 * <dt><b>Postconditions:</b></dt>
 	 * <dd>
 	 * <ul>
 	 * <li>enumerateAttributeNames() => old.enumerateAttributeNames() + name
 	 * <li>getAttribute(name) => value
 	 * </ul>
 	 * </dd>
 	 * </dl>
 	 * <dl>
 	 * 
 	 * @see nanoxml.XMLElement#setDoubleAttribute(java.lang.String, double)
 	 *      setDoubleAttribute(String, double)
 	 * @see nanoxml.XMLElement#setIntAttribute(java.lang.String, int)
 	 *      setIntAttribute(String, int)
 	 * @see nanoxml.XMLElement#enumerateAttributeNames()
 	 * @see nanoxml.XMLElement#getAttribute(java.lang.String)
 	 *      getAttribute(String)
 	 * @see nanoxml.XMLElement#getAttribute(java.lang.String, java.lang.Object)
 	 *      getAttribute(String, Object)
 	 * @see nanoxml.XMLElement#getAttribute(java.lang.String,
 	 *      java.util.Hashtable, java.lang.String, boolean) getAttribute(String,
 	 *      Hashtable, String, boolean)
 	 * @see nanoxml.XMLElement#getStringAttribute(java.lang.String)
 	 *      getStringAttribute(String)
 	 * @see nanoxml.XMLElement#getStringAttribute(java.lang.String,
 	 *      java.lang.String) getStringAttribute(String, String)
 	 * @see nanoxml.XMLElement#getStringAttribute(java.lang.String,
 	 *      java.util.Hashtable, java.lang.String, boolean)
 	 *      getStringAttribute(String, Hashtable, String, boolean)
 	 */
 	public void setAttribute(String name, Object value) {
 		if (this.ignoreCase) {
 			name = name.toUpperCase();
 		}
 
 		this.attributes.put(name, value.toString());
 	}
 
 	/**
 	 * Adds or modifies an attribute.
 	 * 
 	 * @param name
 	 *            The name of the attribute.
 	 * @param value
 	 *            The value of the attribute.
 	 * 
 	 * @deprecated Use {@link #setAttribute(java.lang.String, java.lang.Object)
 	 *             setAttribute} instead.
 	 */
 	public void addProperty(String name, Object value) {
 		this.setAttribute(name, value);
 	}
 
 	/**
 	 * Adds or modifies an attribute.
 	 * 
 	 * @param name
 	 *            The name of the attribute.
 	 * @param value
 	 *            The value of the attribute.
 	 * 
 	 * </dl>
 	 * <dl>
 	 * <dt><b>Preconditions:</b></dt>
 	 * <dd>
 	 * <ul>
 	 * <li><code>name != null</code>
 	 * <li><code>name</code> is a valid XML identifier
 	 * </ul>
 	 * </dd>
 	 * </dl>
 	 * 
 	 * <dl>
 	 * <dt><b>Postconditions:</b></dt>
 	 * <dd>
 	 * <ul>
 	 * <li>enumerateAttributeNames() => old.enumerateAttributeNames() + name
 	 * <li>getIntAttribute(name) => value
 	 * </ul>
 	 * </dd>
 	 * </dl>
 	 * <dl>
 	 * 
 	 * @see nanoxml.XMLElement#setDoubleAttribute(java.lang.String, double)
 	 *      setDoubleAttribute(String, double)
 	 * @see nanoxml.XMLElement#setAttribute(java.lang.String, java.lang.Object)
 	 *      setAttribute(String, Object)
 	 * @see nanoxml.XMLElement#removeAttribute(java.lang.String)
 	 *      removeAttribute(String)
 	 * @see nanoxml.XMLElement#enumerateAttributeNames()
 	 * @see nanoxml.XMLElement#getIntAttribute(java.lang.String)
 	 *      getIntAttribute(String)
 	 * @see nanoxml.XMLElement#getIntAttribute(java.lang.String, int)
 	 *      getIntAttribute(String, int)
 	 * @see nanoxml.XMLElement#getIntAttribute(java.lang.String,
 	 *      java.util.Hashtable, java.lang.String, boolean)
 	 *      getIntAttribute(String, Hashtable, String, boolean)
 	 */
 	public void setIntAttribute(String name, int value) {
 		if (this.ignoreCase) {
 			name = name.toUpperCase();
 		}
 
 		this.attributes.put(name, Integer.toString(value));
 	}
 
 	/**
 	 * Adds or modifies an attribute.
 	 * 
 	 * @param name
 	 *            The name of the attribute.
 	 * @param value
 	 *            The value of the attribute.
 	 * 
 	 * @deprecated Use {@link #setIntAttribute(java.lang.String, int)
 	 *             setIntAttribute} instead.
 	 */
 	public void addProperty(String key, int value) {
 		this.setIntAttribute(key, value);
 	}
 
 	/**
 	 * Adds or modifies an attribute.
 	 * 
 	 * @param name
 	 *            The name of the attribute.
 	 * @param value
 	 *            The value of the attribute.
 	 * 
 	 * </dl>
 	 * <dl>
 	 * <dt><b>Preconditions:</b></dt>
 	 * <dd>
 	 * <ul>
 	 * <li><code>name != null</code>
 	 * <li><code>name</code> is a valid XML identifier
 	 * </ul>
 	 * </dd>
 	 * </dl>
 	 * 
 	 * <dl>
 	 * <dt><b>Postconditions:</b></dt>
 	 * <dd>
 	 * <ul>
 	 * <li>enumerateAttributeNames() => old.enumerateAttributeNames() + name
 	 * <li>getDoubleAttribute(name) => value
 	 * </ul>
 	 * </dd>
 	 * </dl>
 	 * <dl>
 	 * 
 	 * @see nanoxml.XMLElement#setIntAttribute(java.lang.String, int)
 	 *      setIntAttribute(String, int)
 	 * @see nanoxml.XMLElement#setAttribute(java.lang.String, java.lang.Object)
 	 *      setAttribute(String, Object)
 	 * @see nanoxml.XMLElement#removeAttribute(java.lang.String)
 	 *      removeAttribute(String)
 	 * @see nanoxml.XMLElement#enumerateAttributeNames()
 	 * @see nanoxml.XMLElement#getDoubleAttribute(java.lang.String)
 	 *      getDoubleAttribute(String)
 	 * @see nanoxml.XMLElement#getDoubleAttribute(java.lang.String, double)
 	 *      getDoubleAttribute(String, double)
 	 * @see nanoxml.XMLElement#getDoubleAttribute(java.lang.String,
 	 *      java.util.Hashtable, java.lang.String, boolean)
 	 *      getDoubleAttribute(String, Hashtable, String, boolean)
 	 */
 	public void setDoubleAttribute(String name, double value) {
 		if (this.ignoreCase) {
 			name = name.toUpperCase();
 		}
 
 		this.attributes.put(name, Double.toString(value));
 	}
 
 	/**
 	 * Adds or modifies an attribute.
 	 * 
 	 * @param name
 	 *            The name of the attribute.
 	 * @param value
 	 *            The value of the attribute.
 	 * 
 	 * @deprecated Use {@link #setDoubleAttribute(java.lang.String, double)
 	 *             setDoubleAttribute} instead.
 	 */
 	public void addProperty(String name, double value) {
 		this.setDoubleAttribute(name, value);
 	}
 
 	/**
 	 * Returns the number of child elements of the element.
 	 * 
 	 * <dl>
 	 * <dt><b>Postconditions:</b></dt>
 	 * <dd>
 	 * <ul>
 	 * <li><code>result >= 0</code>
 	 * </ul>
 	 * </dd>
 	 * </dl>
 	 * 
 	 * @see nanoxml.XMLElement#addChild(nanoxml.XMLElement) addChild(XMLElement)
 	 * @see nanoxml.XMLElement#enumerateChildren()
 	 * @see nanoxml.XMLElement#getChildren()
 	 * @see nanoxml.XMLElement#removeChild(nanoxml.XMLElement)
 	 *      removeChild(XMLElement)
 	 */
 	public int countChildren() {
 		return this.children.size();
 	}
 
 	/**
 	 * Enumerates the attribute names.
 	 * 
 	 * <dl>
 	 * <dt><b>Postconditions:</b></dt>
 	 * <dd>
 	 * <ul>
 	 * <li><code>result != null</code>
 	 * </ul>
 	 * </dd>
 	 * </dl>
 	 * 
 	 * @see nanoxml.XMLElement#setDoubleAttribute(java.lang.String, double)
 	 *      setDoubleAttribute(String, double)
 	 * @see nanoxml.XMLElement#setIntAttribute(java.lang.String, int)
 	 *      setIntAttribute(String, int)
 	 * @see nanoxml.XMLElement#setAttribute(java.lang.String, java.lang.Object)
 	 *      setAttribute(String, Object)
 	 * @see nanoxml.XMLElement#removeAttribute(java.lang.String)
 	 *      removeAttribute(String)
 	 * @see nanoxml.XMLElement#getAttribute(java.lang.String)
 	 *      getAttribute(String)
 	 * @see nanoxml.XMLElement#getAttribute(java.lang.String, java.lang.Object)
 	 *      getAttribute(String, String)
 	 * @see nanoxml.XMLElement#getAttribute(java.lang.String,
 	 *      java.util.Hashtable, java.lang.String, boolean) getAttribute(String,
 	 *      Hashtable, String, boolean)
 	 * @see nanoxml.XMLElement#getStringAttribute(java.lang.String)
 	 *      getStringAttribute(String)
 	 * @see nanoxml.XMLElement#getStringAttribute(java.lang.String,
 	 *      java.lang.String) getStringAttribute(String, String)
 	 * @see nanoxml.XMLElement#getStringAttribute(java.lang.String,
 	 *      java.util.Hashtable, java.lang.String, boolean)
 	 *      getStringAttribute(String, Hashtable, String, boolean)
 	 * @see nanoxml.XMLElement#getIntAttribute(java.lang.String)
 	 *      getIntAttribute(String)
 	 * @see nanoxml.XMLElement#getIntAttribute(java.lang.String, int)
 	 *      getIntAttribute(String, int)
 	 * @see nanoxml.XMLElement#getIntAttribute(java.lang.String,
 	 *      java.util.Hashtable, java.lang.String, boolean)
 	 *      getIntAttribute(String, Hashtable, String, boolean)
 	 * @see nanoxml.XMLElement#getDoubleAttribute(java.lang.String)
 	 *      getDoubleAttribute(String)
 	 * @see nanoxml.XMLElement#getDoubleAttribute(java.lang.String, double)
 	 *      getDoubleAttribute(String, double)
 	 * @see nanoxml.XMLElement#getDoubleAttribute(java.lang.String,
 	 *      java.util.Hashtable, java.lang.String, boolean)
 	 *      getDoubleAttribute(String, Hashtable, String, boolean)
 	 * @see nanoxml.XMLElement#getBooleanAttribute(java.lang.String,
 	 *      java.lang.String, java.lang.String, boolean)
 	 *      getBooleanAttribute(String, String, String, boolean)
 	 */
 	public Enumeration enumerateAttributeNames() {
 		return this.attributes.keys();
 	}
 
 	/**
 	 * Enumerates the attribute names.
 	 * 
 	 * @deprecated Use {@link #enumerateAttributeNames()
 	 *             enumerateAttributeNames} instead.
 	 */
 	public Enumeration enumeratePropertyNames() {
 		return this.enumerateAttributeNames();
 	}
 
 	/**
 	 * Enumerates the child elements.
 	 * 
 	 * <dl>
 	 * <dt><b>Postconditions:</b></dt>
 	 * <dd>
 	 * <ul>
 	 * <li><code>result != null</code>
 	 * </ul>
 	 * </dd>
 	 * </dl>
 	 * 
 	 * @see nanoxml.XMLElement#addChild(nanoxml.XMLElement) addChild(XMLElement)
 	 * @see nanoxml.XMLElement#countChildren()
 	 * @see nanoxml.XMLElement#getChildren()
 	 * @see nanoxml.XMLElement#removeChild(nanoxml.XMLElement)
 	 *      removeChild(XMLElement)
 	 */
 	public Enumeration enumerateChildren() {
 		return this.children.elements();
 	}
 
 	/**
 	 * Returns the child elements as a Vector. It is safe to modify this Vector.
 	 * 
 	 * <dl>
 	 * <dt><b>Postconditions:</b></dt>
 	 * <dd>
 	 * <ul>
 	 * <li><code>result != null</code>
 	 * </ul>
 	 * </dd>
 	 * </dl>
 	 * 
 	 * @see nanoxml.XMLElement#addChild(nanoxml.XMLElement) addChild(XMLElement)
 	 * @see nanoxml.XMLElement#countChildren()
 	 * @see nanoxml.XMLElement#enumerateChildren()
 	 * @see nanoxml.XMLElement#removeChild(nanoxml.XMLElement)
 	 *      removeChild(XMLElement)
 	 */
 	public Vector getChildren() {
 		try {
 			return (Vector) this.children.clone();
 		} catch (Exception e) {
 			// this never happens, however, some Java compilers are so
 			// braindead that they require this exception clause
 			return null;
 		}
 	}
 
 	/**
 	 * Returns the first child element by name .
 	 */
 	public XMLElement getChild(String name) {
 		for (Enumeration en = this.children.elements(); en.hasMoreElements();) {
 			XMLElement el = (XMLElement) en.nextElement();
 			if (el.getName().equals(name)) {
 				return el;
 			}
 		}
 		return null;
 	}
 
 	public XMLElement getChildOrNew(String name) {
 		XMLElement c = getChild(name);
 		if (c == null) {
 			c = addChild(name);
 		}
 		return c;
 	}
 
 	public int getChildCount(String name) {
 		int cnt = 0;
 		for (Enumeration en = this.children.elements(); en.hasMoreElements();) {
 			XMLElement el = (XMLElement) en.nextElement();
 			if (el.getName().equals(name)) {
 				cnt++;
 			}
 		}
 		return cnt;
 	}
 
 	public XMLElement getChild(String name, String attrValue) {
 		for (Enumeration en = this.children.elements(); en.hasMoreElements();) {
 			XMLElement el = (XMLElement) en.nextElement();
 			String elAttrValue = el.getStringAttribute("name");
 			if ((el.getName().equals(name)) && ((attrValue == elAttrValue) || attrValue.equals(elAttrValue))) {
 				return el;
 			}
 		}
 		return null;
 	}
 
 	public XMLElement getChild(String name, Map equalAttributesNameValue) {
 		nextChildren: for (Enumeration en = this.children.elements(); en.hasMoreElements();) {
 			XMLElement el = (XMLElement) en.nextElement();
 			if (el.getName().equals(name)) {
 				nextAttribute: for (Iterator i = equalAttributesNameValue.entrySet().iterator(); i.hasNext();) {
 					Map.Entry atrNameValue = (Map.Entry) i.next();
 					String attrValue = el.getStringAttribute((String) atrNameValue.getKey());
 					if (atrNameValue.getValue() == null) {
 						if (attrValue != null) {
 							continue nextChildren;
 						} else {
 							continue nextAttribute;
 						}
 					}
 					if (!atrNameValue.getValue().equals(attrValue)) {
 						continue nextChildren;
 					}
 				}
 				return el;
 			}
 		}
 		return null;
 	}
 
 	public int getChildInteger(String name, int defaultValue) {
 		XMLElement xml = this.getChild(name);
 		if (xml == null) {
 			return defaultValue;
 		}
 		try {
 			return Integer.parseInt(xml.getContent());
 		} catch (NumberFormatException e) {
 			return defaultValue;
 		}
 	}
 
 	public String getChildString(String name, String defaultValue) {
 		XMLElement xml = this.getChild(name);
 		if (xml == null) {
 			return defaultValue;
 		}
 		String v = xml.getContent();
 		if ((v == null) || (v.length() == 0)) {
 			return defaultValue;
 		}
 		return v;
 	}
 
 	/**
 	 * Returns the PCDATA content of the object. If there is no such content,
 	 * <CODE>null</CODE> is returned.
 	 * 
 	 * @deprecated Use {@link #getContent() getContent} instead.
 	 */
 	public String getContents() {
 		return this.getContent();
 	}
 
 	/**
 	 * Returns the PCDATA content of the object. If there is no such content,
 	 * <CODE>null</CODE> is returned.
 	 * 
 	 * @see nanoxml.XMLElement#setContent(java.lang.String) setContent(String)
 	 */
 	public String getContent() {
 		return this.contents;
 	}
 
 	/**
 	 * Returns the line nr in the source data on which the element is found.
 	 * This method returns <code>0</code> there is no associated source data.
 	 * 
 	 * <dl>
 	 * <dt><b>Postconditions:</b></dt>
 	 * <dd>
 	 * <ul>
 	 * <li><code>result >= 0</code>
 	 * </ul>
 	 * </dd>
 	 * </dl>
 	 */
 	public int getLineNr() {
 		return this.lineNr;
 	}
 
 	/**
 	 * Returns an attribute of the element. If the attribute doesn't exist,
 	 * <code>null</code> is returned.
 	 * 
 	 * @param name
 	 *            The name of the attribute.
 	 * 
 	 * </dl>
 	 * <dl>
 	 * <dt><b>Preconditions:</b></dt>
 	 * <dd>
 	 * <ul>
 	 * <li><code>name != null</code>
 	 * <li><code>name</code> is a valid XML identifier
 	 * </ul>
 	 * </dd>
 	 * </dl>
 	 * <dl>
 	 * 
 	 * @see nanoxml.XMLElement#setAttribute(java.lang.String, java.lang.Object)
 	 *      setAttribute(String, Object)
 	 * @see nanoxml.XMLElement#removeAttribute(java.lang.String)
 	 *      removeAttribute(String)
 	 * @see nanoxml.XMLElement#enumerateAttributeNames()
 	 * @see nanoxml.XMLElement#getAttribute(java.lang.String, java.lang.Object)
 	 *      getAttribute(String, Object)
 	 * @see nanoxml.XMLElement#getAttribute(java.lang.String,
 	 *      java.util.Hashtable, java.lang.String, boolean) getAttribute(String,
 	 *      Hashtable, String, boolean)
 	 */
 	public Object getAttribute(String name) {
 		return this.getAttribute(name, null);
 	}
 
 	/**
 	 * Returns an attribute of the element. If the attribute doesn't exist,
 	 * <code>defaultValue</code> is returned.
 	 * 
 	 * @param name
 	 *            The name of the attribute.
 	 * @param defaultValue
 	 *            Key to use if the attribute is missing.
 	 * 
 	 * </dl>
 	 * <dl>
 	 * <dt><b>Preconditions:</b></dt>
 	 * <dd>
 	 * <ul>
 	 * <li><code>name != null</code>
 	 * <li><code>name</code> is a valid XML identifier
 	 * </ul>
 	 * </dd>
 	 * </dl>
 	 * <dl>
 	 * 
 	 * @see nanoxml.XMLElement#setAttribute(java.lang.String, java.lang.Object)
 	 *      setAttribute(String, Object)
 	 * @see nanoxml.XMLElement#removeAttribute(java.lang.String)
 	 *      removeAttribute(String)
 	 * @see nanoxml.XMLElement#enumerateAttributeNames()
 	 * @see nanoxml.XMLElement#getAttribute(java.lang.String)
 	 *      getAttribute(String)
 	 * @see nanoxml.XMLElement#getAttribute(java.lang.String,
 	 *      java.util.Hashtable, java.lang.String, boolean) getAttribute(String,
 	 *      Hashtable, String, boolean)
 	 */
 	public Object getAttribute(String name, Object defaultValue) {
 		if (this.ignoreCase) {
 			name = name.toUpperCase();
 		}
 
 		Object value = this.attributes.get(name);
 
 		if (value == null) {
 			value = defaultValue;
 		}
 
 		return value;
 	}
 
 	/**
 	 * Returns an attribute by looking up a key in a hashtable. If the attribute
 	 * doesn't exist, the value corresponding to defaultKey is returned.
 	 * <P>
 	 * As an example, if valueSet contains the mapping <code>"one" =>
 	 * "1"</code>
 	 * and the element contains the attribute <code>attr="one"</code>, then
 	 * <code>getAttribute("attr", mapping, defaultKey, false)</code> returns
 	 * <code>"1"</code>.
 	 * 
 	 * @param name
 	 *            The name of the attribute.
 	 * @param valueSet
 	 *            Hashtable mapping keys to values.
 	 * @param defaultKey
 	 *            Key to use if the attribute is missing.
 	 * @param allowLiterals
 	 *            <code>true</code> if literals are valid.
 	 * 
 	 * </dl>
 	 * <dl>
 	 * <dt><b>Preconditions:</b></dt>
 	 * <dd>
 	 * <ul>
 	 * <li><code>name != null</code>
 	 * <li><code>name</code> is a valid XML identifier
 	 * <li><code>valueSet</code> != null
 	 * <li>the keys of <code>valueSet</code> are strings
 	 * </ul>
 	 * </dd>
 	 * </dl>
 	 * <dl>
 	 * 
 	 * @see nanoxml.XMLElement#setAttribute(java.lang.String, java.lang.Object)
 	 *      setAttribute(String, Object)
 	 * @see nanoxml.XMLElement#removeAttribute(java.lang.String)
 	 *      removeAttribute(String)
 	 * @see nanoxml.XMLElement#enumerateAttributeNames()
 	 * @see nanoxml.XMLElement#getAttribute(java.lang.String)
 	 *      getAttribute(String)
 	 * @see nanoxml.XMLElement#getAttribute(java.lang.String, java.lang.Object)
 	 *      getAttribute(String, Object)
 	 */
 	public Object getAttribute(String name, Hashtable valueSet, String defaultKey, boolean allowLiterals) {
 		if (this.ignoreCase) {
 			name = name.toUpperCase();
 		}
 
 		Object key = this.attributes.get(name);
 		Object result;
 
 		if (key == null) {
 			key = defaultKey;
 		}
 
 		result = valueSet.get(key);
 
 		if (result == null) {
 			if (allowLiterals) {
 				result = key;
 			} else {
 				throw this.invalidValue(name, (String) key);
 			}
 		}
 
 		return result;
 	}
 
 	/**
 	 * Returns an attribute of the element. If the attribute doesn't exist,
 	 * <code>null</code> is returned.
 	 * 
 	 * @param name
 	 *            The name of the attribute.
 	 * 
 	 * </dl>
 	 * <dl>
 	 * <dt><b>Preconditions:</b></dt>
 	 * <dd>
 	 * <ul>
 	 * <li><code>name != null</code>
 	 * <li><code>name</code> is a valid XML identifier
 	 * </ul>
 	 * </dd>
 	 * </dl>
 	 * <dl>
 	 * 
 	 * @see nanoxml.XMLElement#setAttribute(java.lang.String, java.lang.Object)
 	 *      setAttribute(String, Object)
 	 * @see nanoxml.XMLElement#removeAttribute(java.lang.String)
 	 *      removeAttribute(String)
 	 * @see nanoxml.XMLElement#enumerateAttributeNames()
 	 * @see nanoxml.XMLElement#getStringAttribute(java.lang.String,