Class SimpleElement

A simple implementation of the IXmlElement interface.

Inheritance

object

SimpleValue

SimpleElement

SimpleDocument

Implements

Inherited Members

SimpleValue.GetBoolean()

SimpleValue.GetBoolean(bool)

SimpleValue.SetBoolean(bool)

SimpleValue.GetInt()

SimpleValue.GetInt(int)

SimpleValue.SetInt(int)

SimpleValue.GetLong()

SimpleValue.GetLong(long)

SimpleValue.SetLong(long)

SimpleValue.GetDouble()

SimpleValue.GetDouble(double)

SimpleValue.SetDouble(double)

SimpleValue.GetDecimal()

SimpleValue.GetDecimal(decimal)

SimpleValue.SetDecimal(decimal)

SimpleValue.GetString()

SimpleValue.GetString(string)

SimpleValue.SetString(string)

SimpleValue.GetBinary()

SimpleValue.GetBinary(Binary)

SimpleValue.SetBinary(Binary)

SimpleValue.GetDateTime()

SimpleValue.GetDateTime(DateTime)

SimpleValue.SetDateTime(DateTime)

SimpleValue.Value

SimpleValue.Parent

SimpleValue.IsEmpty

SimpleValue.IsAttribute

SimpleValue.IsContent

SimpleValue.IsMutable

SimpleValue.InternalValue

SimpleValue.EnsureType(XmlValueType)

SimpleValue.Convert(object, XmlValueType)

object.Equals(object, object)

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

Namespace: Tangosol.Run.Xml

Assembly: Coherence.dll

Syntax

public class SimpleElement : SimpleValue, IPortableObject, IXmlElement, IXmlValue, ICloneable

Remarks

Protected methods are provided to support inheriting classes.

Constructors

SimpleElement()

Construct an empty SimpleElement.

Declaration

public SimpleElement()

SimpleElement(string)

Construct a SimpleElement.

Declaration

public SimpleElement(string name)

Parameters

Type	Name	Description
string	name	The name of the element.

SimpleElement(string, object)

Construct a SimpleElement.

Declaration

public SimpleElement(string name, object value)

Parameters

Type	Name	Description
string	name	The name of the element.
object	value	An initial value for this element.

Properties

AbsolutePath

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

Declaration

public virtual 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

public virtual 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

public virtual 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

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

IsNameMutable

Determine if the name can be changed.

Declaration

protected virtual bool IsNameMutable { get; }

Property Value

Type	Description
bool	true if the name can be changed.

Remarks

The default implementation allows a name to be changed. This can be overridden by inheriting implementations.

Name

Get or set the name of the element.

Declaration

public virtual 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

public virtual 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

public virtual 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

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

CheckMutable()

Validates that the element is mutable, otherwise throws an InvalidOperationException.

Declaration

protected virtual void CheckMutable()

Exceptions

Type	Condition
InvalidOperationException

Clone()

Creates and returns a copy of this SimpleElement.

Declaration

public override object Clone()

Returns

Type	Description
object	A clone of this instance.

Overrides

SimpleValue.Clone()

Remarks

The returned copy is a deep clone of this SimpleElement "unlinked" from the parent and mutable.

EnsureElement(string)

Ensure that a child element exists.

Declaration

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

Equals(object)

Compare this XML element and all of its contained information with another XML element for equality.

Declaration

public override bool Equals(object o)

Parameters

Type	Name	Description
object	o	The object to compare to.

Returns

Type	Description
bool	true if the elements are equal, false otherwise.

Overrides

SimpleValue.Equals(object)

Remarks

Note that this overrides the contract of the Equals() method in the super interface IXmlValue.

FindElement(string)

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

Declaration

public virtual 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

public virtual 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

public virtual 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

GetElements(string)

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

Declaration

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

GetHashCode()

Provide a hash value for this XML element and all of its contained information.

Declaration

public override int GetHashCode()

Returns

Type	Description
int	The hash value for this XML element.

Overrides

SimpleValue.GetHashCode()

Remarks

Note that this overrides the contract of the GetHashCode() method in the super interface IXmlValue. The hash value is defined as a xor of the following:

the GetHashCode() from the element's value (i.e. base.GetHashCode())
the GetHashCode() from each attribute name
the GetHashCode() from each attribute value
the GetHashCode() from each sub-element

GetSafeAttribute(string)

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

Declaration

public virtual 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

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

InstantiateAttribute()

Instantiate an IXmlValue implementation for an attribute value.

Declaration

protected virtual IXmlValue InstantiateAttribute()

Returns

Type	Description
IXmlValue	A new IXmlValue to be used as an attribute value.

InstantiateAttributes()

Instantiate an IDictionary implementation that will support the name to value dictionary used to hold attributes.

Declaration

protected virtual IDictionary InstantiateAttributes()

Returns

Type	Description
IDictionary	A IDictionary that supports string keys and IXmlValue values.

InstantiateElement(string, object)

Instantiate an IXmlElement implementation for an element.

Declaration

protected virtual IXmlElement InstantiateElement(string name, object value)

Parameters

Type	Name	Description
string	name	Element name.
object	value	Element value.

Returns

Type	Description
IXmlElement	A new IXmlElement to be used as an element.

InstantiateElementList()

Instantiate an IList implementation that will hold child elements.

Declaration

protected virtual IList InstantiateElementList()

Returns

Type	Description
IList	A IList that supports IXmlElements.

ReadExternal(IPofReader)

Restore the contents of a user type instance by reading its state using the specified IPofReader object.

Declaration

public override void ReadExternal(IPofReader reader)

Parameters

Type	Name	Description
IPofReader	reader	The IPofReader from which to read the object's state.

Overrides

SimpleValue.ReadExternal(IPofReader)

Exceptions

Type	Condition
IOException	If an I/O error occurs.

SetAttribute(string, IXmlValue)

Set an attribute value.

Declaration

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

ToString()

Format the XML element and all its contained information into a string in a display format.

Declaration

public override string ToString()

Returns

Type	Description
string	A string representation of the XML element.

Overrides

SimpleValue.ToString()

Remarks

Note that this overrides the contract of the ToString() method in the super interface IXmlValue.

ToString(bool)

Format the XML element and all its contained information into a string in a display format.

Declaration

public virtual string ToString(bool isPretty)

Parameters

Type	Name	Description
bool	isPretty	true to specify that the output is intended to be as human readable as possible.

Returns

Type	Description
string	A string representation of the XML element.

WriteAttributes(TextWriter, bool)

Write the attributes as part of a start tag.

Declaration

protected virtual void WriteAttributes(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.

WriteChildren(TextWriter, bool)

Write the element's children.

Declaration

protected virtual void WriteChildren(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.

WriteComment(TextWriter, bool)

Write the comment as it will appear in XML.

Declaration

protected virtual void WriteComment(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.

WriteEmptyTag(TextWriter, bool)

Write the element as a combined start/end tag.

Declaration

protected virtual void WriteEmptyTag(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.

WriteEndTag(TextWriter, bool)

Write the element's end tag.

Declaration

protected virtual void WriteEndTag(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.

WriteExternal(IPofWriter)

Save the contents of a POF user type instance by writing its state using the specified IPofWriter object.

Declaration

public override void WriteExternal(IPofWriter writer)

Parameters

Type	Name	Description
IPofWriter	writer	The IPofWriter to which to write the object's state.

Overrides

SimpleValue.WriteExternal(IPofWriter)

Exceptions

Type	Condition
IOException	If an I/O error occurs.

WriteStartTag(TextWriter, bool)

Write the element's start tag.

Declaration

protected virtual void WriteStartTag(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.

WriteValue(TextWriter, bool)

Write the value as it will appear in XML.

Declaration

public override void WriteValue(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.

Overrides

SimpleValue.WriteValue(TextWriter, bool)

WriteXml(TextWriter, bool)

Write the element as it will appear in XML.

Declaration

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

Implements

IPortableObject

IXmlElement

IXmlValue

ICloneable