getName

setName

Set the Name of the element. This method is intended primarily to be utilized to configure a newly instantiated element before adding it as a child element to another element. Implementations of this interface that support read-only documents are expected to throw UnsupportedOperationException from this method if the document (or this element) is in a read-only state. If this XmlElement has a parent XmlElement, then the implementation of this interface is permitted to throw UnsupportedOperationException from this method. This results from typical document implementations in which the name of an element that is a child of another element is immutable; the W3C DOM interfaces are one example.

getElementList

Get the list of all child elements. The contents of the list implement the XmlValue interface. If this XmlElement is mutable, then the list returned from this method is expected to be mutable as well. An element should be fully configured before it is added to the list:

The List implementation is permitted (and most implementations are expected) to instantiate its own copy of any XmlElement objects added to it.

Certain properties of an element (such as Name) may not be settable once the element has been added. (See the comments for the setName method.)

Returns:

a List containing all elements of this XmlElement

getElement

Get a child element. This is a convenience method. Elements are accessed and manipulated via the list returned from getElementList(). If multiple child elements exist that have the specified name, then the behavior of this method is undefined, and it is permitted to return any one of the matching elements, to return null, or to throw an arbitrary runtime exception.

Returns:

the specified element as an object implementing XmlElement, or null if the specified child element does not exist

findElement

Find a child element with the specified '/'-delimited path. This is based on a subset of the XPath specification, supporting:

Leading '/' to specify root

Use of '/' as a path delimiter

Use of '..' to specify parent

This is a convenience method. Elements are accessed and manipulated via the list returned from getElementList(). If multiple child elements exist that have the specified name, then the behavior of this method is undefined, and it is permitted to return any one of the matching elements, to return null, or to throw an arbitrary runtime exception.

Parameters:

sPath - element path

Returns:

the specified element as an object implementing XmlElement, or null if the specified child element does not exist

getSafeElement

Return the specified child element using the same path notation as supported by findElement, but return a read-only element if the specified element does not exist. This method never returns null. This is a convenience method. Elements are accessed and manipulated via the list returned from getElementList(). If multiple child elements exist that have the specified name, then the behavior of this method is undefined, and it is permitted to return any one of the matching elements, to return null, or to throw an arbitrary runtime exception.

Parameters:

sPath - element path

Returns:

the specified element (never null) as an object implementing XmlElement for read-only use

ensureElement

Ensure that a child element exists. This is a convenience method. It combines the functionality of findElement() and addElement(). If any part of the path does not exist create new child elements to match the path.

setAttribute

Set an attribute value. If the attribute does not already exist, and the new value is non-null, then the attribute is added and its value is set to the passed value. If the attribute does exist, and the new value is non-null, then the attribute's value is updated to the passed value. If the attribute does exist, but the new value is null, then the attribute and its corresponding value are removed. This is a convenience method. Attributes are accessed and manipulated via the map returned from getAttributeMap.

Parameters:

sName - the name of the attribute

val - the new value for the attribute; null indicates that the attribute should be removed

addAttribute

Provides a means to add a new attribute value. If the attribute of the same name already exists, it is returned, otherwise a new value is created and added as an attribute. This is a convenience method. Attributes are accessed and manipulated via the map returned from getAttributeMap.

getComment

Get the text of any comments that are in the XML element. An element can contain many comments interspersed randomly with textual values and child elements. In reality, comments are rarely used. The purpose of this method and the corresponding mutator are to ensure that if comments do exist, that their text will be accessible through this interface and not lost through a transfer from one instance of this interface to another.

Returns:

the comment text from this element (not including the "") or null if there was no comment

hashCode

int hashCode()

Provide a hash value for this XML element and all of its contained information. Note that this overrides the contract of the hashCode method in the super interface XmlValue. The hash value is defined as a xor of the following: