Package com.nfbsoftware.xml

Interface IXmlElement

All Superinterfaces:

Serializable

All Known Subinterfaces:

IXmlDocument

All Known Implementing Classes:

XmlDocument

public interface IXmlElement
extends Serializable

Author:

Brendan Clemenzi

Method Summary

Modifier and Type	Method	Description
void	addChild(IXmlElement child)	This appends an IXmlElement object to the this element.
void	addToChild(IXmlElement child, String parent)	This method appends the input IXmlElement object to the element identified by the path.
IXmlDocument	clone(boolean deep)	This method creates a copy of the existing IXmlElement object, including a clone of every child if and only if the deep parameter is set to be true.
IXmlElement	createChild(String childName)	This method creates a new child under this element with an element name equal to the childName parameter.
IXmlElement	createChild(String childName, String value)	This method creates a new child under this element with an element name equal to the childName parameter and a value equal to the value parameter.
IXmlElement	createChildren(String fullChildPath)	This method creates aall of the child elements referenced by the child path.
String	getAttribute(String name)	This method returns the attribute's value according to input attribute name.
Collection<String>	getAttributeNames()	This method returns all of the attribute names of the current node
Collection<String>	getAttributeValues()	This method returns all of the attribute values of the current node.
String	getCDATASection(String childName)	This method returns the descendent's value.
IXmlElement	getChild(int index)	This method returns an IXmlElement object that contains the child element at the given index.
IXmlElement	getChild(String childName)	This method returns the first child element identified by the path.
String	getChildAttribute(String child, String attr)	This method returns the attribute value of a child node.
int	getChildCount()	This method returns the number of children.
Collection<IXmlElement>	getChildren()	This method returns all of this element's children.
Collection<IXmlElement>	getChildrenByName(String name)	This method returns all of this element's children with the given name.
String	getChildValue(String childName)	This method returns the descendent's value.
Document	getDocument()
String	getName()	This method returns the name of this element
Node	getRootNode()
String	getValue()	This method returns the element's value
void	removeAttribute(String attributeName)	This method removes an attribute from this element..
IXmlElement	removeChild(int index)	This method removes the index-th child element.
IXmlElement	removeChild(String childName)	This method removes a child element.
void	removeChildAttribute(String child, String attributeName)	This method removes an attribute from a child element
List<IXmlElement>	removeChildrenWithXpath(String xpathQuery)	This method removes all child elements with the given xpath query.
IXmlElement	removeChildWithXpath(String xpathQuery)	This method removes a single child element with the given xpath query.
void	replaceAllChildren(IXmlElement parent)	Removes all of the element's children and adds all of the children of the provided parent element.
IXmlElement	replaceChild(int index, IXmlElement newChild)	This method replaces the index-th element with the new element.
IXmlElement	replaceChild(String childName, IXmlElement newChild)	This method replaces the child element with the new element.
IXmlElement	selectChild(String xpathQuery)
List<IXmlElement>	selectChildren(String xpathQuery)
IXmlElement	setAttribute(String attributeName, String value)	Sets the value of an attribute of this element.
void	setCDATASection(String value)	Sets this element's CDATA value
void	setValue(String value)	Sets this element's value
void	write(File file)	This method saves the stored XML document as a file.
void	write(OutputStream output)	This methods writes the content of the current XML document to the output stream.

Method Details

addChild

void addChild(IXmlElement child)
       throws XmlDocumentCheckedException

This appends an IXmlElement object to the this element.

Parameters:

child - the child node to append

Throws:

XmlDocumentCheckedException - If the XML is invalid.

addToChild

void addToChild(IXmlElement child,
 String parent)
         throws XmlDocumentCheckedException

This method appends the input IXmlElement object to the element identified by the path.

Parameters:

child - the child node to append.

parent - a string contains the path to the element to be appended to.

Throws:

XmlDocumentCheckedException - If the XML is invalid.

clone

IXmlDocument clone(boolean deep)
            throws XmlDocumentCheckedException

This method creates a copy of the existing IXmlElement object, including a clone of every child if and only if the deep parameter is set to be true.

Parameters:

deep - Indicates whether it is a deep clone or just cloning the node

Returns:

IXmlDocument the new document object

Throws:

XmlDocumentCheckedException - If the XML is invalid.

createChild

IXmlElement createChild(String childName)
                 throws XmlDocumentCheckedException

This method creates a new child under this element with an element name equal to the childName parameter. The returned element is referenced directly by this element's document after the operation.

Parameters:

childName - the child name

Returns:

XmlDocument Contains the newly created child node

Throws:

XmlDocumentCheckedException - If the XML is invalid.

createChild

IXmlElement createChild(String childName,
 String value)
                 throws XmlDocumentCheckedException

This method creates a new child under this element with an element name equal to the childName parameter and a value equal to the value parameter. The returned element is referenced directly by this element's document after the operation.

Parameters:

childName - the child name

value - the child value

Returns:

XmlDocument Contains the newly created child node

Throws:

XmlDocumentCheckedException - If the XML is invalid.

createChildren

IXmlElement createChildren(String fullChildPath)
                    throws XmlDocumentCheckedException

This method creates aall of the child elements referenced by the child path. The returned element is referenced directly by this element's document after the operation succeeds.

Parameters:

fullChildPath - the full list of elements to creat in XPath format (e.g., REQUEST/HEADER/INFO)

Returns:

IXmlElement the first element in the child path

Throws:

XmlDocumentCheckedException - If the XML is invalid.

getAttribute

String getAttribute(String name)
             throws XmlDocumentCheckedException

This method returns the attribute's value according to input attribute name.

Parameters:

name - Attribute name

Returns:

A string contains attribute value

Throws:

XmlDocumentCheckedException - If the XML is invalid.

getAttributeNames

Collection<String> getAttributeNames()
                              throws XmlDocumentCheckedException

This method returns all of the attribute names of the current node

Returns:

a Collection of attribute names

Throws:

XmlDocumentCheckedException - If the XML is invalid.

getAttributeValues

Collection<String> getAttributeValues()
                               throws XmlDocumentCheckedException

This method returns all of the attribute values of the current node.

Returns:

a Collection of attribute values

Throws:

XmlDocumentCheckedException - If the XML is invalid.

getChild

IXmlElement getChild(int index)
              throws XmlDocumentCheckedException

This method returns an IXmlElement object that contains the child element at the given index.

Parameters:

index - The array number of the child.

Returns:

An IXmlElement object representing the child element

Throws:

XmlDocumentCheckedException - If the XML is invalid.

getChild

IXmlElement getChild(String childName)
              throws XmlDocumentCheckedException

This method returns the first child element identified by the path. If multiple children with the given name exist, the first child found is returned. This method throws an exception if no child element matches the specified name.

Parameters:

childName - a string containing the path to the child element

Returns:

XmlDocument The first child node identified by the path

Throws:

XmlDocumentCheckedException - If the XML is invalid. If there is no child element matches the specified name, an exception with XmlDocumentCheckedException.Codes.CHILD_NOT_FOUND is thrown. Exception for other reasons will have exception code XmlDocumentCheckedException.Codes.GENERAL_ERROR

selectChildren

List<IXmlElement> selectChildren(String xpathQuery)
                          throws XmlDocumentCheckedException

Parameters:

xpathQuery - The XPath string designated the desired children.

Returns:

A list of the matching children. If there are no matching children it will return an empty list.

Throws:

XmlDocumentCheckedException - If the XML is invalid.

selectChild

IXmlElement selectChild(String xpathQuery)
                 throws XmlDocumentCheckedException

Parameters:

xpathQuery - The XPath string designated the desired child.

Returns:

The element with the matching child. Returns null if there is no match.

Throws:

XmlDocumentCheckedException - If the XML is invalid.

getChildAttribute

String getChildAttribute(String child,
 String attr)
                  throws XmlDocumentCheckedException

This method returns the attribute value of a child node.

Parameters:

child - Identifies the child

attr - Contains the attribute name

Returns:

A string contains the attribute value

Throws:

XmlDocumentCheckedException - If the XML is invalid.

getChildCount

int getChildCount()
           throws XmlDocumentCheckedException

This method returns the number of children.

Returns:

Number of children

Throws:

XmlDocumentCheckedException - If the XML is invalid.

getChildren

Collection<IXmlElement> getChildren()
                             throws XmlDocumentCheckedException

This method returns all of this element's children.

Returns:

a collection of the element's children

Throws:

XmlDocumentCheckedException - If the XML is invalid.

getChildrenByName

Collection<IXmlElement> getChildrenByName(String name)
                                   throws XmlDocumentCheckedException

This method returns all of this element's children with the given name.

Parameters:

name - of the desired children.

Returns:

a collection of the element's children

Throws:

XmlDocumentCheckedException - If the XML is invalid.

getChildValue

String getChildValue(String childName)
              throws XmlDocumentCheckedException

This method returns the descendent's value.

Parameters:

childName - identifies the child element

Returns:

the value of the child element

Throws:

XmlDocumentCheckedException - If the XML is invalid.

getCDATASection

String getCDATASection(String childName)
                throws XmlDocumentCheckedException

This method returns the descendent's value.

Parameters:

childName - identifies the child element

Returns:

the value of the child element

Throws:

XmlDocumentCheckedException - If the XML is invalid.

getName

String getName()
        throws XmlDocumentCheckedException

This method returns the name of this element

Returns:

the element name

Throws:

XmlDocumentCheckedException - If the XML is invalid.

getValue

String getValue()
         throws XmlDocumentCheckedException

This method returns the element's value

Returns:

the value of the element

Throws:

XmlDocumentCheckedException - If the XML is invalid.

getDocument

Document getDocument()
              throws XmlDocumentCheckedException

Returns:

The current document.

Throws:

XmlDocumentCheckedException - If the XML is invalid.

getRootNode

Node getRootNode()
          throws XmlDocumentCheckedException

Returns:

The root node.

Throws:

XmlDocumentCheckedException - If the XML is invalid.

removeAttribute

void removeAttribute(String attributeName)
              throws XmlDocumentCheckedException

This method removes an attribute from this element..

Parameters:

attributeName - the name of the attribute

Throws:

XmlDocumentCheckedException - If the XML is invalid.

removeChild

IXmlElement removeChild(int index)
                 throws XmlDocumentCheckedException

This method removes the index-th child element.

Parameters:

index - the index of the child to remove

Returns:

the removed child

Throws:

XmlDocumentCheckedException - If the XML is invalid.

removeChild

IXmlElement removeChild(String childName)
                 throws XmlDocumentCheckedException

This method removes a child element.

Parameters:

childName - the name of the element to remove

Returns:

the removed child

Throws:

XmlDocumentCheckedException - If the XML is invalid.

removeChildWithXpath

IXmlElement removeChildWithXpath(String xpathQuery)
                          throws XmlDocumentCheckedException

This method removes a single child element with the given xpath query.

Parameters:

xpathQuery - query to identify element

Returns:

the removed child

Throws:

XmlDocumentCheckedException - If the XML is invalid.

removeChildrenWithXpath

List<IXmlElement> removeChildrenWithXpath(String xpathQuery)
                                   throws XmlDocumentCheckedException

This method removes all child elements with the given xpath query.

Parameters:

xpathQuery - query to identify elements

Returns:

the removed child

Throws:

XmlDocumentCheckedException - If the XML is invalid.

removeChildAttribute

void removeChildAttribute(String child,
 String attributeName)
                   throws XmlDocumentCheckedException

This method removes an attribute from a child element

Parameters:

child - the name of the child element

attributeName - the name of the attribute to remove

Throws:

XmlDocumentCheckedException - If the XML is invalid.

replaceAllChildren

void replaceAllChildren(IXmlElement parent)
                 throws XmlDocumentCheckedException

Removes all of the element's children and adds all of the children of the provided parent element.

Parameters:

parent - the element whose children are added to this element

Throws:

XmlDocumentCheckedException - If the XML is invalid.

replaceChild

IXmlElement replaceChild(int index,
 IXmlElement newChild)
                  throws XmlDocumentCheckedException

This method replaces the index-th element with the new element.

Parameters:

index - the index of the child to replace

newChild - the child to add to this element

Returns:

the replaced element

Throws:

XmlDocumentCheckedException - If the XML is invalid.

replaceChild

IXmlElement replaceChild(String childName,
 IXmlElement newChild)
                  throws XmlDocumentCheckedException

This method replaces the child element with the new element.

Parameters:

childName - the name of the child to replace

newChild - the child to add to this element

Returns:

the replaced element

Throws:

XmlDocumentCheckedException - If the XML is invalid.

setAttribute

IXmlElement setAttribute(String attributeName,
 String value)
                  throws XmlDocumentCheckedException

Sets the value of an attribute of this element. If the attribute doesn't exist, it is created.

Parameters:

attributeName - the attribute name

value - the attribute value

Returns:

The element.

Throws:

XmlDocumentCheckedException - If the XML is invalid.

setValue

void setValue(String value)
       throws XmlDocumentCheckedException

Sets this element's value

Parameters:

value - the new element value

Throws:

XmlDocumentCheckedException - If the XML is invalid.

setCDATASection

void setCDATASection(String value)
              throws Exception

Sets this element's CDATA value

Parameters:

value - the new element value

Throws:

Exception - If anything bad happens.

write

void write(File file)
    throws XmlDocumentCheckedException

This method saves the stored XML document as a file.

Parameters:

file - File in which to store the XML document

Throws:

XmlDocumentCheckedException - If the XML is invalid.

write

void write(OutputStream output)
    throws XmlDocumentCheckedException

This methods writes the content of the current XML document to the output stream.

Parameters:

output - Contains the output stream to write to

Throws:

XmlDocumentCheckedException - If the XML is invalid.