Oracle Coherence for C++ API
Release 3.6.0.0
E15728-01

- Main Page
- Namespaces
- Classes
- Files

- Alphabetical List
- Class List
- Class Hierarchy
- Class Members

# XmlElement Class Reference

`#include <coherence/run/xml/XmlElement.hpp>`

Inherits XmlValue.

Inherited by XmlDocument `[virtual]`.

List of all members.

## Detailed Description

An interface for XML element access.

The XmlElement interface represents both the element and its content (through the underlying XmlValue interface).

Author:
  js 2007.12.14

## 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.

## Member Function Documentation

virtual String::View getName | ( |  | ) | const `[pure virtual]`

Get the name of the element.

Returns:
  the element name

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.

Parameters:

  | vsName | the new element name

virtual Handle getRoot | ( |  | ) | `[pure virtual]`

Get the root element.

Returns:
  the root element for this element

virtual View getRoot | ( |  | ) | const `[pure virtual]`

Get the root element.

Returns:
  the root element for this element

virtual String::View getAbsolutePath | ( |  | ) | const `[pure virtual]`

Get the '/'-delimited path of the element starting from the root element.

Returns:
  the element path

virtual ObjectArray::Handle getAllElements | ( |  | ) | const `[pure virtual]`

Get an array of all child elements.

The contents of the array implement the XmlValue interface.

Returns:
  an array containing all child elements

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.

Returns:
  a List containing all elements of this XmlElement

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.

Returns:
  a List containing all elements of this XmlElement

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.

Parameters:

  | vsName | the name of the element to get

Returns:
  an element with the specified name or NULL if no matches are found

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.

Parameters:

  | vsName | the name of the element to get

Returns:
  an element with the specified name or NULL if no matches are found

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.

Parameters:

  | vsPath | element path

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

virtual Iterator::Handle getElements | ( | String::View | vsName | ) | `[pure virtual]`

Get an iterator of child elements that have a specific name.

Parameters:

  | vsName | the name of the element to get

Returns:
  an iterator containing all child elements of the specified name

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.

Parameters:

  | vsName | the name of the element to get

Returns:
  an iterator containing all child elements of the specified name

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.

Parameters:

  | vsPath | element path

Returns:
  the existing or new XmlElement object

Exceptions:

  | 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.

Parameters:

  | vsName | the name for the new element

Returns:
  a handle to the new XmlElement object

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:

- Leading '/' to specify root
- Use of '/' as a path delimiter
- Use of '..' to specify parent

If multiple child elements exist that have the specified path, then the behavior of this method is undefined, and it is permitted to return any one of the matching elements.

Parameters:

  | vsPath | the element path to search for

Returns:
  the specified element or NULL if the specified child element does not exist

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:

- Leading '/' to specify root
- Use of '/' as a path delimiter
- Use of '..' to specify parent

If multiple child elements exist that have the specified path, then the behavior of this method is undefined, and it is permitted to return any one of the matching elements.

Parameters:

  | vsPath | the element path to search for

Returns:
  the specified element or NULL if the specified child element does not exist

virtual XmlValue::Handle getAttribute | ( | String::View | vsName | ) | const `[pure virtual]`

Get an attribute value.

Parameters:

  | vsName | the name of the attribute

Returns:
  the attribute corresponding to the specified name or NULL if the attribute does not exist

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.

Returns:
  a Map containing all attributes of this XmlElement; the return value will never be NULL, although it may be an empty map

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.

Returns:
  a Map containing all attributes of this XmlElement; the return value will never be NULL, although it may be an empty map

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.

Parameters:

  | 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.

Parameters:

  | vsName | the name of the attribute

Returns:
  the value of the existing attribute if the attribute of the same name exist; otherwise the value of a newly created 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.

Returns:
  the comment text from this element (not including the "\<!--" and "--\>") or NULL if there was no comment

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 "--".

Parameters:

  | vsComment | the comment text

Exceptions:

  | 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.

Parameters:

  | 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

The documentation for this class was generated from the following file:

- coherence/run/xml/XmlElement.hpp

Copyright © 2000, 2010, Oracle and/or its affiliates. All rights reserved.