#include <coherence/run/xml/XmlElement.hpp>
Inherits XmlValue.
Inherited by XmlDocument [virtual].
The XmlElement interface represents both the element and its content (through the underlying XmlValue interface).
Public Types | |
| typedef spec::Handle | Handle |
| XmlElement Handle definition. | |
| typedef spec::View | View |
| XmlElement View definition. | |
| typedef spec::Holder | Holder |
| XmlElement Holder definition. | |
Public Member Functions | |
| virtual String::View | getName () const =0 |
| Get the name of the element. | |
| virtual void | setName (String::View vsName)=0 |
| Set the name of the element. | |
| virtual Handle | getRoot ()=0 |
| Get the root element. | |
| virtual View | getRoot () const =0 |
| Get the root element. | |
| virtual String::View | getAbsolutePath () const =0 |
| Get the '/'-delimited path of the element starting from the root element. | |
| virtual ObjectArray::Handle | getAllElements () const =0 |
| Get an array of all child elements. | |
| virtual List::Handle | getElementList ()=0 |
| Get the list of all child elements. | |
| virtual List::View | getElementList () const =0 |
| Get the list of all child elements. | |
| virtual Handle | getElement (String::View vsName)=0 |
| Get a child element. | |
| virtual View | getElement (String::View vsName) const =0 |
| Get a View to a child element. | |
| virtual View | getSafeElement (String::View vsPath) const =0 |
| 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. | |
| virtual Iterator::Handle | getElements (String::View vsName)=0 |
| Get an iterator of child elements that have a specific name. | |
| virtual Iterator::Handle | getElements (String::View vsName) const =0 |
| Get an iterator of child elements that have a specific name. | |
| virtual XmlElement::Handle | ensureElement (String::View vsPath)=0 |
| Ensure that a child element exists. | |
| virtual Handle | addElement (String::View vsName)=0 |
| Create a new element and add it as a child element to this element. | |
| virtual Handle | findElement (String::View vsPath)=0 |
| Find a child element with the specified '/'-delimited path. | |
| virtual View | findElement (String::View vsPath) const =0 |
| Find a child element with the specified '/'-delimited path. | |
| virtual XmlValue::Handle | getAttribute (String::View vsName) const =0 |
| Get an attribute value. | |
| virtual HashMap::Handle | getAttributeMap ()=0 |
| Get the map of all attributes. | |
| virtual HashMap::View | getAttributeMap () const =0 |
| Get the map of all attributes. | |
| virtual void | setAttribute (String::View vsName, XmlValue::Handle hValue)=0 |
| Set an attribute value. | |
| virtual XmlValue::Handle | addAttribute (String::View vsName)=0 |
| Provides a means to add a new attribute value. | |
| virtual String::View | getComment () const =0 |
| Get the text of any comments that are in the XML element. | |
| virtual void | setComment (String::View vsComment)=0 |
| Set the text of this element's comment. | |
| virtual void | writeXml (std::ostream &out, bool fPretty=false, size32_t cIndent=0) const =0 |
| Write the element as it will appear in XML. | |
| virtual String::View getName | ( | ) | const [pure virtual] |
Get the name of the element.
| virtual void setName | ( | String::View | vsName | ) | [pure virtual] |
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.
| vsName | the new element name |
| virtual Handle getRoot | ( | ) | [pure virtual] |
Get the root element.
| virtual View getRoot | ( | ) | const [pure virtual] |
Get the root element.
| virtual String::View getAbsolutePath | ( | ) | const [pure virtual] |
Get the '/'-delimited path of the element starting from the root element.
| virtual ObjectArray::Handle getAllElements | ( | ) | const [pure virtual] |
Get an array of all child elements.
The contents of the array implement the XmlValue interface.
| virtual List::Handle getElementList | ( | ) | [pure virtual] |
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.
| virtual List::View getElementList | ( | ) | const [pure virtual] |
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.
| virtual Handle getElement | ( | String::View | vsName | ) | [pure virtual] |
Get a child element.
If multiple child elements exist that have the specified name, then any matching element may be returned.
| vsName | the name of the element to get |
| virtual View getElement | ( | String::View | vsName | ) | const [pure virtual] |
Get a View to a child element.
If multiple child elements exist that have the specified name, then any matching element may be returned.
| vsName | the name of the element to get |
| virtual View getSafeElement | ( | String::View | vsPath | ) | const [pure virtual] |
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.
| vsPath | element path |
| virtual Iterator::Handle getElements | ( | String::View | vsName | ) | [pure virtual] |
Get an iterator of child elements that have a specific name.
| vsName | the name of the element to get |
| virtual Iterator::Handle getElements | ( | String::View | vsName | ) | const [pure virtual] |
Get an iterator of child elements that have a specific name.
Note: This method returns only read-only Views of the elements.
| vsName | the name of the element to get |
| virtual XmlElement::Handle ensureElement | ( | String::View | vsPath | ) | [pure virtual] |
Ensure that a child element exists.
This method combines the functionality of findElement() and addElement(). If any part of the path does not exist create new child elements to match the path.
| vsPath | element path |
| IllegalArgumentException | if the name is NULL or if any part of the path is not a legal XML tag name | |
| UnsupportedOperationException | if unable to add a child element |
| virtual Handle addElement | ( | String::View | vsName | ) | [pure virtual] |
Create a new element and add it as a child element to this element.
| vsName | the name for the new element |
| virtual Handle findElement | ( | String::View | vsPath | ) | [pure virtual] |
Find a child element with the specified '/'-delimited path.
This is based on a subset of the XPath specification, supporting:
| vsPath | the element path to search for |
| virtual View findElement | ( | String::View | vsPath | ) | const [pure virtual] |
Find a child element with the specified '/'-delimited path.
This is based on a subset of the XPath specification, supporting:
| vsPath | the element path to search for |
| virtual XmlValue::Handle getAttribute | ( | String::View | vsName | ) | const [pure virtual] |
Get an attribute value.
| vsName | the name of the attribute |
| virtual HashMap::Handle getAttributeMap | ( | ) | [pure virtual] |
Get the map of all attributes.
The map is keyed by attribute names. The corresponding values are non-NULL objects that implement the XmlValue interface.
| virtual HashMap::View getAttributeMap | ( | ) | const [pure virtual] |
Get the map of all attributes.
The map is keyed by attribute names. The corresponding values are non-NULL objects that implement the XmlValue interface.
| virtual void setAttribute | ( | String::View | vsName, | |
| XmlValue::Handle | hValue | |||
| ) | [pure virtual] |
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.
| vsName | name of the attribute | |
| hValue | the new value for the attribute; NULL indicates that the attribute should be removed |
| virtual XmlValue::Handle addAttribute | ( | String::View | vsName | ) | [pure virtual] |
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.
| vsName | the name of the attribute |
| virtual String::View getComment | ( | ) | const [pure virtual] |
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.
| virtual void setComment | ( | String::View | vsComment | ) | [pure virtual] |
Set the text of this element's comment.
This interface allows a single comment to be associated with the element. The XML specification does not allow a comment to contain the string "--".
| vsComment | the comment text |
| coherence::lang::IllegalArgumentException | if the comment contains "--" |
| virtual void writeXml | ( | std::ostream & | out, | |
| bool | fPretty = false, |
|||
| size32_t | cIndent = 0 | |||
| ) | const [pure virtual] |
Write the element as it will appear in XML.
| out | an std::ostream object to use to write to | |
| fPretty | true to specify that the output is intended to be as human readable as possible | |
| cIndent | the number of spaces to indent each line |