javolution.xml
Class XmlElement

java.lang.Object
  javolution.xml.XmlElement

public final class XmlElement
extends java.lang.Object

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

During serialization, XmlFormat.format(XmlElement) is used to represent the Java objects into XML.

During deserialization, XmlFormat.parse(XmlElement) is used to restore the objects from their XML representations.

Version:

3.6, October 13, 2005

Author:

Jean-Marie Dautelle

Method Summary

void	add(java.lang.Object obj) Adds the specified object as an anonymous nested element of unknown type.
void	add(java.lang.Object obj, java.lang.String qName) Adds the specified object as a named nested element of unknown type (null objects are ignored).
void	add(java.lang.Object obj, java.lang.String qName, java.lang.Class clazz) Adds the specified object as a named nested element of known type (null objects are ignored).
void	add(java.lang.Object obj, java.lang.String qName, XmlFormat xmlFormat) Deprecated. Replaced by add(Object, String, Class)
ContentHandler	formatter() Returns the content handler used during serialization (typically a WriterHandler).
<T> T	get(java.lang.String qName) Returns the object corresponding to the next nested element only if it has the specified qualified name.
<T> T	get(java.lang.String qName, java.lang.Class clazz) Returns the object corresponding to the next nested element only if it has the specified qualified name; the object type is identified by the specified class parameter.
<T> T	get(java.lang.String qName, XmlFormat xmlFormat) Deprecated. Replaced by get(String, Class)
java.lang.CharSequence	getAttribute(java.lang.String name) Searches for the attribute having the specified name.
boolean	getAttribute(java.lang.String name, boolean defaultValue) Returns the specified boolean attribute.
java.lang.Boolean	getAttribute(java.lang.String name, java.lang.Boolean defaultValue) Searches for the specified Boolean attribute.
java.lang.Byte	getAttribute(java.lang.String name, java.lang.Byte defaultValue) Searches for the specified Byte attribute.
java.lang.CharSequence	getAttribute(java.lang.String name, java.lang.CharSequence defaultValue) Returns the specified CharSequence attribute.
double	getAttribute(java.lang.String name, double defaultValue) Returns the specified double attribute.
java.lang.Double	getAttribute(java.lang.String name, java.lang.Double defaultValue) Searches for the specified Double attribute.
float	getAttribute(java.lang.String name, float defaultValue) Returns the specified float attribute.
java.lang.Float	getAttribute(java.lang.String name, java.lang.Float defaultValue) Searches for the specified Float attribute.
int	getAttribute(java.lang.String name, int defaultValue) Returns the specified int attribute.
java.lang.Integer	getAttribute(java.lang.String name, java.lang.Integer defaultValue) Searches for the specified Integer attribute.
long	getAttribute(java.lang.String name, long defaultValue) Returns the specified long attribute.
java.lang.Long	getAttribute(java.lang.String name, java.lang.Long defaultValue) Searches for the specified Long attribute.
java.lang.Short	getAttribute(java.lang.String name, java.lang.Short defaultValue) Searches for the specified Short attribute.
java.lang.String	getAttribute(java.lang.String name, java.lang.String defaultValue) Returns the specified String attribute.
Attributes	getAttributes() Returns the attributes for this xml element (parsing or formatting).
FastList	getContent() Deprecated. Formats should use getNext() and hasNext() to parse anonymous content and add(Object) to serialize anonymous content.
<T> T	getNext() Returns the object corresponding to the next nested element.
boolean	hasNext() Indicates if more nested elements can be read.
boolean	isAttribute(java.lang.String name) Indicates if the specified attribute is present.
TextBuilder	newAttribute(java.lang.String name) Creates a new attribute for this xml element.
<T> T	object() Returns the object corresponding to this xml element; this is the object which has been allocated by the xml format or using the public no-arg constructor of objectClass().
java.lang.Class	objectClass() Returns the Java(tm) class corresponding to this XML element; the class is identified by the tag name of this xml element or the "j:class" attribute when present.
XmlPullParser	parser() Returns the pull parser used during deserialization.
void	removeAttribute(java.lang.String name) Removes the specified attribute.
void	setAttribute(java.lang.String name, boolean value) Sets the specified boolean attribute.
void	setAttribute(java.lang.String name, java.lang.Boolean value) Sets the specified Boolean attribute.
void	setAttribute(java.lang.String name, java.lang.Byte value) Sets the specified Byte attribute.
void	setAttribute(java.lang.String name, java.lang.CharSequence value) Sets the specified CharSequence attribute (null values are ignored).
void	setAttribute(java.lang.String name, double value) Sets the specified double attribute.
void	setAttribute(java.lang.String name, java.lang.Double value) Sets the specified Double attribute.
void	setAttribute(java.lang.String name, float value) Sets the specified float attribute.
void	setAttribute(java.lang.String name, java.lang.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, java.lang.Integer value) Sets the specified Integer attribute.
void	setAttribute(java.lang.String name, long value) Sets the specified long attribute.
void	setAttribute(java.lang.String name, java.lang.Long value) Sets the specified Long attribute.
void	setAttribute(java.lang.String name, java.lang.Short value) Sets the specified Short attribute.
void	setAttribute(java.lang.String name, java.lang.String value) Sets the specified String attribute (null values are ignored).

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

object

public <T> T object()
         throws XmlException

Returns the object corresponding to this xml element; this is the object which has been allocated by the xml format or using the public no-arg constructor of objectClass().

Returns:

the (uninitialized) object corresponding to this xml element.

Throws:

XmlException

objectClass

public java.lang.Class objectClass()

Returns the Java(tm) class corresponding to this XML element; the class is identified by the tag name of this xml element or the "j:class" attribute when present.

Returns:

this XML element's corresponding class.

formatter

public ContentHandler formatter()

Returns the content handler used during serialization (typically a WriterHandler).

Returns:

the content handler receiving the SAX-2 events.

add

public void add(java.lang.Object obj)

Adds the specified object as an anonymous nested element of unknown type.

Parameters:

obj - the object added as nested element or null.

add

public void add(java.lang.Object obj,
                java.lang.String qName)

Adds the specified object as a named nested element of unknown type (null objects are ignored). The nested xml element will contain a "j:class" attribute identifying the object type.

Parameters:

obj - the object added as nested element or null.

qName - the qualified name of the nested element.

add

public void add(java.lang.Object obj,
                java.lang.String qName,
                java.lang.Class clazz)

Adds the specified object as a named nested element of known type (null objects are ignored).

Parameters:

obj - the object added as nested element or null.

qName - the qualified name of the nested element.

clazz - the class identifying the xml format to use.

newAttribute

public TextBuilder newAttribute(java.lang.String name)

Creates a new attribute for this xml element. This method allows for custom attribute formatting. For example:

     // Formats the color RGB value in hexadecimal.
     xml.newAttribute("color").append(_color.getRGB(), 16);
     
     // Formats the error using 4 digits.
     xml.newAttribute("error").append(error, 4, false, false);

Parameters:

name - the attribute name.

Returns:

the text builder to hold the attribute value.

setAttribute

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

Sets the specified CharSequence attribute (null values are ignored).

Parameters:

name - the attribute name.

value - the attribute value or null.

setAttribute

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

Sets the specified String attribute (null values are ignored).

Parameters:

name - the attribute name.

value - the attribute value.

setAttribute

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

Sets the specified boolean attribute.

Parameters:

name - the attribute name.

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 attribute name.

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 attribute name.

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 attribute name.

value - the float value for the specified attribute.

See Also:

/

setAttribute

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

Sets the specified double attribute.

Parameters:

name - the attribute name.

value - the double value for the specified attribute.

See Also:

/

setAttribute

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

Sets the specified Boolean attribute.

Parameters:

name - the name of the attribute.

value - the Boolean value for the specified attribute or null in which case the attribute is not set.

See Also:

getAttribute(String, Boolean)

setAttribute

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

Sets the specified Byte attribute.

Parameters:

name - the name of the attribute.

value - the Byte value for the specified attribute or null in which case the attribute is not set.

See Also:

getAttribute(String, Byte)

setAttribute

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

Sets the specified Short attribute.

Parameters:

name - the name of the attribute.

value - the Short value for the specified attribute or null in which case the attribute is not set.

See Also:

getAttribute(String, Short)

setAttribute

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

Sets the specified Integer attribute.

Parameters:

name - the name of the attribute.

value - the Integer value for the specified attribute or null in which case the attribute is not set.

See Also:

getAttribute(String, Integer)

setAttribute

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

Sets the specified Long attribute.

Parameters:

name - the name of the attribute.

value - the Long value for the specified attribute or null in which case the attribute is not set.

See Also:

getAttribute(String, Long)

setAttribute

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

Sets the specified Float attribute.

Parameters:

name - the name of the attribute.

value - the Float value for the specified attribute or null in which case the attribute is not set.

See Also:

/

setAttribute

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

Sets the specified Double attribute.

Parameters:

name - the name of the attribute.

value - the Double value for the specified attribute or null in which case the attribute is not set.

See Also:

/

removeAttribute

public void removeAttribute(java.lang.String name)

Removes the specified attribute.

Parameters:

name - the name of the attribute to remove.

parser

public XmlPullParser parser()

Returns the pull parser used during deserialization.

Returns:

the pull parser.

hasNext

public boolean hasNext()

Indicates if more nested elements can be read.

Returns:

true if more nested elements can be read; false otherwise.

getNext

public <T> T getNext()

Returns the object corresponding to the next nested element.

Returns:

the next nested object.

Throws:

java.util.NoSuchElementException - if this.hasNext() == false

get

public <T> T get(java.lang.String qName)

Returns the object corresponding to the next nested element only if it has the specified qualified name.

Parameters:

qName - the nested element qualified name required.

Returns:

the next content object or null if the qName does not match.

Throws:

XmlException - if the specified object has no "j:class" attribute identifying the object type.

get

public <T> T get(java.lang.String qName,
                 java.lang.Class clazz)

Returns the object corresponding to the next nested element only if it has the specified qualified name; the object type is identified by the specified class parameter.

Parameters:

qName - the nested element qualified name required.

clazz - the class identifying the object to return.

Returns:

the next content object or null if the qName does not match.

getAttributes

public Attributes getAttributes()

Returns the attributes for this xml element (parsing or formatting).

Returns:

the attributes mapping.

getAttribute

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

Searches for the attribute having the specified name.

Parameters:

name - the qualified name of the attribute (qName).

Returns:

the value for the specified attribute or null if the attribute is not found.

isAttribute

public boolean isAttribute(java.lang.String name)

Indicates if the specified attribute is present.

Parameters:

name - the qualified name of the attribute (qName).

Returns:

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

getAttribute

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

Returns the specified CharSequence attribute.

Parameters:

name - the name of the attribute.

defaultValue - a default value.

Returns:

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

getAttribute

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

Returns the specified String attribute.

Parameters:

name - the name of the attribute.

defaultValue - a default value.

Returns:

the value 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. /

getAttribute

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

Searches for the specified Boolean attribute.

Parameters:

name - the name of the attribute.

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 java.lang.Byte getAttribute(java.lang.String name,
                                   java.lang.Byte defaultValue)

Searches for the specified Byte attribute.

Parameters:

name - the name of the attribute.

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

Returns:

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

getAttribute

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

Searches for the specified Short attribute.

Parameters:

name - the name of the attribute.

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

Returns:

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

getAttribute

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

Searches for the specified Integer attribute.

Parameters:

name - the name of the attribute.

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

Returns:

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

getAttribute

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

Searches for the specified Long attribute.

Parameters:

name - the name of the attribute.

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 java.lang.Float getAttribute(java.lang.String name,
                                    java.lang.Float defaultValue)

Searches for the specified Float attribute.

Parameters:

name - the name of the attribute.

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 java.lang.Double getAttribute(java.lang.String name,
                                     java.lang.Double defaultValue)

Searches for the specified Double attribute.

Parameters:

name - the name of the attribute.

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. /

getContent

public FastList getContent()

Deprecated. Formats should use getNext() and hasNext() to parse anonymous content and add(Object) to serialize anonymous content.

add

public void add(java.lang.Object obj,
                java.lang.String qName,
                XmlFormat xmlFormat)

Deprecated. Replaced by add(Object, String, Class)

get

public <T> T get(java.lang.String qName,
                 XmlFormat xmlFormat)

Deprecated. Replaced by get(String, Class)