com.softcorporation.xmllight
Class Element

java.lang.Object
  |
  +--com.softcorporation.xmllight.Element

All Implemented Interfaces:

java.io.Serializable

public class Element

extends java.lang.Object

implements java.io.Serializable

XML Light Element. Represents any element in XML document, including the root element. An element is a pair of identically named start and end tags. (<text> and </text>). It may have a content. Here is a sample of element "text", with content "Text goes here." and attribute "language" with value "English".
<text language="English">
Text goes here.
</text>
A slash (/) in the end of start tag means that this element does not have a content and it is closed: <text language="English"/>.

See Also:

Serialized Form

Field Summary

int	errorCode Error Code.
boolean	validate Validation flag.

Constructor Summary

Element()
Constructor.

Element(Element elem)
Constructor.

Element(java.lang.String name)
Constructor.

Method Summary

void	addCData(java.lang.String cdata) Adds a CDATA section to the end of the existing content of the Element.
void	addComment(java.lang.String comment) Adds a comment to the end of the existing content of the Element.
void	addCont(Element elem) Adds a string representation of the Element elem to the end of the content of the Element.
void	addCont(java.lang.String cont) Adds a content to the end of the existing content of the Element.
void	addElem(Element elem) Adds a string representation of the Element elem to the end of the content of the Element.
void	addText(java.lang.String text) Adds a text to the end of the existing content of the Element.
java.lang.String	getAttr(java.lang.String attr) Gets the attribute of the Element by it's name.
java.lang.String	getAttr(java.lang.String attr, java.lang.String defValue) Gets the attribute of the Element by it's name.
java.util.Properties	getAttributes() Returns Properties class containing all attributes of the Element.
Element	getChildElem(java.lang.String elemName) Searches the Element with elemName in the content only among direct children of the Element.
java.lang.String	getChildText() Returns the text presented in whole content of the Element.
java.lang.String	getChildText(boolean decode) Returns the text presented in whole content of the Element.
java.lang.String	getCont() Returns the content of the Element as a String.
Element	getElem() Returns the XMLLight Element from the content.
Element	getElem(java.lang.String elemName) Searches the Element with elemName in the content of the Element.
Element	getFirstElem(java.lang.String elemName) Searches the element in the content starting from the beginning of the content and returns the Element.
java.lang.String	getName() Gets the name of the Element.
int	getPosition() Gets current position in the content of the Element.
int	getPosition(int id) Gets working positions in the content of the Element. Working positions 0 is current position (same like getPosition()). Working positions 1 is a beginning of found Element in the content.
java.lang.String	getText() Returns the text presented in the content of the Element from current position (see getPosition() for more) till the next child Element.
java.lang.String	getText(boolean decode) Returns the text presented in the content of the Element from current position (see getPosition() for more) till the next child Element.
void	insCont(Element elem) Inserts a string representation of the Element elem in the beginning of the content of the Element.
void	insCont(Element elem, int position) Inserts a string representation of the Element elem at the requested position in the content of the Element.
void	insCont(java.lang.String cont) Inserts a string in the beginning of the content of the Element.
void	insCont(java.lang.String cont, int position) Inserts a string at the requested position in the content of the Element.
boolean	isNull() Checks if the Element was just created and has not been set up yet.
void	remAttr(java.lang.String attr) Removes the attribute from the Element.
void	resetPosition() Sets current position to the beginning of the content.
void	setAttr(java.lang.String attr, int value) Sets the attribute of the Element as int.
void	setAttr(java.lang.String attr, java.lang.String value) Sets the attribute of the Element.
void	setAttributes(java.util.Properties attributes) Sets Properties class containing all attributes for the Element.
void	setCont(java.lang.String cont) Sets the content of the Element.
void	setElem(java.lang.String doc) Sets Element from input string representing XML Element.
void	setElem(java.lang.String doc, int start) Creates XMLLight Element from XML document starting from position defined in pos[0].
void	setElem(java.lang.String doc, java.lang.String tag) Sets Element from input string representing XML Element with shift to the beginning of the element in the string.
void	setElem(java.lang.String doc, java.lang.String tag, int start) Sets Element from input string representing XML Element with shift to the beginning of the element in the string.
void	setName(java.lang.String name) Sets the name of the Element.
void	setPosition(int position) Sets current position in the content of the Element.
java.lang.String	toString() Creates String representation of the Element.

Methods inherited from class java.lang.Object

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

Field Detail

validate

public boolean validate

Validation flag. Suppress the validation.
true - perform basic validation (default)
fasle - drop validation

errorCode

public int errorCode

Error Code. Represents the errors.
0 - all right
1 - unexpected error
2 - error while processing the Element
3 - error while modifying the Element

Constructor Detail

Element

public Element()

Constructor. Creates default Element.

Element

public Element(java.lang.String name)

Constructor. Creates Element with name and no content.

Parameters:

name - represents the name of the Element.

Element

public Element(Element elem)

Constructor. Creates new Element from parent Element.

Parameters:

elem - parent Element.

Method Detail

setElem

public void setElem(java.lang.String doc)
             throws XMLLightException

Sets Element from input string representing XML Element. Element reset as new Element if input string = null.

XMLLightException

setElem

public void setElem(java.lang.String doc,
                    int start)
             throws XMLLightException

Creates XMLLight Element from XML document starting from position defined in pos[0]. If malformed XML found then returned Element errorCode equals 2.

Parameters:

doc - the XML document as a string

Returns:

XMLLight Element

XMLLightException

setElem

public void setElem(java.lang.String doc,
                    java.lang.String tag)
             throws XMLLightException

Sets Element from input string representing XML Element with shift to the beginning of the element in the string. Element reset as new Element if input string = null.

Parameters:

tag - tag name

Returns:

-1 - tag not found 0 - tag found, error occured 1 - tag found

XMLLightException

setElem

public void setElem(java.lang.String doc,
                    java.lang.String tag,
                    int start)
             throws XMLLightException

Sets Element from input string representing XML Element with shift to the beginning of the element in the string. Element reset as new Element if input string = null.

Parameters:

tag - tag name

Returns:

-1 - tag not found 0 - tag found, error occured 1 - tag found

XMLLightException

toString

public java.lang.String toString()

Creates String representation of the Element. If the Element is just created and has no name returns empty string.

Overrides:

toString in class java.lang.Object

Returns:

XML Element as a String

getName

public java.lang.String getName()

Gets the name of the Element.

Returns:

XML Element name

setName

public void setName(java.lang.String name)

Sets the name of the Element. If element name is not valid sets errorCode = 3.

Parameters:

name - XML Element name

getAttr

public java.lang.String getAttr(java.lang.String attr)

Gets the attribute of the Element by it's name. XML entities in attribute value are decoded.

Parameters:

attr - Attribute name

Returns:

Attribute value

getAttr

public java.lang.String getAttr(java.lang.String attr,
                                java.lang.String defValue)

Gets the attribute of the Element by it's name. Returns default Value if the attribute is not defined.

Parameters:

attr - Attribute name

Returns:

Attribute value

setAttr

public void setAttr(java.lang.String attr,
                    java.lang.String value)

Sets the attribute of the Element. XML entities in attribute value are encoded. New attribute will be created or existing attribute with the same name will be replaced.

Parameters:

attr - attribute name

value - attribute value

setAttr

public void setAttr(java.lang.String attr,
                    int value)

Sets the attribute of the Element as int. New attribute will be created or existing attribute with the same name will be replaced.

Parameters:

attr - attribute name

value - attribute value

remAttr

public void remAttr(java.lang.String attr)

Removes the attribute from the Element.

Parameters:

attr - attribute name

getAttributes

public java.util.Properties getAttributes()

Returns Properties class containing all attributes of the Element. Attribute name is a Key and Attribute value is a Value. XML entities in attribute value are decoded.

Returns:

attribute value

setAttributes

public void setAttributes(java.util.Properties attributes)

Sets Properties class containing all attributes for the Element. Attribute name is a Key and Attribute value is a Value. XML entities in attribute value are decoded.

Returns:

attribute value

getCont

public java.lang.String getCont()

Returns the content of the Element as a String. Content always has a String value.

Returns:

content of the Element as a String

setCont

public void setCont(java.lang.String cont)

Sets the content of the Element. All existing content replaced. If input equals null then empty string assigned to the content. No error verification provided for a new content.

Parameters:

cont - XML Content as a string

addCont

public void addCont(java.lang.String cont)

Adds a content to the end of the existing content of the Element. No error verification provided for a new content.

Parameters:

cont - XML Content as a string

addCont

public void addCont(Element elem)

Adds a string representation of the Element elem to the end of the content of the Element. No error verification provided for a new content. NOTE: Created Element containing recursive Elements cannot be parsed with current version of XMLLight.

Parameters:

elem - XMLLight Element

insCont

public void insCont(java.lang.String cont)

Inserts a string in the beginning of the content of the Element. No error verification provided for a new content.

insCont

public void insCont(java.lang.String cont,
                    int position)

Inserts a string at the requested position in the content of the Element. No error verification provided for a new content.

Parameters:

position - requested position in the content of the Element

insCont

public void insCont(Element elem)

Inserts a string representation of the Element elem in the beginning of the content of the Element. No error verification provided for a new content. NOTE: Created Element containing recursive Elements cannot be parsed with current version of XMLLight.

Parameters:

elem - XMLLight Element

insCont

public void insCont(Element elem,
                    int position)

Inserts a string representation of the Element elem at the requested position in the content of the Element. No error verification provided for a new content.

Parameters:

elem - XMLLight Element

position - requested position in the content of the Element

addElem

public void addElem(Element elem)

Adds a string representation of the Element elem to the end of the content of the Element. No error verification provided for a new content. NOTE: Created Element containing recursive Elements cannot be parsed with current version of XMLLight. May be deprecated This method replaced with addCont(Element elem)

Parameters:

elem - XMLLight Element

addComment

public void addComment(java.lang.String comment)

Adds a comment to the end of the existing content of the Element. No error verification provided for a new content. NOTE: Created Element containing <!-- ... --> section cannot be parsed with current version of XMLLight.

addCData

public void addCData(java.lang.String cdata)

Adds a CDATA section to the end of the existing content of the Element. No error verification provided for a new content. NOTE: Created Element containing <![CDATA[ ... ]]> section cannot be parsed with current version of XMLLight.

addText

public void addText(java.lang.String text)

Adds a text to the end of the existing content of the Element. Mixed content supported. All XML entities are encoded (escaped). If you need to add not encoded text use addCont() instead.

Parameters:

text - text as a string

getText

public java.lang.String getText()

Returns the text presented in the content of the Element from current position (see getPosition() for more) till the next child Element. Current position set to the end of found text. XML entities in text are decoded. Never returns null. Check the errorCode for success.

Returns:

text as a String

getText

public java.lang.String getText(boolean decode)

Returns the text presented in the content of the Element from current position (see getPosition() for more) till the next child Element. Current position set to the end of found text. XML entities in text are not decoded if decode parameter is false. Never returns null. Check the errorCode for success.

Parameters:

decode - defines to decode the text or not

Returns:

text as a String

getChildText

public java.lang.String getChildText()

Returns the text presented in whole content of the Element. XML entities in text are decoded. Current position is not changed. Slower then getText(). Never returns null. Check the errorCode for success.

Returns:

text as a String

getChildText

public java.lang.String getChildText(boolean decode)

Returns the text presented in whole content of the Element. XML entities in text are not decoded if decode parameter is false. Current position is not changed. Never returns null. Check the errorCode for success.

Parameters:

decode - defines to decode the text or not

Returns:

text as a String

getElem

public Element getElem()
                throws XMLLightException

Returns the XMLLight Element from the content. The Element is searched from the current position (see getPosition() for more) and if the Element is found current position set to the end of found Element. Always returns the Element. If the Element was not found in the content then it's isEmpty() is true.

Returns:

XMLLight Element

XMLLightException

getElem

public Element getElem(java.lang.String elemName)
                throws XMLLightException

Searches the Element with elemName in the content of the Element. The Element is searched from the current position (see getPosition() for more) and if the Element is found current position set to the end of found Element. The difference with getChildElem(elemName) is that it searches all descendant Elements. This method works simirar to XSL matching with "//" and it works fast. Always returns the Element. If the Element is not found, the value of isEmpty() method of returned Element is true.

Parameters:

elemName - the name of searched element

Returns:

XMLLight Element

XMLLightException

getFirstElem

public Element getFirstElem(java.lang.String elemName)
                     throws XMLLightException

Searches the element in the content starting from the beginning of the content and returns the Element. The method works simirar to getElem(String elemName). Always returns the Element. If the Element is not found, the value of isEmpty() method of returned Element is true.

Parameters:

elemName - the name of searched element

Returns:

XMLLight Element

XMLLightException

getChildElem

public Element getChildElem(java.lang.String elemName)
                     throws XMLLightException

Searches the Element with elemName in the content only among direct children of the Element. The Element is searched from the current position (see getPosition() for more) and if the Element is found current position set to the end of found Element. When this method called the current position must not be inside children Element. Slower then getElem(String elemName) method. Always returns the Element. If the Element is not found, the value of isEmpty() method of returned Element is true.

Parameters:

elemName - the name of searched element

Returns:

XMLLight Element

XMLLightException

resetPosition

public void resetPosition()

Sets current position to the beginning of the content. Same as setPosition(0).

setPosition

public void setPosition(int position)

Sets current position in the content of the Element. see getPosition() for more.

Parameters:

position - the current position

getPosition

public int getPosition()

Gets current position in the content of the Element. Current position defines a start point for seraching the included Elements in the content. When the Element is found the current position set at the first character after the end of found Element. Newly created Element current position equals 0.

Returns:

current position as integer

getPosition

public int getPosition(int id)

Gets working positions in the content of the Element.
Working positions 0 is current position (same like getPosition()).
Working positions 1 is a beginning of found Element in the content. If Element or Text was not found equals -1.
Working positions 2 is an end of found Element in the content. Undefined if element was not found.
Working positions are stored in int array pos[3].

Parameters:

id - the id of working position

Returns:

working position as integer

isNull

public boolean isNull()

Checks if the Element was just created and has not been set up yet. Useful to check if the Element was found in the content (see getElem()) for more. If the Element was not found returns true, otherwise false.

Returns:

true if the Element is not set up.