Oracle Coherence for C++ API
Release 3.7.1.0

E22845-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, 2011, Oracle and/or its affiliates. All rights reserved.