xtom.parser
Class Element

java.lang.Object
  xtom.parser.Element

public class Element

extends java.lang.Object

Description:Each xml tag is an element. An element can be a parent and can have children elements, and it might also have attributes. Only one element can be a root element.
LinkedLists are used to hold children Elements and a HashMap to hold Attributes.

Version:

$Revision: 1.1 $

Author:

taras

Field Summary

private java.util.HashMap	attributes Attributes of this element
private boolean	caseSensitive Used to specify whether the names of elements are case sensitive
private java.util.LinkedList	children Children of this Element
private java.lang.String	name name of this element
private Element	parent Parent element - used by the parser
private java.lang.String	value value of this element, null if the element is a parent

Constructor Summary

private	Element()
	Element(java.lang.String name, java.lang.String value) Creates a new Element object. BY DEFAULT - ELEMENT NAMES ARE CASE SENSITIVE The case sensitivity can be turned of by XMLTree.

Method Summary

void	addAttribute(Attribute a) adds an attribute to this element.
void	addChildElement(Element e) adds a child element to this element.
private Element[]	findChildElements(java.lang.String name) Searches the list of the children of this element to find the correct one specified by the name.
Attribute	getAttribute(java.lang.String name) Gets an attribute specified by a name.
java.util.HashMap	getAttributes()
Element[]	getChildren()
Element	getElementByPath(java.lang.String path) This method gets the element according to the path specidied.
protected Element[]	getElements(java.lang.String path) This method is one the does the searching of the Element specified in the path.
Element[]	getElementsByPath(java.lang.String path) This method gets all instances of specified element according to the path specidied.
java.lang.String	getName()
protected Element	getParentElement() Returns the parent Element.
java.lang.String	getValue()
boolean	getValueAsBoolean() Returns value parsed as a boolean.
byte	getValueAsByte() Returns value parsed as a byte.
char	getValueAsCharacter() Returns value parsed as a char.
double	getValueAsDouble() Returns value parsed as a double.
float	getValueAsFloat() Returns value parsed as a float.
int	getValueAsInt() Returns value parsed as an int.
long	getValueAsLong() Returns value parsed as a float.
short	getValueAsShort() Returns value parsed as a short.
boolean	hasAttribute(java.lang.String name) Checks if the attribute exists.
boolean	hasAttributes()
boolean	hasChildren()
boolean	isCaseSensitive()
private boolean	isNameTheSame(java.lang.String eName, java.lang.String tName) This method check if the two string Names are the same, it Check to see if case sensitive is set, and if it is, it converts both names toLowercase.
protected void	setCaseSensitive(boolean caseSensitive) Sets the case sensitivity to all of the children Elements of this element.
protected void	setParentElement(Element parent) Sets the parent for this element, only used by the parser
protected void	setValue(java.lang.String value) This is called by the Parser class, to set the value.
java.lang.String	toString() Outputs the Name and value of the method, and attributes

Methods inherited from class java.lang.Object

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

Field Detail

caseSensitive

private boolean caseSensitive

Used to specify whether the names of elements are case sensitive

parent

private Element parent

Parent element - used by the parser

name

private java.lang.String name

name of this element

value

private java.lang.String value

value of this element, null if the element is a parent

children

private java.util.LinkedList children

Children of this Element

attributes

private java.util.HashMap attributes

Attributes of this element

Constructor Detail

Element

private Element()

Element

public Element(java.lang.String name,
               java.lang.String value)

Creates a new Element object.
BY DEFAULT - ELEMENT NAMES ARE CASE SENSITIVE
The case sensitivity can be turned of by XMLTree.

Parameters:

name - the name of this element, as it appears between tags, case sensitive.

value - the value.

Throws:

java.lang.IllegalArgumentException - if name is null

Method Detail

setParentElement

protected void setParentElement(Element parent)

Sets the parent for this element, only used by the parser

Parameters:

parent -

getParentElement

protected Element getParentElement()

Returns the parent Element. if the parent Element is null, this element is the Element root.
This method is only used by the Parser Class.
It may return a null, even if the Element is a child of another Element.
USE AT YOUR OWN RISK

Returns:

addChildElement

public void addChildElement(Element e)

adds a child element to this element.

Parameters:

e - Element. must not be null and the name must not be null.

addAttribute

public void addAttribute(Attribute a)

adds an attribute to this element. If the attribute of the same name exists, the value will be overriden.

Parameters:

a - Attribute. must not be null and the name must not be null.

getChildren

public Element[] getChildren()

Returns:

Children elements of this element, or empty array if there no children elements.

getAttributes

public java.util.HashMap getAttributes()

Returns:

The attributes of this element or empty HashMap if there are none.

getName

public java.lang.String getName()

Returns:

Returns the name.

getValue

public java.lang.String getValue()

Returns:

Returns the value.

setValue

protected void setValue(java.lang.String value)

This is called by the Parser class, to set the value.

Parameters:

value -

hasChildren

public boolean hasChildren()

Returns:

True if it has children, false otherwise.

hasAttributes

public boolean hasAttributes()

Returns:

True if it has attributes, false otherwise.

toString

public java.lang.String toString()

Outputs the Name and value of the method, and attributes

See Also:

Object.toString()

getElementByPath

public Element getElementByPath(java.lang.String path)
                         throws MultipleElementInstancesException

This method gets the element according to the path specidied. The path specified must be relative to the element whose getElementByPath method you are invoking.
ie. XML file < tester > ... < test > < one > < two > stuff ... < tester > And you hold the reference to the element whose name is 'test', to get the element named 'two' you would pass this path definition to the method one/two Be very careful, because the method from the XMLTree with a simpilar name uses the the path that is relative to the root element, which means that the call to XMLTree.getElementByPath() is relative to the rootElement, which is the same thing as calling XMLTree.getRootElement().getElementByPath().

Parameters:

path - The path to the element in search for.

Returns:

The element or throws an UnknownElement exception if the element is not there.

Throws:

MultipleElementInstancesException - if there are more then one instance of the element that was requested by the path. This usually means that developer should use getElements method instead.

java.lang.IllegalArgumentException - The path argument was null.

UnknownElementException - if it can not find an element under the name specified.

getElementsByPath

public Element[] getElementsByPath(java.lang.String path)
                            throws MultipleElementInstancesException

This method gets all instances of specified element according to the path specidied. The path specified must be relative to the element whose getElementsByPath method you are invoking.
ie. XML file < tester > ... < test > < one > < two > stuff < two > stuff 2 ... < tester > And you hold the reference to the element whose name is 'test', to get the element named 'two' you would pass this path definition to the method one/two Be very careful, because the method from the XMLTree with a simpilar name uses the the path that is relative to the root element, which means that the call to XMLTree.getElementsByPath() is relative to the rootElement, which is the same thing as calling XMLTree.getRootElement().getElementsByPath().
IMPORTANT: The element that you are holding the reference to can never search for itself. To get the root element use XMLTree.getRootElement() method.

Parameters:

path - The path to the element in search for.

Returns:

The element or throws an UnknownElement exception if the element is not there.

Throws:

UnknownElementException - if it can not find an element under the name specified.

java.lang.IllegalArgumentException - The path argument was null.

MultipleElementInstancesException

getElements

protected Element[] getElements(java.lang.String path)

This method is one the does the searching of the Element specified in the path. This method gets called by getElementsByPath method.

Parameters:

path - The path.

Returns:

Array of elements.

findChildElements

private Element[] findChildElements(java.lang.String name)

Searches the list of the children of this element to find the correct one specified by the name. If the element does not exist there, it will return an empty array of elements.

Parameters:

name - The name of the element we are looking for.

Returns:

An array of elements, if there is more than one, or an empty array if there none.

isNameTheSame

private boolean isNameTheSame(java.lang.String eName,
                              java.lang.String tName)

This method check if the two string Names are the same, it Check to see if case sensitive is set, and if it is, it converts both names toLowercase.

Parameters:

eName -

tName -

Returns:

True if names are the same, false otherwise.

isCaseSensitive

public boolean isCaseSensitive()

Returns:

Returns the caseSensitive.

setCaseSensitive

protected void setCaseSensitive(boolean caseSensitive)

Sets the case sensitivity to all of the children Elements of this element. This method is only accessed by the XMLTree.

Parameters:

caseSensitive - The caseSensitive to set.

getValueAsInt

public int getValueAsInt()

Returns value parsed as an int. If the parsing fails it will throw a NumberFormatException

Throws:

java.lang.NumberFormatException - is it can not parse the value.

getValueAsFloat

public float getValueAsFloat()

Returns value parsed as a float. If the parsing fails it will throw a NumberFormatException

Throws:

java.lang.NumberFormatException - is it can not parse the value.

getValueAsDouble

public double getValueAsDouble()

Returns value parsed as a double. If the parsing fails it will throw a NumberFormatException

Throws:

java.lang.NumberFormatException - is it can not parse the value.

getValueAsShort

public short getValueAsShort()

Returns value parsed as a short. If the parsing fails it will throw a NumberFormatException

Throws:

java.lang.NumberFormatException - is it can not parse the value.

getValueAsLong

public long getValueAsLong()

Returns value parsed as a float. If the parsing fails it will throw a NumberFormatException

Throws:

java.lang.NumberFormatException - is it can not parse the value.

getValueAsByte

public byte getValueAsByte()

Returns value parsed as a byte. If the parsing fails it will throw a NumberFormatException

Throws:

java.lang.NumberFormatException - is it can not parse the value.

getValueAsBoolean

public boolean getValueAsBoolean()

Returns value parsed as a boolean. If the parsing fails it will throw a NumberFormatException If the string = 'true', returns true, Returns false otherwise.

Throws:

java.lang.NumberFormatException - is it can not parse the value.

See Also:

Boolean.valueOf(java.lang.String)

getValueAsCharacter

public char getValueAsCharacter()

Returns value parsed as a char. If the parsing fails it will throw a NumberFormatException

Throws:

java.lang.NumberFormatException - is it can not parse the value.

getAttribute

public Attribute getAttribute(java.lang.String name)

Gets an attribute specified by a name.

Parameters:

name - The name of the attribute

Returns:

The Attribute or throws an exception.

Throws:

UnknownAttributeException - if name is null or there is no such attribute.

hasAttribute

public boolean hasAttribute(java.lang.String name)

Checks if the attribute exists. if name is null, returns false.

Parameters:

name - The name of the attribute.

Returns: