Skip navigation links

Overview | Package | Class | Tree | Index | Help
| Oracle® Coherence Java API Reference Release 3.6.1.0 E18814-01
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.tangosol.run.xml
Class SimpleElement

`java.lang.Object
com.tangosol.util.Base
com.tangosol.util.BitHelper
com.tangosol.util.ExternalizableHelper
com.tangosol.run.xml.SimpleValue
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:
  - The List implementation is permitted (and most implementations are expected) to instantiate its own copy of any XmlElement objects added to it.
  - Certain properties of an element (such as Name) may not be settable once the element has been added. (See the comments for the setName method.)
  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.

Skip navigation links

Overview | Package | Class | Tree | Index | Help
| Oracle® Coherence Java API Reference Release 3.6.1.0 E18814-01
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2000, 2010, Oracle and/or its affiliates. All rights reserved.