Oracle Coherence for C++ API
Release 3.6.1.0

E18813-01

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:

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:

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:
Copyright © 2000, 2010, Oracle and/or its affiliates. All rights reserved.