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:

• numChildren - the number of children of this element

Constructor Summary

XMLElementObject()
Default Constructor

XMLElementObject(java.lang.String location, 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(java.lang.String location, 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.
java.util.Hashtable	getAttributes() This method returns the attributes for this object.
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.util.Hashtable	getInstanceVariables() This method returns the instance variables for this object.
java.lang.String	getLocation() returns the location of this element
java.lang.String	getSource(java.lang.String location) This method returns the source for a scripted method described by the location.
java.lang.Object	getValue(java.lang.String name, java.lang.String attrib, ExecutableContext ctxt) Retrieves a field from the XML.
java.lang.Object	getValueAt(java.lang.Object array_index, java.lang.String attrib, ExecutableContext ctxt) Retrieves the nth child element from this element.
java.lang.Object	method(java.lang.String s, java.lang.Object[] args, ExecutableContext ctxt) 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, ExecutableContext ctxt) sets the value of an item in the element.
void	setValueAt(java.lang.Object array_index, java.lang.String attrib, java.lang.Object v, ExecutableContext ctxt) 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(java.lang.String location,
                        org.w3c.dom.Element elem)

Constructor which takes an Element

Parameters:

location - location of this element

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,
                     ExecutableContext ctxt)
              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

Specified by:

setValue in interface Executable

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)

v - the value to be set

ctxt - the context the function is called within

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

FieldNotSupportedException - - if the field could not be found

setValueAt

public void setValueAt(java.lang.Object array_index,
                       java.lang.String attrib,
                       java.lang.Object v,
                       ExecutableContext ctxt)
                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

Specified by:

setValueAt in interface Executable

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)

v - the value to be set

ctxt - the context the function is called within

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

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

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,
                                   ExecutableContext ctxt)
                            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

Specified by:

getValueAt in interface Executable

Overrides:

getValueAt in class ExecutableRoot

Parameters:

array_index - the array index

attrib - the attribute name to retrieve

ctxt - the context the function is called within

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,
                                 ExecutableContext ctxt)
                          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

Specified by:

getValue in interface Executable

Overrides:

getValue in class ExecutableRoot

Parameters:

name - the tag name containing the data

attrib - the attribute name to retrieve

ctxt - the context the function is called within

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

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(java.lang.String location,
                                                  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,
                               ExecutableContext ctxt)
                        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

Specified by:

method in interface Executable

Overrides:

method in class ExecutableRoot

Parameters:

s - the name of the method

args - an array of arguments to the method

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.

Specified by:

createIterator in interface Executable

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.

Specified by:

createIterator in interface Executable

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

getSource

public java.lang.String getSource(java.lang.String location)

This method returns the source for a scripted method described by the location.

Specified by:

getSource in interface Executable

Overrides:

getSource in class ExecutableRoot

Parameters:

location - the location of the method - in the format passed to the execute functions in the Interpreter

Returns:

the source for the method

getInstanceVariables

public java.util.Hashtable getInstanceVariables()

This method returns the instance variables for this object. This is a hashtable mapping name to XMLElementObject. If names are duplicated the last occurrence will appear in the table

Specified by:

getInstanceVariables in interface Executable

Overrides:

getInstanceVariables in class ExecutableRoot

Returns:

table a table to filled with references to the instance variables. Each entry in the table maps a name to an object

getAttributes

public java.util.Hashtable getAttributes()

This method returns the attributes for this object. At

Specified by:

getAttributes in interface Executable

Overrides:

getAttributes in class ExecutableRoot

Returns:

table a table filled with the attribute values. Each entry in the table maps an attribute name to a value

getLocation

public java.lang.String getLocation()

returns the location of this element