simkin
Class XMLElementObject

java.lang.Object
  |
  +--simkin.ExecutableRoot
        |
        +--simkin.XMLElementObject
All Implemented Interfaces:
Executable
Direct Known Subclasses:
InheritsElement, XMLExecutable

public class XMLElementObject
extends ExecutableRoot

This object is a container for an XML element, and exposes an interface to it to Simkin The class implements methods from the Executable interface.

The method getValue, setValue and method all search for matching element tags within the XML document. Only the first matching tag is used.

This class supports the following fields:


Constructor Summary
XMLElementObject()
          Default Constructor
XMLElementObject(org.w3c.dom.Element elem)
          Constructor which takes an Element
 
Method Summary
 XMLElementObject addElement(java.lang.String tag_name)
          adds a new element with the given tag name to this element
 boolean containsElement(java.lang.String tag_name)
          returns true if this element contains an element with the given tag name
 void copyAttributesInto(org.w3c.dom.Element other)
          This method clears the other elements attributes and copies from ours into it
 void copyItemsInto(org.w3c.dom.Element other)
          Clears the other element and does a deep copy of the children of this node into that one
 ExecutableIterator createIterator()
          This method returns an XMLElementObjectEnumerator object which is used in a foreach statement.
 ExecutableIterator createIterator(java.lang.String qualifier)
          This method returns an XMLElementObjectEnumerator object which is used in a foreach statement.
protected  XMLElementObject createXMLElementObject(org.w3c.dom.Element elem)
          This method creates a new XML Element object to wrap an element.
 void dump()
          This method writes the entire XML element out to the tracer
 XMLElementObjectEnumerator enumerate()
          This method returns an object which can iterate over all the immediate child elements of this element
 XMLElementObjectEnumerator enumerate(java.lang.String tagName)
          This method returns an object which can iterate over all the immediate child elements of this element whose tagname matches the one given
 boolean equals(java.lang.Object o)
          tests for equality with another object, using the string value
static org.w3c.dom.Element findChild(org.w3c.dom.Element parent, int index)
          returns the nth child element
static org.w3c.dom.Element findChild(org.w3c.dom.Element parent, java.lang.String tagname)
          returns a child element
static org.w3c.dom.Element findChild(org.w3c.dom.Element parent, java.lang.String tagname, java.lang.String attribute, java.lang.String value)
          returns a child element with the given attribute set to the given value
 boolean getAddIfNotPresent()
          this returns the value of the flag controlling whether new elements are created as they are accessed
 java.lang.String getAttribute(java.lang.String name)
          This method returns the value of an attribute attached to this element.
static java.lang.String getData(org.w3c.dom.Element element)
          retrieves the text data from an element
 org.w3c.dom.Element getElement()
          This method returns the XML Element being held by the object.
 java.lang.Object getValue(java.lang.String name, java.lang.String attrib)
          Retrieves a field from the XML.
 java.lang.Object getValueAt(java.lang.Object array_index, java.lang.String attrib)
          Retrieves the nth child element from this element.
 java.lang.Object method(java.lang.String s, java.lang.Object[] args)
          this method attempts to execute a method stored in the XML.
 void setAddIfNotPresent(boolean enable)
          sets the flag controlling whether new elements are created as they are accessed
 void setAttribute(java.lang.String name, java.lang.String value)
          Sets an attribute on this node
static void setData(org.w3c.dom.Element element, java.lang.String data)
          sets the text data for a node by looking for the first CDATA and TEXT child node
protected  void setElement(org.w3c.dom.Element elem)
          This method updates the associated element and clears the parse tree cache
 void setValue(java.lang.String name, java.lang.String attrib, java.lang.Object v)
          sets the value of an item in the element.
 void setValueAt(java.lang.Object array_index, java.lang.String attrib, java.lang.Object v)
          sets the value of an item in the element.
 java.lang.String tagName()
          this method returns the tag name of this object (taken from the code element)
 java.lang.String toString()
           
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

XMLElementObject

public XMLElementObject()
Default Constructor

XMLElementObject

public XMLElementObject(org.w3c.dom.Element elem)
Constructor which takes an Element
Parameters:
elem - the element to be stored
Method Detail

setElement

protected void setElement(org.w3c.dom.Element elem)
This method updates the associated element and clears the parse tree cache
Parameters:
elem - - the new Element

toString

public java.lang.String toString()
Overrides:
toString in class java.lang.Object
Returns:
the value of the element text data as a string

setValue

public void setValue(java.lang.String name,
                     java.lang.String attrib,
                     java.lang.Object v)
              throws java.lang.RuntimeException,
                     FieldNotSupportedException
sets the value of an item in the element. If the value passed is an element, it is first copied. If the m_AddIfNotPresent flag is true, a new item will be added if one is not already present
Overrides:
setValue in class ExecutableRoot
Parameters:
name - the name of the element tag to set (null if it's the overall element)
attrib - the name of the attribute to set (null to set text for the element)
Throws:
java.lang.RuntimeException - - if there was a problem running the script (such as not having permission to access a field)
java.lang.NoSuchFieldException - - if the field could not be found

setValueAt

public void setValueAt(java.lang.Object array_index,
                       java.lang.String attrib,
                       java.lang.Object v)
                throws java.lang.RuntimeException
sets the value of an item in the element. If the value passed is an element, it is first copied. If the m_AddIfNotPresent flag is true, a new item with the tag name "array_item" will be added if one is not already present
Overrides:
setValueAt in class ExecutableRoot
Parameters:
array_index - the position of the element in the list
attrib - the name of the attribute to set (null to set text for the element)
Throws:
java.lang.RuntimeException - - if there was a problem running the script

copyAttributesInto

public void copyAttributesInto(org.w3c.dom.Element other)
This method clears the other elements attributes and copies from ours into it
Parameters:
child - - the element into which our attributes will be copied

copyItemsInto

public void copyItemsInto(org.w3c.dom.Element other)
Clears the other element and does a deep copy of the children of this node into that one
Parameters:
child - - the element into which our children will be copied

equals

public boolean equals(java.lang.Object o)
tests for equality with another object, using the string value
Overrides:
equals in class java.lang.Object
Returns:
true if the data in both elements is the same

getElement

public org.w3c.dom.Element getElement()
This method returns the XML Element being held by the object.
Returns:
the underlying Element

getValueAt

public java.lang.Object getValueAt(java.lang.Object array_index,
                                   java.lang.String attrib)
                            throws java.lang.RuntimeException
Retrieves the nth child element from this element. It returns null if the object could not be found.If the m_AddIfNotPresent flag is true, a new item with the tag name "array_item" will be added if one is not already present
Overrides:
getValueAt in class ExecutableRoot
Parameters:
array_index - the array index
attrib - the attribute name to retrieve
Returns:
the value of the field
Throws:
java.lang.RuntimeException - - if there was a problem running the script

getValue

public java.lang.Object getValue(java.lang.String name,
                                 java.lang.String attrib)
                          throws java.lang.RuntimeException,
                                 FieldNotSupportedException
Retrieves a field from the XML. The value returned is an XMLElementObject, unless the attrib value is specified.If the m_AddIfNotPresent flag is true, a new item will be added if one is not already present
Overrides:
getValue in class ExecutableRoot
Parameters:
name - the tag name containing the data
attrib - the attribute name to retrieve
Returns:
the value of the field
Throws:
java.lang.RuntimeException - - if there was a problem running the script (such as not having permission to access a field)
FieldNotSupportedException - - if the field could not be found

getData

public static java.lang.String getData(org.w3c.dom.Element element)
retrieves the text data from an element
Parameters:
element -  
Returns:
the text from a child node of type CDATA or TEXT

setData

public static void setData(org.w3c.dom.Element element,
                           java.lang.String data)
sets the text data for a node by looking for the first CDATA and TEXT child node
Parameters:
element - the element to be changed
data - the data to be set

findChild

public static org.w3c.dom.Element findChild(org.w3c.dom.Element parent,
                                            java.lang.String tagname)
returns a child element
Parameters:
parent - the parent element
tagname - the tag name of the element
Returns:
the first element child of the parent with the matching tag name, or null if not found

findChild

public static org.w3c.dom.Element findChild(org.w3c.dom.Element parent,
                                            int index)
returns the nth child element
Parameters:
parent - the parent element
tagname - the tag name of the element
Returns:
the nth child of the parent, or null if not found

findChild

public static org.w3c.dom.Element findChild(org.w3c.dom.Element parent,
                                            java.lang.String tagname,
                                            java.lang.String attribute,
                                            java.lang.String value)
returns a child element with the given attribute set to the given value
Parameters:
parent - the parent element
tagname - the tag name of the element
attribute - name of the attribute
value - value of the named attribute
Returns:
the first element child of the parent with the matching tag name and attribute value, or null if not found

setAttribute

public void setAttribute(java.lang.String name,
                         java.lang.String value)
Sets an attribute on this node

getAttribute

public java.lang.String getAttribute(java.lang.String name)
This method returns the value of an attribute attached to this element.
Returns:
the value of the given attribute

createXMLElementObject

protected XMLElementObject createXMLElementObject(org.w3c.dom.Element elem)
This method creates a new XML Element object to wrap an element. Override this for special behaviour in derived classes. In this method, the newly created object inherits this object's m_AddIfNotPresent flag

enumerate

public XMLElementObjectEnumerator enumerate()
This method returns an object which can iterate over all the immediate child elements of this element

enumerate

public XMLElementObjectEnumerator enumerate(java.lang.String tagName)
This method returns an object which can iterate over all the immediate child elements of this element whose tagname matches the one given

dump

public void dump()
This method writes the entire XML element out to the tracer

method

public java.lang.Object method(java.lang.String s,
                               java.lang.Object[] args)
                        throws ParseException,
                               java.lang.RuntimeException,
                               MethodNotSupportedException
this method attempts to execute a method stored in the XML. It searches for an element whose tag matches the method name and if found passes the text for the tag through to the interpeter
Overrides:
method in class ExecutableRoot
Parameters:
s - the name of the method
args - an array of arguments to the method
ret - the object to receive the result of the method call
Returns:
true if the method was found, false otherwise
Throws:
ParseException - if the code contained syntax errors
java.lang.RuntimeException - if there was an error running the code
MethodNotSupportedException - if the method could not be found

tagName

public java.lang.String tagName()
this method returns the tag name of this object (taken from the code element)

addElement

public XMLElementObject addElement(java.lang.String tag_name)
adds a new element with the given tag name to this element
Returns:
the newly created element

containsElement

public boolean containsElement(java.lang.String tag_name)
returns true if this element contains an element with the given tag name

setAddIfNotPresent

public void setAddIfNotPresent(boolean enable)
sets the flag controlling whether new elements are created as they are accessed
Parameters:
enable - enables this feature (which by default is disabled)

getAddIfNotPresent

public boolean getAddIfNotPresent()
this returns the value of the flag controlling whether new elements are created as they are accessed
Returns:
true if the feature is enabled, otherwise false (the default)

createIterator

public ExecutableIterator createIterator()
This method returns an XMLElementObjectEnumerator object which is used in a foreach statement. This version iterates unconditionally over all the children of this element.
Overrides:
createIterator in class ExecutableRoot
Returns:
a new iterator object, or null if this object cannot be iterated

createIterator

public ExecutableIterator createIterator(java.lang.String qualifier)
This method returns an XMLElementObjectEnumerator object which is used in a foreach statement. This version is iterates over the child elements with the matching tag name.
Overrides:
createIterator in class ExecutableRoot
Parameters:
qualifier - - a string, children with a matching tag name will be returned
Returns:
a new iterator object, or null if this object cannot be iterated