org.koala.koalaxml
Class XML

java.lang.Object
  |
  +--org.koala.koalaxml.XML

public class XML

extends java.lang.Object

koala XML class provides a simple way to handle and parse xml data. Its purpose is to be used as a property or parameter/return type.
In this version support is included to handle attributes, nested tags, various types of values (including dates).

Here is a brief example of how to parse and print a xml:

String text = "<xml><TagA att1 = 'hi att' att2='' att3='<%System.out.println(someThingToPrint);%>'>value of tagA</TagA>" +
"<TagB><TagC>value of tagC</TagC></TagB><TagD><%String coco=\"<Tag>I can put whatever i want in a scriptlet</Tag>\";%></TagD></xml>";

// to parse it and create an XML object out of the text
XML xml = new XML(text);

// now lets print the xml
System.out.println(xml.toString());


Constructor Summary

XML()
Creates an empty XML object.

XML(java.lang.String xml)
Creates a new XML object by parsing the given string, take note that this is a non-validating parser and it could parse invalid XML.

Method Summary

void	addSibling(org.koala.koalaxml.XML sibling) Adds a new tag as the last child of the root one.
void	deleteSibling() Deletes the sibling at the current position
void	deleteSibling(java.lang.String name) Deletes the first sibling from the current position that has the given name and positions on the next child.
boolean	equals(java.lang.Object xml) Compares the XML object with another one
boolean	getAttributeBoolean(java.lang.String attributeName) Returns the boolean value of the given attribute of the root tag.
boolean	getAttributeBoolean(java.lang.String attributeName, boolean defaultValue)
double	getAttributeDouble(java.lang.String attributeName) Returns the double value of the given attribute of the root tag.
double	getAttributeDouble(java.lang.String attributeName, double defaultValue)
java.util.GregorianCalendar	getAttributeGregorianCalendar(java.lang.String attributeName) Returns the GregorianCalendar (date) value of the given attribute of the root tag.
java.util.GregorianCalendar	getAttributeGregorianCalendar(java.lang.String attributeName, java.util.GregorianCalendar defaultValue)
int	getAttributeInt(java.lang.String attributeName) Returns the integer value of the given attribute of the root tag.
int	getAttributeInt(java.lang.String attributeName, int defaultValue)
long	getAttributeLong(java.lang.String attributeName) Returns the long value of the given attribute of the root tag.
long	getAttributeLong(java.lang.String attributeName, long defaultValue)
java.lang.String	getAttributeScriptlet(java.lang.String attributeName) Returns the string value of the given attribute of the root tag, striping the sorrounding <% and %>.
java.lang.String	getAttributeScriptlet(java.lang.String attributeName, java.lang.String defaultValue)
java.lang.String	getAttributeString(java.lang.String attributeName) Returns the string value of the given attribute of the root tag.
java.lang.String	getAttributeString(java.lang.String attributeName, java.lang.String defaultValue)
java.lang.String	getName() Returns the name of the root tag
boolean	getValueBoolean() Returns the boolean value of the root tag.
double	getValueDouble() Returns the double value of the root tag
java.util.GregorianCalendar	getValueGregorianCalendar() Returns the GregorianCalendar (date) value of the root tag.
int	getValueInt() Returns the integer value of the root tag
long	getValueLong() Returns the long value of the root tag
java.lang.String	getValueScriptlet() Returns the value of the root element and strips the <% and %> that sorrounds scriptlets
java.lang.String	getValueString() Returns the value of the root element
boolean	hasMoreSiblings() Returns true if there is a sibling at the current position.
java.util.Vector	listAttributes() Returns a vector containing the names of all the attributes of the root tag
org.koala.koalaxml.XML	nextSibling() Returns the sibling at the current position
org.koala.koalaxml.XML	nextSibling(java.lang.String name) Returns the first sibling that has the given name, searching from the current position in a circular way (restarting from the beginning if no one is found).
void	setAttributeBoolean(java.lang.String attributeName, boolean value) Changes or sets the value of a given attribute in the root tag.
void	setAttributeDouble(java.lang.String attributeName, double value) Changes or sets the value of a given attribute in the root tag.
void	setAttributeGregorianCalendar(java.lang.String attributeName, java.util.GregorianCalendar value) Changes or sets the value of a given attribute in the root tag.
void	setAttributeInt(java.lang.String attributeName, int value) Changes or sets the value of a given attribute in the root tag.
void	setAttributeLong(java.lang.String attributeName, long value) Changes or sets the value of a given attribute in the root tag.
void	setAttributeString(java.lang.String attributeName, java.lang.String value) Changes or sets the value of a given attribute in the root tag.
void	setName(java.lang.String name) Changes or sets the name of the root element
void	setValueBoolean(boolean value) Sets the value of the root tag to a given boolean.
void	setValueDouble(double value) Sets the value of the root tag to a given double.
void	setValueGregorianCalendar(java.util.GregorianCalendar value) Sets the value of the root tag to a given GregorianCalendar (date).
void	setValueInt(int value) Sets the value of the root tag to a given integer.
void	setValueLong(long value) Sets the value of the root tag to a given long.
void	setValueString(java.lang.String value) Sets the value of the root tag to a given string.
void	top() Moves the position to the first child of the root element
java.lang.String	toString() Returns a string representation of the XML object, indented and with tag and attribute names in capital letters.

Methods inherited from class java.lang.Object

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

Constructor Detail

XML

public XML()

Creates an empty XML object. It represents the root tag and you MUST give it a name using setName() before further use.

XML

public XML(java.lang.String xml)
    throws XMLParseException

Creates a new XML object by parsing the given string, take note that this is a non-validating parser and it could parse invalid XML. The XML must have a root tag and it cannot contain empty tags (as in <br/>).

Parameters:

xml - The string containing the xml data

Throws:

XMLParseException - If an error that prevents parsing is found

Method Detail

hasMoreSiblings

public boolean hasMoreSiblings()

Returns true if there is a sibling at the current position. This method is meant to be used jointly with nextSibling() to iterate on the siblings of the current tag.

Returns:

True if there is a sibling to be read at the current position, false otherwise

nextSibling

public org.koala.koalaxml.XML nextSibling()
                                   throws java.lang.IndexOutOfBoundsException

Returns the sibling at the current position

Returns:

A XML object containing the sibling tag

Throws:

java.lang.IndexOutOfBoundsException - If there is no sibling at the current position (meaning its beyond the last one)

addSibling

public void addSibling(org.koala.koalaxml.XML sibling)
                throws XMLInvalidTagException,
                       java.lang.NullPointerException

Adds a new tag as the last child of the root one.

Parameters:

sibling - The XML object that contains the info to be added

Throws:

XMLInvalidTagException - If the root tag is a leaf and therefor cannot have children

java.lang.NullPointerException - If the sibling is null

deleteSibling

public void deleteSibling()
                   throws java.lang.IndexOutOfBoundsException

Deletes the sibling at the current position

Throws:

java.lang.IndexOutOfBoundsException - If there is no child at the current position (meaning the root element is a leaf or you are beyond the last sibling)

deleteSibling

public void deleteSibling(java.lang.String name)

Deletes the first sibling from the current position that has the given name and positions on the next child. It performs a full circular search, so it WILL delete a tag thats before your position if the name matches and there is no other one with the same one.

Parameters:

name - Name of the tag to be deleted

nextSibling

public org.koala.koalaxml.XML nextSibling(java.lang.String name)
                                   throws java.lang.NullPointerException

Returns the first sibling that has the given name, searching from the current position in a circular way (restarting from the beginning if no one is found).

Parameters:

name - Name to be found

Returns:

An XML object containing the sibling or null if no one matched

Throws:

java.lang.NullPointerException - If no name is given (either null or "")

top

public void top()

Moves the position to the first child of the root element

toString

public java.lang.String toString()

Returns a string representation of the XML object, indented and with tag and attribute names in capital letters.

Overrides:

toString in class java.lang.Object

Returns:

The string containing the xml data

listAttributes

public java.util.Vector listAttributes()

Returns a vector containing the names of all the attributes of the root tag

Returns:

Vector of strings

getName

public java.lang.String getName()

Returns the name of the root tag

Returns:

Name of the root tag (in uppercase)

setName

public void setName(java.lang.String name)

Changes or sets the name of the root element

Parameters:

name - New name

getValueString

public java.lang.String getValueString()

Returns the value of the root element

Returns:

A string containing the tag value, or null if its not a leaf

getValueScriptlet

public java.lang.String getValueScriptlet()
                                   throws XMLInvalidTypeException

Returns the value of the root element and strips the <% and %> that sorrounds scriptlets

Returns:

The root tag value without <% and %>

Throws:

XMLInvalidTypeException - If the tag value is not a scriptlet code

getValueInt

public int getValueInt()
                throws java.lang.NullPointerException,
                       XMLInvalidTypeException

Returns the integer value of the root tag

Returns:

int value of the root tag

Throws:

java.lang.NullPointerException - If the tag is not a leaf and therefor dont have a value

XMLInvalidTypeException - If the value cannot be parsed to an int

getValueLong

public long getValueLong()
                  throws java.lang.NullPointerException,
                         XMLInvalidTypeException

Returns the long value of the root tag

Returns:

long value of the root tag

Throws:

java.lang.NullPointerException - If the tag is not a leaf and therefor dont have a value

XMLInvalidTypeException - If the value cannot be parsed to a long

getValueDouble

public double getValueDouble()
                      throws java.lang.NullPointerException,
                             XMLInvalidTypeException

Returns the double value of the root tag

Returns:

double value of the root tag

Throws:

java.lang.NullPointerException - If the tag is not a leaf and therefor dont have a value

XMLInvalidTypeException - If the value cannot be parsed to a double

getValueGregorianCalendar

public java.util.GregorianCalendar getValueGregorianCalendar()
                                                      throws java.lang.NullPointerException,
                                                             XMLInvalidTypeException

Returns the GregorianCalendar (date) value of the root tag. Dates are represented as mm-dd-yyyy hh:mm:ss strings in the toString() representation of the XML.

Returns:

GregorianCalendar value of the root tag

Throws:

java.lang.NullPointerException - If the tag is not a leaf and therefor dont have a value

XMLInvalidTypeException - If the value cannot be parsed to a GregorianCalendar

getValueBoolean

public boolean getValueBoolean()
                        throws java.lang.NullPointerException,
                               XMLInvalidTypeException

Returns the boolean value of the root tag. Booleans are represented as 1 (true) or 0 (false) in the toString() form of the XML.

Returns:

boolean value of the root tag

Throws:

java.lang.NullPointerException - If the tag is not a leaf and therefor dont have a value

XMLInvalidTypeException - If the value cannot be parsed to a boolean

setValueString

public void setValueString(java.lang.String value)
                    throws java.lang.NullPointerException

Sets the value of the root tag to a given string.

Parameters:

value - New value

Throws:

java.lang.NullPointerException - If the value is null

setValueInt

public void setValueInt(int value)

Sets the value of the root tag to a given integer.

Parameters:

value - New int value

setValueLong

public void setValueLong(long value)

Sets the value of the root tag to a given long.

Parameters:

value - New long value

setValueDouble

public void setValueDouble(double value)

Sets the value of the root tag to a given double.

Parameters:

value - New double value

setValueGregorianCalendar

public void setValueGregorianCalendar(java.util.GregorianCalendar value)
                               throws java.lang.NullPointerException,
                                      java.lang.Exception

Sets the value of the root tag to a given GregorianCalendar (date). Dates are represented as mm-dd-yyyy hh:mm:ss strings in the toString() representation of the XML.

Parameters:

value - New GregorianCalendar value

Throws:

java.lang.NullPointerException - If the value is null

java.lang.Exception - Very rare, report if thrown

setValueBoolean

public void setValueBoolean(boolean value)

Sets the value of the root tag to a given boolean. Booleans are represented as 1 (true) or 0 (false) in the toString() representation of XML.

Parameters:

value - New boolean value

getAttributeString

public java.lang.String getAttributeString(java.lang.String attributeName,
                                           java.lang.String defaultValue)
                                    throws XMLInvalidTypeException,
                                           java.lang.NullPointerException

XMLInvalidTypeException

java.lang.NullPointerException

getAttributeString

public java.lang.String getAttributeString(java.lang.String attributeName)
                                    throws java.lang.NullPointerException

Returns the string value of the given attribute of the root tag.

Parameters:

attributeName - Name of the attribute

Returns:

Attribute value or "" if it doesnt exists in the tag

Throws:

java.lang.NullPointerException - If no name is specified (either by providing null or "")

getAttributeScriptlet

public java.lang.String getAttributeScriptlet(java.lang.String attributeName,
                                              java.lang.String defaultValue)
                                       throws XMLInvalidTypeException,
                                              java.lang.NullPointerException

XMLInvalidTypeException

java.lang.NullPointerException

getAttributeScriptlet

public java.lang.String getAttributeScriptlet(java.lang.String attributeName)
                                       throws XMLInvalidTypeException,
                                              java.lang.NullPointerException

Returns the string value of the given attribute of the root tag, striping the sorrounding <% and %>.

Parameters:

attributeName - Attribute name

Returns:

Attribute value

Throws:

XMLInvalidTypeException - If attribute value is not a scriptlet

java.lang.NullPointerException - If attribute name is null or empty

getAttributeInt

public int getAttributeInt(java.lang.String attributeName,
                           int defaultValue)
                    throws XMLInvalidTypeException,
                           java.lang.NullPointerException

XMLInvalidTypeException

java.lang.NullPointerException

getAttributeInt

public int getAttributeInt(java.lang.String attributeName)
                    throws XMLInvalidTypeException,
                           java.lang.NullPointerException

Returns the integer value of the given attribute of the root tag.

Parameters:

attributeName - Name of the attribute

Returns:

Attribute int value

Throws:

java.lang.NullPointerException - If no name is specified (either by providing null or "")

XMLInvalidTypeException - If the value cannot be parsed as an integer

getAttributeLong

public long getAttributeLong(java.lang.String attributeName,
                             long defaultValue)
                      throws XMLInvalidTypeException,
                             java.lang.NullPointerException

XMLInvalidTypeException

java.lang.NullPointerException

getAttributeLong

public long getAttributeLong(java.lang.String attributeName)
                      throws XMLInvalidTypeException,
                             java.lang.NullPointerException

Returns the long value of the given attribute of the root tag.

Parameters:

attributeName - Name of the attribute

Returns:

Attribute long value

Throws:

java.lang.NullPointerException - If no name is specified (either by providing null or "")

XMLInvalidTypeException - If the value cannot be parsed as a long

getAttributeDouble

public double getAttributeDouble(java.lang.String attributeName,
                                 double defaultValue)
                          throws XMLInvalidTypeException,
                                 java.lang.NullPointerException

XMLInvalidTypeException

java.lang.NullPointerException

getAttributeDouble

public double getAttributeDouble(java.lang.String attributeName)
                          throws XMLInvalidTypeException,
                                 java.lang.NullPointerException

Returns the double value of the given attribute of the root tag.

Parameters:

attributeName - Name of the attribute

Returns:

Attribute double value

Throws:

java.lang.NullPointerException - If no name is specified (either by providing null or "")

XMLInvalidTypeException - If the value cannot be parsed as a double

getAttributeGregorianCalendar

public java.util.GregorianCalendar getAttributeGregorianCalendar(java.lang.String attributeName,
                                                                 java.util.GregorianCalendar defaultValue)
                                                          throws XMLInvalidTypeException,
                                                                 java.lang.NullPointerException

XMLInvalidTypeException

java.lang.NullPointerException

getAttributeGregorianCalendar

public java.util.GregorianCalendar getAttributeGregorianCalendar(java.lang.String attributeName)
                                                          throws XMLInvalidTypeException,
                                                                 java.lang.NullPointerException

Returns the GregorianCalendar (date) value of the given attribute of the root tag. Dates are represented as mm-dd-yyyy hh:mm:ss strings in the toString() representation of the XML.

Parameters:

attributeName - Name of the attribute

Returns:

Attribute GregorianCalendar value

Throws:

java.lang.NullPointerException - If no name is specified (either by providing null or "")

XMLInvalidTypeException - If the value cannot be parsed as a GregorianCalendar

getAttributeBoolean

public boolean getAttributeBoolean(java.lang.String attributeName,
                                   boolean defaultValue)
                            throws XMLInvalidTypeException,
                                   java.lang.NullPointerException

XMLInvalidTypeException

java.lang.NullPointerException

getAttributeBoolean

public boolean getAttributeBoolean(java.lang.String attributeName)
                            throws XMLInvalidTypeException,
                                   java.lang.NullPointerException

Returns the boolean value of the given attribute of the root tag. Booleans are represented as 1 (true) or 0 (false) in the toString() representation of XML.

Parameters:

attributeName - Name of the attribute

Returns:

Attribute boolean value

Throws:

java.lang.NullPointerException - If no name is specified (either by providing null or "")

XMLInvalidTypeException - If the value cannot be parsed as a boolean

setAttributeString

public void setAttributeString(java.lang.String attributeName,
                               java.lang.String value)
                        throws java.lang.NullPointerException

Changes or sets the value of a given attribute in the root tag.

Parameters:

attributeName - Attribute name

value - New value

Throws:

java.lang.NullPointerException - If the name is not specified (either by providing null or "") or if the value is null

setAttributeInt

public void setAttributeInt(java.lang.String attributeName,
                            int value)
                     throws java.lang.NullPointerException

Changes or sets the value of a given attribute in the root tag.

Parameters:

attributeName - Attribute name

value - New value

Throws:

java.lang.NullPointerException - If the name is not specified (either by providing null or "")

setAttributeLong

public void setAttributeLong(java.lang.String attributeName,
                             long value)
                      throws java.lang.NullPointerException

Changes or sets the value of a given attribute in the root tag.

Parameters:

attributeName - Attribute name

value - New value

Throws:

java.lang.NullPointerException - If the name is not specified (either by providing null or "")

setAttributeDouble

public void setAttributeDouble(java.lang.String attributeName,
                               double value)
                        throws java.lang.NullPointerException

Changes or sets the value of a given attribute in the root tag.

Parameters:

attributeName - Attribute name

value - New value

Throws:

java.lang.NullPointerException - If the name is not specified (either by providing null or "")

setAttributeGregorianCalendar

public void setAttributeGregorianCalendar(java.lang.String attributeName,
                                          java.util.GregorianCalendar value)
                                   throws java.lang.NullPointerException,
                                          java.lang.Exception

Changes or sets the value of a given attribute in the root tag. Dates are represented as mm-dd-yyyy hh:mm:ss strings in the toString() representation of the XML.

Parameters:

attributeName - Attribute name

value - New value

Throws:

java.lang.NullPointerException - If the name is not specified (either by providing null or "") or if the value is null

java.lang.Exception - Very rare, report if thrown

setAttributeBoolean

public void setAttributeBoolean(java.lang.String attributeName,
                                boolean value)
                         throws java.lang.NullPointerException

Changes or sets the value of a given attribute in the root tag. Booleans are represented as 1 (true) or 0 (false) in the toString() representation of XML.

Parameters:

attributeName - Attribute name

value - New value

Throws:

java.lang.NullPointerException - If the name is not specified (either by providing null or "")

equals

public boolean equals(java.lang.Object xml)

Compares the XML object with another one

Overrides:

equals in class java.lang.Object

Parameters:

xml - Object to compare to

Returns:

True if the parameter is a XML object and contains the exact same information, false otherwise