com.dautelle.xml
Class XmlElement

java.lang.Object
  java.util.AbstractCollection
      java.util.AbstractList
          com.dautelle.xml.XmlElement

All Implemented Interfaces:

java.util.Collection, java.util.List

public final class XmlElement

extends java.util.AbstractList

This class represents a XML element. Instances of this class are made available only during the XML serialization/deserialization process.

During serialization, XML elements are used to define the XML mapping of Java objects (ref. Representable interface).

During deserialization, XML elements are restored and are converted to Java objects using the factory method:

static Object elementName.valueOf(XmlElement xml)

where the xml parameter contains the attributes (CharSequence) as well as all the inners objects (Representable) recursively created from the XML document.

Version:

4.6, July 15, 2003

Author:

Jean-Marie Dautelle

See Also:

ObjectWriter, Constructor

Field Summary

Fields inherited from class java.util.AbstractList

modCount

Method Summary

void	add(int index, java.lang.Object object) Inserts the specified object at the specified position in this XML element.
void	add(Representable element) Appends the specified nested element to this XmlElement.
boolean	addAll(Representable[] elements) Appends the specified nested elements to this XmlElement.
java.util.Iterator	attributeNames() Returns an iterator over the names of all the attributes being set for this XML element.
java.lang.Object	get(int index) Returns the object contained by this XML element at the specified position.
java.lang.CharSequence	getAttribute(java.lang.CharSequence name) Searches for the specified attribute (generic).
boolean	getAttribute(java.lang.String name, boolean defaultValue) Returns the specified boolean attribute.
double	getAttribute(java.lang.String name, double defaultValue) Returns the specified double attribute.
Enum	getAttribute(java.lang.String name, Enum defaultValue) Searches for the specified Enum attribute.
float	getAttribute(java.lang.String name, float defaultValue) Returns the specified float attribute.
int	getAttribute(java.lang.String name, int defaultValue) Returns the specified int attribute.
long	getAttribute(java.lang.String name, long defaultValue) Returns the specified long attribute.
java.lang.String	getAttribute(java.lang.String name, java.lang.String defaultValue) Searches for the specified String attribute.
java.lang.Class	getFactoryClass() Sets the factory class for this XML element.
XmlElement	getParent() Returns the parent of this XML element (container element).
boolean	isAttribute(java.lang.CharSequence name) Indicates if the specified attribute is present.
boolean	isEmpty() Indicates if this XML element is empty.
java.lang.StringBuffer	newAttribute(java.lang.CharSequence name) Creates a new attribute for this XmlElement and returns the StringBuffer holding the attribute's value.
java.lang.Object	newInstance() Convenience method equivalent to getFactoryClass().newInstance().
java.lang.Object	remove(int index) Removes the object at the specified position in this list XML element.
java.lang.Object	set(int index, java.lang.Object object) Replaces the specified object at the specified position in this XML element.
void	setAttribute(java.lang.CharSequence name, java.lang.CharSequence value) Sets the specified attribute (generic).
void	setAttribute(java.lang.String name, boolean value) Sets the specified boolean attribute.
void	setAttribute(java.lang.String name, double value) Sets the specified double attribute.
void	setAttribute(java.lang.String name, Enum value) Sets the specified Enum attribute.
void	setAttribute(java.lang.String name, float value) Sets the specified float attribute.
void	setAttribute(java.lang.String name, int value) Sets the specified int attribute.
void	setAttribute(java.lang.String name, long value) Sets the specified long attribute.
void	setFactoryClass(java.lang.Class factoryClass) Sets the factory class to use for deserialization (identified by the XML element tag name).
int	size() Returns the number of nested element contained in this XML element.

Methods inherited from class java.util.AbstractList

add, addAll, clear, equals, hashCode, indexOf, iterator, lastIndexOf, listIterator, listIterator, removeRange, subList

Methods inherited from class java.util.AbstractCollection

addAll, contains, containsAll, remove, removeAll, retainAll, toArray, toArray, toString

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.List

addAll, contains, containsAll, remove, removeAll, retainAll, toArray, toArray

Method Detail

newAttribute

public java.lang.StringBuffer newAttribute(java.lang.CharSequence name)

Creates a new attribute for this XmlElement and returns the StringBuffer holding the attribute's value.

Note: This method allows for custom formatting of attribute's values without allocating temporary String objects. For example:

           // Formats an attribute in hexadecimal.
           TypeFormat.format(intValue, 16, xml.newAttribute(name));
           

Parameters:

name - the attributes' name.

Returns:

an empty StringBuffer to hold the attribute's value.

setAttribute

public void setAttribute(java.lang.CharSequence name,
                         java.lang.CharSequence value)

Sets the specified attribute (generic).

Parameters:

name - the attributes' name.

value - the attributes' value.

setAttribute

public void setAttribute(java.lang.String name,
                         Enum value)

Sets the specified Enum attribute.

Parameters:

name - the name of the attribute.

value - the Enumfor the specified attribute.

See Also:

getAttribute(String, Enum)

setAttribute

public void setAttribute(java.lang.String name,
                         boolean value)

Sets the specified boolean attribute.

Parameters:

name - the name of the attribute.

value - the boolean value for the specified attribute.

See Also:

getAttribute(String, boolean)

setAttribute

public void setAttribute(java.lang.String name,
                         int value)

Sets the specified int attribute.

Parameters:

name - the name of the attribute.

value - the int value for the specified attribute.

See Also:

getAttribute(String, int)

setAttribute

public void setAttribute(java.lang.String name,
                         long value)

Sets the specified long attribute.

Parameters:

name - the name of the attribute.

value - the long value for the specified attribute.

See Also:

getAttribute(String, long)

setAttribute

public void setAttribute(java.lang.String name,
                         float value)

Sets the specified float attribute.

Parameters:

name - the name of the attribute.

value - the float value for the specified attribute.

See Also:

getAttribute(String, float)

setAttribute

public void setAttribute(java.lang.String name,
                         double value)

Sets the specified double attribute.

Parameters:

name - the name of the attribute.

value - the double value for the specified attribute.

See Also:

getAttribute(String, double)

setFactoryClass

public void setFactoryClass(java.lang.Class factoryClass)

Sets the factory class to use for deserialization (identified by the XML element tag name). By default, the factory class is the class of the element being serialized.

Parameters:

factoryClass - the class to use for deserialization.

getParent

public XmlElement getParent()

Returns the parent of this XML element (container element).

Returns:

this XML element's parent or null if this element is a root element.

attributeNames

public java.util.Iterator attributeNames()

Returns an iterator over the names of all the attributes being set for this XML element.

Returns:

an iterator over the attributes' names (CharSequence objects).

isAttribute

public boolean isAttribute(java.lang.CharSequence name)

Indicates if the specified attribute is present.

Parameters:

name - the name of the attribute.

Returns:

true if this xml element contains the specified attribute; false otherwise.

getAttribute

public java.lang.CharSequence getAttribute(java.lang.CharSequence name)

Searches for the specified attribute (generic).

Parameters:

name - the name of the attribute.

Returns:

the value of the attribute or null if not found.

See Also:

setAttribute(CharSequence, CharSequence)

getAttribute

public java.lang.String getAttribute(java.lang.String name,
                                     java.lang.String defaultValue)

Searches for the specified String attribute.

Parameters:

name - the name of the attribute.

defaultValue - a default value.

Returns:

the String value for the specified attribute or the defaultValue if the attribute is not found.

getAttribute

public Enum getAttribute(java.lang.String name,
                         Enum defaultValue)

Searches for the specified Enum attribute.

Parameters:

name - the name of the attribute.

defaultValue - a default value which also identifies the enumeration.

Returns:

the Enum for the specified attribute or the defaultValue if the attribute is not found.

getAttribute

public boolean getAttribute(java.lang.String name,
                            boolean defaultValue)

Returns the specified boolean attribute.

Parameters:

name - the name of the attribute searched for.

defaultValue - the value returned if the attribute is not found.

Returns:

the boolean value for the specified attribute or the default value if the attribute is not found.

getAttribute

public int getAttribute(java.lang.String name,
                        int defaultValue)

Returns the specified int attribute. This method handles string formats that are used to represent octal and hexadecimal numbers.

Parameters:

name - the name of the attribute searched for.

defaultValue - the value returned if the attribute is not found.

Returns:

the int value for the specified attribute or the default value if the attribute is not found.

getAttribute

public long getAttribute(java.lang.String name,
                         long defaultValue)

Returns the specified long attribute. This method handles string formats that are used to represent octal and hexadecimal numbers.

Parameters:

name - the name of the attribute searched for.

defaultValue - the value returned if the attribute is not found.

Returns:

the long value for the specified attribute or the default value if the attribute is not found.

getAttribute

public float getAttribute(java.lang.String name,
                          float defaultValue)

Returns the specified float attribute.

Parameters:

name - the name of the attribute searched for.

defaultValue - the value returned if the attribute is not found.

Returns:

the float value for the specified attribute or the default value if the attribute is not found.

getAttribute

public double getAttribute(java.lang.String name,
                           double defaultValue)

Returns the specified double attribute.

Parameters:

name - the name of the attribute searched for.

defaultValue - the value returned if the attribute is not found.

Returns:

the double value for the specified attribute or the default value if the attribute is not found.

getFactoryClass

public java.lang.Class getFactoryClass()

Sets the factory class for this XML element. The factory class is responsible for the convertion of the XML element to a Java Object.

Returns:

the factory class.

See Also:

setFactoryClass(java.lang.Class)

newInstance

public java.lang.Object newInstance()
                             throws ConstructorException

Convenience method equivalent to getFactoryClass().newInstance(). Typically, this method is used to provide a default XML factory method inherited by sub-classes. For example:

     abstract class TopClass {
         public static TopClass valueOf(XmlElement xml) {
             TopClass instance = (TopClass) xml.newInstance();
             ... // Initializes instance from xml.
             return instance;
         }
     }
 

Returns:

a new instance of the class corresponding to this XML element using the class default constructor.

Throws:

ConstructorException - if the instance cannot be created.

add

public void add(Representable element)

Appends the specified nested element to this XmlElement.

Parameters:

element - the nested element to be inserted.

addAll

public boolean addAll(Representable[] elements)

Appends the specified nested elements to this XmlElement.

Parameters:

elements - the nested elements being appended.

Returns:

true if this XmlElement changed as a result of this call; false otherwise.

get

public java.lang.Object get(int index)

Returns the object contained by this XML element at the specified position.

Note: Typically the object returned is a Representable, but it does not have to be if the class is deserializable only (XML document created externally).

Parameters:

index - the index of the object to return.

Returns:

the object at the specified position.

Throws:

java.lang.IndexOutOfBoundsException - if the given index is out of range (index < 0 || index >= size()).

set

public java.lang.Object set(int index,
                            java.lang.Object object)

Replaces the specified object at the specified position in this XML element.

Parameters:

index - index of the object to replace.

object - the object to be stored at the specified position.

Returns:

the object previously at the specified position.

Throws:

java.lang.ClassCastException - if this specified object is not a Representable.

java.lang.IndexOutOfBoundsException - if the specified index is out of range (index < 0 || index >= size()).

add

public void add(int index,
                java.lang.Object object)

Inserts the specified object at the specified position in this XML element. Shifts the object currently at that position (if any) and any subsequent objects to the right (adds one to their indices).

Parameters:

index - index at which the specified object is to be inserted.

object - the object to be inserted.

Throws:

java.lang.ClassCastException - if this specified object is not a Representable.

java.lang.IndexOutOfBoundsException - if the specified index is out of range (index < 0 || index > size()).

remove

public java.lang.Object remove(int index)

Removes the object at the specified position in this list XML element. Shifts any subsequent objects to the left (subtracts one from their indices). Returns the object that was removed.

Parameters:

index - the index of the object to remove.

Returns:

the object previously at the specified position.

Throws:

java.lang.IndexOutOfBoundsException - if the specified index is out of range (index < 0 || index >= size()).

size

public int size()

Returns the number of nested element contained in this XML element.

Returns:

the size of this XML element.

isEmpty

public boolean isEmpty()

Indicates if this XML element is empty. Empty elements use an alternate representation: <className .../>

Returns:

true if this element has no content; false otherwise.