Interface IXmlElement

An interface for XML element access.

Inherited Members

IXmlValue.GetBoolean()

IXmlValue.SetBoolean(bool)

IXmlValue.GetInt()

IXmlValue.SetInt(int)

IXmlValue.GetLong()

IXmlValue.SetLong(long)

IXmlValue.GetDouble()

IXmlValue.SetDouble(double)

IXmlValue.GetDecimal()

IXmlValue.SetDecimal(decimal)

IXmlValue.GetString()

IXmlValue.SetString(string)

IXmlValue.GetBinary()

IXmlValue.SetBinary(Binary)

IXmlValue.GetDateTime()

IXmlValue.SetDateTime(DateTime)

IXmlValue.GetBoolean(bool)

IXmlValue.GetInt(int)

IXmlValue.GetLong(long)

IXmlValue.GetDouble(double)

IXmlValue.GetDecimal(decimal)

IXmlValue.GetString(string)

IXmlValue.GetBinary(Binary)

IXmlValue.GetDateTime(DateTime)

IXmlValue.Value

IXmlValue.Parent

IXmlValue.IsEmpty

IXmlValue.IsAttribute

IXmlValue.IsContent

IXmlValue.IsMutable

IXmlValue.WriteValue(TextWriter, bool)

IXmlValue.ToString()

IXmlValue.GetHashCode()

IXmlValue.Equals(object)

ICloneable.Clone()

Namespace: Tangosol.Run.Xml

Assembly: Coherence.dll

Syntax

public interface IXmlElement : IXmlValue, ICloneable

Remarks

The IXmlElement interface represents both the element and its content (through the underlying IXmlValue interface).

Properties

AbsolutePath

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

Declaration

string AbsolutePath { get; }

Property Value

Type	Description
string	The element path.

Remarks

This is a convenience property. Elements are retrieved by simple name using Name.

Attributes

Get the dictionary of all attributes.

Declaration

IDictionary Attributes { get; }

Property Value

Type	Description
IDictionary	A IDictionary containing all attributes of this IXmlElement; the return value will never be null, although it may be an empty dictionary.

Remarks

The dictionary is keyed by attribute names. The corresponding values are non-null objects that implement the IXmlValue interface.

Comment

Get or set the text of any comments that are in the XML element.

Declaration

string Comment { get; set; }

Property Value

Type	Description
string	The comment text from this element (not including the "") or null if there was no comment.

Remarks

The XML specification does not allow a comment to contain the string "--".
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.

ElementList

Get the list of all child elements.

Declaration

IList ElementList { get; }

Property Value

Type	Description
IList	An IList containing all elements of this IXmlElement.

Remarks

The contents of the list implement the IXmlValue interface. If this IXmlElement is mutable, then the list returned from this method is expected to be mutable as well.
An element should be fully configured before it is added to the list:

• The IList implementation is permitted (and most implementations are expected) to instantiate its own copy of any IXmlElement objects added to it.
• Certain properties of an element (such as Name) may not be settable once the element has been added.

Name

Get or set the name of the element.

Declaration

string Name { get; set; }

Property Value

Type	Description
string	The element name.

Remarks

Setter is intended primarily to be utilized to configure a newly instantiated element before adding it as a child element to another element.
Implementations of this interface that support read-only documents are expected to throw InvalidOperationException from this method if the document (or this element) is in a read-only state.
If this IXmlElement has a parent IXmlElement, then the implementation of this interface is permitted to throw InvalidOperationException from this method. This results from typical document implementations in which the name of an element that is a child of another element is immutable; the W3C DOM interfaces are one example.

Root

Get the root element.

Declaration

IXmlElement Root { get; }

Property Value

Type	Description
IXmlElement	The root element for this element.

Remarks

This is a convenience property. Parent element is retrived using Parent.

Methods

AddAttribute(string)

Provides a means to add a new attribute value.

Declaration

IXmlValue AddAttribute(string name)

Parameters

Type	Name	Description
string	name	The name of the attribute.

Returns

Type	Description
IXmlValue	The newly added attribute value.

Remarks

If the attribute of the same name already exists, it is returned, otherwise a new value is created and added as an attribute.
This is a convenience method. Attributes are accessed and manipulated via the dictionary returned from Attributes.

AddElement(string)

Create a new element and add it as a child element to this element.

Declaration

IXmlElement AddElement(string name)

Parameters

Type	Name	Description
string	name	The name for the new element.

Returns

Type	Description
IXmlElement	The new IXmlElement object.

Remarks

This is a convenience method. Elements are accessed and manipulated via the list returned from ElementList.

Exceptions

Type	Condition
ArgumentException	If the name is null or if the name is not a legal XML tag name.
InvalidOperationException	If this element is immutable or otherwise can not add a child element.

EnsureElement(string)

Ensure that a child element exists.

Declaration

IXmlElement EnsureElement(string path)

Parameters

Type	Name	Description
string	path	Element path.

Returns

Type	Description
IXmlElement	The existing or new IXmlElement object.

Remarks

This is a convenience method. It combines the functionality of FindElement(string) and AddElement(string). If any part of the path does not exist create new child elements to match the path.

Exceptions

Type	Condition
ArgumentException	If the name is null or if any part of the path is not a legal XML tag name.
InvalidOperationException	If any element in the path is immutable or otherwise can not add a child element.

FindElement(string)

Find a child element with the specified '/'-delimited path.

Declaration

IXmlElement FindElement(string path)

Parameters

Type	Name	Description
string	path	Element path.

Returns

Type	Description
IXmlElement	The specified element as an object implementing IXmlElement, or null if the specified child element does not exist.

Remarks

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

This is a convenience method. Elements are accessed and manipulated via the list returned from ElementList.
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.

GetAttribute(string)

Get an attribute value.

Declaration

IXmlValue GetAttribute(string name)

Parameters

Type	Name	Description
string	name	The name of the attribute.

Returns

Type	Description
IXmlValue	The value of the specified attribute, or null if the attribute does not exist.

Remarks

This is a convenience method. Attributes are accessed and manipulated via the dictionary returned from Attributes.

GetElement(string)

Get a child element.

Declaration

IXmlElement GetElement(string name)

Parameters

Type	Name	Description
string	name	The name of child element.

Returns

Type	Description
IXmlElement	The specified element as an object implementing IXmlElement, or null if the specified child element does not exist.

Remarks

This is a convenience method. Elements are accessed and manipulated via the list returned from ElementList.
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.

GetElements(string)

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

Declaration

IEnumerator GetElements(string name)

Parameters

Type	Name	Description
string	name	The name of child elements.

Returns

Type	Description
IEnumerator	An enumerator containing all child elements of the specified name.

Remarks

This is a convenience method. Elements are accessed and manipulated via the list returned from ElementList.

GetSafeAttribute(string)

Get an attribute value, and return a temporary value if the attribute does not exist.

Declaration

IXmlValue GetSafeAttribute(string name)

Parameters

Type	Name	Description
string	name	The name of the attribute.

Returns

Type	Description
IXmlValue	The value of the specified attribute, or a temporary value if the attribute does not exist.

GetSafeElement(string)

Return the specified child element using the same path notation as supported by FindElement(string), but return a read-only element if the specified element does not exist.

Declaration

IXmlElement GetSafeElement(string path)

Parameters

Type	Name	Description
string	path	Element path.

Returns

Type	Description
IXmlElement	The specified element (never null) as an object implementing IXmlElement for read-only use.

Remarks

This method never returns null.
This is a convenience method. Elements are accessed and manipulated via the list returned from ElementList.
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.

SetAttribute(string, IXmlValue)

Set an attribute value.

Declaration

void SetAttribute(string name, IXmlValue value)

Parameters

Type	Name	Description
string	name	The name of the attribute.
IXmlValue	value	The new value for the attribute; null indicates that the attribute should be removed.

Remarks

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.
This is a convenience method. Attributes are accessed and manipulated via the dictionary returned from Attributes.

WriteXml(TextWriter, bool)

Write the element as it will appear in XML.

Declaration

void WriteXml(TextWriter writer, bool isPretty)

Parameters

Type	Name	Description
TextWriter	writer	A TextWriter object to use to write to.
bool	isPretty	true to specify that the output is intended to be as human readable as possible.