Oracle® Coherence Java API Reference
v3.5.3

E15583-01

com.tangosol.run.xml
Class SimpleElement

java.lang.Object
  extended by com.tangosol.util.Base
      extended by com.tangosol.util.BitHelper
          extended by com.tangosol.util.ExternalizableHelper
              extended by com.tangosol.run.xml.SimpleValue
                  extended by com.tangosol.run.xml.SimpleElement
All Implemented Interfaces:
ExternalizableLite, PortableObject, XmlElement, XmlSerializable, XmlValue, java.io.Serializable, java.lang.Cloneable
Direct Known Subclasses:
SimpleDocument

public class SimpleElement
extends SimpleValue
implements XmlElement, XmlSerializable

A simple implementation of the XmlElement interface. Protected methods are provided to support inheriting classes.

Author:
cp 2000.10.20

Nested Class Summary
 class SimpleElement.AttributeMap
          A Map implementation using a list that can be a read-only map that supports only Strings for keys and XmlValue for values.
protected  class SimpleElement.ElementIterator
          Provides an Iterator implementation that exposes only those Elements from the Element list that match a certain name.
protected  class SimpleElement.ElementList
          An implementation of List that only supports XmlElements as the content of the List.
 
Field Summary
 
Fields inherited from interface com.tangosol.run.xml.XmlValue
TYPE_BINARY, TYPE_BOOLEAN, TYPE_DATE, TYPE_DATETIME, TYPE_DECIMAL, TYPE_DOUBLE, TYPE_INT, TYPE_LONG, TYPE_STRING, TYPE_TIME
 
Constructor Summary
SimpleElement()
          Construct an empty SimpleElement.
SimpleElement(java.lang.String sName)
          Construct a SimpleElement.
SimpleElement(java.lang.String sName, java.lang.Object oValue)
          Construct a SimpleElement.
 
Method Summary
 XmlValue addAttribute(java.lang.String sName)
          Provides a means to add a new attribute value.
 XmlElement addElement(java.lang.String sName)
          Create a new element and add it as a child element to this element.
protected  void checkMutable()
          Validates that the element is mutable, otherwise throws an UnsupportedOperationException.
 java.lang.Object clone()
          Creates and returns a copy of this SimpleElement.
 XmlElement ensureElement(java.lang.String sPath)
          Ensure that a child element exists.
 boolean equals(java.lang.Object o)
          Compare this XML element and all of its contained information with another XML element for equality.
 XmlElement findElement(java.lang.String sPath)
          Find a child element with the specified '/'-delimited path.
 void fromXml(XmlElement xml)
          Deserialize the object from an XmlElement.
 java.lang.String getAbsolutePath()
          Get the '/'-delimited path of the element starting from the root element.
 XmlValue getAttribute(java.lang.String sName)
          Get an attribute value.
 java.util.Map getAttributeMap()
          Get the map of all attributes.
 java.lang.String getComment()
          Get the text of any comments that are in the XML element.
 XmlElement getElement(java.lang.String sName)
          Get a child element.
 java.util.List getElementList()
          Get the list of all child elements.
 java.util.Iterator getElements(java.lang.String sName)
          Get an iterator of child elements that have a specific name.
 java.lang.String getName()
          Get the name of the element.
 XmlElement getRoot()
          Get the root element.
 XmlValue getSafeAttribute(java.lang.String sName)
          Get an attribute value, and return a temporary value if the attribute does not exist.
 XmlElement getSafeElement(java.lang.String sPath)
          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.
 int hashCode()
          Provide a hash value for this XML element and all of its contained information.
protected  XmlValue instantiateAttribute()
          Instantiate an XmlValue implementation for an attribute value.
protected  java.util.Map instantiateAttributeMap()
          Instantiate a Map implementation that will support the name to value map used to hold attributes.
protected  XmlElement instantiateElement(java.lang.String sName, java.lang.Object oValue)
          Instantiate an XmlElement implementation for an element.
protected  java.util.List instantiateElementList()
          Instantiate a List implementation that will hold child elements.
protected  boolean isNameMutable()
          Determine if the name can be changed.
 void readExternal(java.io.DataInput in)
          Restore the contents of this object by loading the object's state from the passed DataInput object.
 void readExternal(PofReader in)
          Restore the contents of a user type instance by reading its state using the specified PofReader object.
 void setAttribute(java.lang.String sName, XmlValue val)
          Set an attribute value.
 void setComment(java.lang.String sComment)
          Set the text of this element's comment.
 void setName(java.lang.String sName)
          Set the Name of the element.
 java.lang.String toString()
          Format the XML element and all its contained information into a String in a display format.
 java.lang.String toString(boolean fPretty)
          Format the XML element and all its contained information into a String in a display format.
 XmlElement toXml()
          Serialize the object into an XmlElement.
protected  void writeAttributes(java.io.PrintWriter out, boolean fPretty)
          Write the attributes as part of a start tag.
protected  void writeChildren(java.io.PrintWriter out, boolean fPretty)
          Write the element as it will appear in XML.
protected  void writeComment(java.io.PrintWriter out, boolean fPretty)
          Write the element as it will appear in XML.
protected  void writeEmptyTag(java.io.PrintWriter out, boolean fPretty)
          Write the element as a combined start/end tag.
protected  void writeEndTag(java.io.PrintWriter out, boolean fPretty)
          Write the element's end tag.
 void writeExternal(java.io.DataOutput out)
          Save the contents of this object by storing the object's state into the passed DataOutput object.
 void writeExternal(PofWriter out)
          Save the contents of a POF user type instance by writing its state using the specified PofWriter object.
protected  void writeStartTag(java.io.PrintWriter out, boolean fPretty)
          Write the element's start tag.
 void writeValue(java.io.PrintWriter out, boolean fPretty)
          Write the value as it will appear in XML.
 void writeXml(java.io.PrintWriter out, boolean fPretty)
          Write the element as it will appear in XML.
 
Methods inherited from class com.tangosol.run.xml.SimpleValue
convert, ensureType, getBinary, getBinary, getBoolean, getBoolean, getDate, getDate, getDateTime, getDateTime, getDecimal, getDecimal, getDouble, getDouble, getInt, getInt, getInternalValue, getLong, getLong, getParent, getString, getString, getTime, getTime, getValue, isAttribute, isContent, isEmpty, isMutable, setAttribute, setBinary, setBoolean, setDate, setDateTime, setDecimal, setDouble, setInt, setInternalValue, setLong, setMutable, setParent, setString, setTime
 
Methods inherited from class com.tangosol.util.BitHelper
countBits, countBits, countBits, indexOfLSB, indexOfLSB, indexOfLSB, indexOfMSB, indexOfMSB, indexOfMSB, rotateLeft, rotateLeft, rotateLeft, rotateRight, rotateRight, rotateRight, toBitString, toBitString, toBitString
 
Methods inherited from interface com.tangosol.run.xml.XmlValue
getBinary, getBinary, getBoolean, getBoolean, getDate, getDate, getDateTime, getDateTime, getDecimal, getDecimal, getDouble, getDouble, getInt, getInt, getLong, getLong, getParent, getString, getString, getTime, getTime, getValue, isAttribute, isContent, isEmpty, isMutable, setBinary, setBoolean, setDate, setDateTime, setDecimal, setDouble, setInt, setLong, setParent, setString, setTime
 

Constructor Detail

SimpleElement

public SimpleElement()
Construct an empty SimpleElement. Note: this constructor is needed only to comply with the requirements for the Externalizable and ExternalizableLite interfaces.


SimpleElement

public SimpleElement(java.lang.String sName)
Construct a SimpleElement.

Parameters:
sName - the name of the element

SimpleElement

public SimpleElement(java.lang.String sName,
                     java.lang.Object oValue)
Construct a SimpleElement.

Parameters:
sName - the name of the element
oValue - an initial value for this element
Method Detail

getName

public java.lang.String getName()
Get the name of the element.

Specified by:
getName in interface XmlElement
Returns:
the element name

setName

public void setName(java.lang.String sName)
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. Implementations of this interface that support read-only documents are expected to throw UnsupportedOperationException from this method if the document (or this element) is in a read-only state. If this XmlElement has a parent XmlElement, then the implementation of this interface is permitted to throw UnsupportedOperationException 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.

Specified by:
setName in interface XmlElement
Parameters:
sName - the new element name
Throws:
java.lang.IllegalArgumentException - if the name is null or if the name is not a legal XML tag name
java.lang.UnsupportedOperationException - if the element cannot be renamed

getRoot

public XmlElement getRoot()
Get the root element. This is a convenience method. Parent element is retrived using getParent().

Specified by:
getRoot in interface XmlElement
Returns:
the root element for this element

getAbsolutePath

public java.lang.String getAbsolutePath()
Get the '/'-delimited path of the element starting from the root element. This is a convenience method. Elements are retrieved by simple name using getName().

Specified by:
getAbsolutePath in interface XmlElement
Returns:
the element path

getElementList

public java.util.List getElementList()
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. An element should be fully configured before it is added to the list:

Specified by:
getElementList in interface XmlElement
Returns:
a List containing all elements of this XmlElement

getElement

public XmlElement getElement(java.lang.String sName)
Get a child element. 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.

Specified by:
getElement in interface XmlElement
Returns:
the specified element as an object implementing XmlElement, or null if the specified child element does not exist

getElements

public java.util.Iterator getElements(java.lang.String sName)
Get an iterator of child elements that have a specific name. This is a convenience method. Elements are accessed and manipulated via the list returned from getElementList().

Specified by:
getElements in interface XmlElement
Returns:
an iterator containing all child elements of the specified name

addElement

public XmlElement addElement(java.lang.String sName)
Create a new element and add it as a child element to this element. This is a convenience method. Elements are accessed and manipulated via the list returned from getElementList().

Specified by:
addElement in interface XmlElement
Parameters:
sName - the name for the new element
Returns:
the new XmlElement object
Throws:
java.lang.IllegalArgumentException - if the name is null or if the name is not a legal XML tag name
java.lang.UnsupportedOperationException - if this element is immutable or otherwise cannot add a child element

findElement

public XmlElement findElement(java.lang.String sPath)
Find a child element with the specified '/'-delimited path. This is based on a subset of the XPath specification, supporting:
  1. Leading '/' to specify root
  2. Use of '/' as a path delimiter
  3. Use of '..' to specify parent
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.

Specified by:
findElement in interface XmlElement
Parameters:
sPath - element path
Returns:
the specified element as an object implementing XmlElement, or null if the specified child element does not exist

getSafeElement

public XmlElement getSafeElement(java.lang.String sPath)
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.

Specified by:
getSafeElement in interface XmlElement
Parameters:
sPath - element path
Returns:
the specified element (never null) as an object implementing XmlElement for read-only use

ensureElement

public XmlElement ensureElement(java.lang.String sPath)
Ensure that a child element exists. This is a convenience method. It combines the functionality of findElement() and addElement(). If any part of the path does not exist create new child elements to match the path.

Specified by:
ensureElement in interface XmlElement
Parameters:
sPath - element path
Returns:
the existing or new XmlElement object
Throws:
java.lang.IllegalArgumentException - if the name is null or if any part of the path is not a legal XML tag name
java.lang.UnsupportedOperationException - if any element in the path is immutable or otherwise cannot add a child element
See Also:
findElement(java.lang.String)

getAttributeMap

public java.util.Map getAttributeMap()
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.

Specified by:
getAttributeMap in interface XmlElement
Returns:
a Map containing all attributes of this XmlElement; the return value will never be null, although it may be an empty map

getAttribute

public XmlValue getAttribute(java.lang.String sName)
Get an attribute value. This is a convenience method. Attributes are accessed and manipulated via the map returned from getAttributeMap.

Specified by:
getAttribute in interface XmlElement
Parameters:
sName - the name of the attribute
Returns:
the value of the specified attribute, or null if the attribute does not exist or does not have a value

setAttribute

public void setAttribute(java.lang.String sName,
                         XmlValue val)
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. This is a convenience method. Attributes are accessed and manipulated via the map returned from getAttributeMap.

Specified by:
setAttribute in interface XmlElement
Parameters:
sName - the name of the attribute
val - the new value for the attribute; null indicates that the attribute should be removed

addAttribute

public XmlValue addAttribute(java.lang.String sName)
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. This is a convenience method. Attributes are accessed and manipulated via the map returned from getAttributeMap.

Specified by:
addAttribute in interface XmlElement
Parameters:
sName - the name of the attribute

getSafeAttribute

public XmlValue getSafeAttribute(java.lang.String sName)
Get an attribute value, and return a temporary value if the attribute does not exist. This is a convenience method. Attributes are accessed and manipulated via the map returned from getAttributeMap.

Specified by:
getSafeAttribute in interface XmlElement
Parameters:
sName - the name of the attribute
Returns:
the value of the specified attribute, or a temporary value if the attribute does not exist

getComment

public java.lang.String getComment()
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.

Specified by:
getComment in interface XmlElement
Returns:
the comment text from this element (not including the "") or null if there was no comment

setComment

public void setComment(java.lang.String sComment)
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 "--".

Specified by:
setComment in interface XmlElement
Parameters:
sComment - the comment text
Throws:
java.lang.IllegalArgumentException - if the comment contains "--"

writeXml

public void writeXml(java.io.PrintWriter out,
                     boolean fPretty)
Write the element as it will appear in XML.

Specified by:
writeXml in interface XmlElement
Parameters:
out - a PrintWriter object to use to write to
fPretty - true to specify that the output is intended to be as human readable as possible

writeValue

public void writeValue(java.io.PrintWriter out,
                       boolean fPretty)
Write the value as it will appear in XML.

Specified by:
writeValue in interface XmlValue
Overrides:
writeValue in class SimpleValue
Parameters:
out - a PrintWriter object to use to write to
fPretty - true to specify that the output is intended to be as human readable as possible

toXml

public XmlElement toXml()
Serialize the object into an XmlElement.

Specified by:
toXml in interface XmlSerializable
Returns:
an XmlElement that contains the serialized form of the object

fromXml

public void fromXml(XmlElement xml)
Deserialize the object from an XmlElement. This method can throw one of several RuntimeExceptions.

Specified by:
fromXml in interface XmlSerializable
Parameters:
xml - an XmlElement that contains the serialized form of the object
Throws:
java.lang.UnsupportedOperationException - if this element is immutable

readExternal

public void readExternal(java.io.DataInput in)
                  throws java.io.IOException
Restore the contents of this object by loading the object's state from the passed DataInput object.

Specified by:
readExternal in interface ExternalizableLite
Overrides:
readExternal in class SimpleValue
Parameters:
in - the DataInput stream to read data from in order to restore the state of this object
Throws:
java.io.IOException - if an I/O exception occurs
java.io.NotActiveException - if the object is not in its initial state, and therefore cannot be deserialized into

writeExternal

public void writeExternal(java.io.DataOutput out)
                   throws java.io.IOException
Save the contents of this object by storing the object's state into the passed DataOutput object.

Specified by:
writeExternal in interface ExternalizableLite
Overrides:
writeExternal in class SimpleValue
Parameters:
out - the DataOutput stream to write the state of this object to
Throws:
java.io.IOException - if an I/O exception occurs

readExternal

public void readExternal(PofReader in)
                  throws java.io.IOException
Restore the contents of a user type instance by reading its state using the specified PofReader object.

Specified by:
readExternal in interface PortableObject
Overrides:
readExternal in class SimpleValue
Parameters:
in - the PofReader from which to read the object's state
Throws:
java.io.IOException - if an I/O error occurs

writeExternal

public void writeExternal(PofWriter out)
                   throws java.io.IOException
Save the contents of a POF user type instance by writing its state using the specified PofWriter object.

Specified by:
writeExternal in interface PortableObject
Overrides:
writeExternal in class SimpleValue
Parameters:
out - the PofWriter to which to write the object's state
Throws:
java.io.IOException - if an I/O error occurs

checkMutable

protected void checkMutable()
Validates that the element is mutable, otherwise throws an UnsupportedOperationException.

Throws:
java.lang.UnsupportedOperationException

isNameMutable

protected boolean isNameMutable()
Determine if the name can be changed. The default implementation allows a name to be changed. This can be overridden by inheriting implementations.

Returns:
true if the name can be changed

instantiateElementList

protected java.util.List instantiateElementList()
Instantiate a List implementation that will hold child elements.

Returns:
a List that supports XmlElements

instantiateElement

protected XmlElement instantiateElement(java.lang.String sName,
                                        java.lang.Object oValue)
Instantiate an XmlElement implementation for an element.

Parameters:
sName - element name
oValue - element value
Returns:
a new XmlElement to be used as an element

instantiateAttributeMap

protected java.util.Map instantiateAttributeMap()
Instantiate a Map implementation that will support the name to value map used to hold attributes.

Returns:
a Map that supports String keys and XmlValue values

instantiateAttribute

protected XmlValue instantiateAttribute()
Instantiate an XmlValue implementation for an attribute value.

Returns:
a new XmlValue to be used as an attribute value

writeEmptyTag

protected void writeEmptyTag(java.io.PrintWriter out,
                             boolean fPretty)
Write the element as a combined start/end tag.

Parameters:
out - a PrintWriter object to use to write to
fPretty - true to specify that the output is intended to be as human readable as possible

writeStartTag

protected void writeStartTag(java.io.PrintWriter out,
                             boolean fPretty)
Write the element's start tag.

Parameters:
out - a PrintWriter object to use to write to
fPretty - true to specify that the output is intended to be as human readable as possible

writeEndTag

protected void writeEndTag(java.io.PrintWriter out,
                           boolean fPretty)
Write the element's end tag.

Parameters:
out - a PrintWriter object to use to write to
fPretty - true to specify that the output is intended to be as human readable as possible

writeAttributes

protected void writeAttributes(java.io.PrintWriter out,
                               boolean fPretty)
Write the attributes as part of a start tag.

Parameters:
out - a PrintWriter object to use to write to
fPretty - true to specify that the output is intended to be as human readable as possible

writeComment

protected void writeComment(java.io.PrintWriter out,
                            boolean fPretty)
Write the element as it will appear in XML.

Parameters:
out - a PrintWriter object to use to write to
fPretty - true to specify that the output is intended to be as human readable as possible

writeChildren

protected void writeChildren(java.io.PrintWriter out,
                             boolean fPretty)
Write the element as it will appear in XML.

Parameters:
out - a PrintWriter object to use to write to
fPretty - true to specify that the output is intended to be as human readable as possible

toString

public java.lang.String toString()
Format the XML element and all its contained information into a String in a display format. Note that this overrides the contract of the toString method in the super interface XmlValue.

Specified by:
toString in interface XmlElement
Specified by:
toString in interface XmlValue
Overrides:
toString in class SimpleValue
Returns:
a String representation of the XML element

toString

public java.lang.String toString(boolean fPretty)
Format the XML element and all its contained information into a String in a display format.

Parameters:
fPretty - true to specify that the output is intended to be as human readable as possible
Returns:
a String representation of the XML element

hashCode

public int hashCode()
Provide a hash value for this XML element and all of its contained information. Note that this overrides the contract of the hashCode method in the super interface XmlValue. The hash value is defined as a xor of the following:
  1. the hashCode from the element's value (i.e. super.hashCode())
  2. the hashCode from each attribute name
  3. the hashCode from each attribute value
  4. the hashCode from each sub-element

Specified by:
hashCode in interface XmlElement
Specified by:
hashCode in interface XmlValue
Overrides:
hashCode in class SimpleValue
Returns:
the hash value for this XML element

equals

public boolean equals(java.lang.Object o)
Compare this XML element and all of its contained information with another XML element for equality. Note that this overrides the contract of the equals method in the super interface XmlValue.

Specified by:
equals in interface XmlElement
Specified by:
equals in interface XmlValue
Overrides:
equals in class SimpleValue
Returns:
true if the elements are equal, false otherwise

clone

public java.lang.Object clone()
Creates and returns a copy of this SimpleElement. The returned copy is a deep clone of this SimpleElement "unlinked" from the parent and mutable

Specified by:
clone in interface XmlElement
Specified by:
clone in interface XmlValue
Overrides:
clone in class SimpleValue
Returns:
a clone of this instance.

Oracle® Coherence Java API Reference
v3.5.3

E15583-01

Copyright © 2000, 2010, Oracle. All rights reserved.