Overview | Package | Class | Tree | Index | Help

Oracle® Coherence Java API Reference
v3.5.3
E15583-01
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.tangosol.run.xml
Interface XmlElement

All Superinterfaces:
  java.io.Serializable, XmlValue

All Known Subinterfaces:
  XmlDocument

All Known Implementing Classes:
  SimpleDocument, SimpleElement

    public interface XmlElement

extends XmlValue

An interface for XML element access. The XmlElement interface represents both the element and its content (through the underlying XmlValue interface).

Author:
  cp 2000.10.12

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`

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.
`java.lang.Object` | `clone()` Creates and returns a copy of this XmlElement.
`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.
`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.
`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.
`void` | `writeXml(java.io.PrintWriter out, boolean fPretty)` Write the element as it will appear in XML.

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, writeValue`

Method Detail

### getName

    java.lang.String getName()

  Get the name of the element.

  Returns:
    the element name

### setName

    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.

  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 can not be renamed

### getRoot

    XmlElement getRoot()

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

  Returns:
    the root element for this element

### getAbsolutePath

    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().

  Returns:
    the element path

### getElementList

    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.)

  Returns:
    a List containing all elements of this XmlElement

### getElement

    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.

  Returns:
    the specified element as an object implementing XmlElement, or null if the specified child element does not exist

### getElements

    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().

  Returns:
    an iterator containing all child elements of the specified name

### addElement

    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().

  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 can not add a child element

### findElement

    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:
  - 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 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:
    `sPath` - element path
  Returns:
    the specified element as an object implementing XmlElement, or null if the specified child element does not exist

### getSafeElement

    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.

  Parameters:
    `sPath` - element path
  Returns:
    the specified element (never null) as an object implementing XmlElement for read-only use

### ensureElement

    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.

  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 can not add a child element
  See Also:
    `findElement(java.lang.String)`

### getAttributeMap

    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.

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

### getAttribute

    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.

  Parameters:
    `sName` - the name of the attribute
  Returns:
    the value of the specified attribute, or null if the attribute does not exist

### setAttribute

    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.

  Parameters:
    `sName` - the name of the attribute
    `val` - the new value for the attribute; null indicates that the attribute should be removed

### addAttribute

    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.

  Parameters:
    `sName` - the name of the attribute

### getSafeAttribute

    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.

  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

    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.

  Returns:
    the comment text from this element (not including the "") or null if there was no comment

### setComment

    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 "--".

  Parameters:
    `sComment` - the comment text
  Throws:
    `java.lang.IllegalArgumentException` - if the comment contains "--"

### writeXml

    void writeXml(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

    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 `XmlValue`
  Returns:
    a String representation of the XML element

### hashCode

    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:
  - the hashCode from the element's value (i.e. super.hashCode())
  - the hashCode from each attribute name
  - the hashCode from each attribute value
  - the hashCode from each sub-element

  Specified by:
    `hashCode` in interface `XmlValue`
  Returns:
    the hash value for this XML element

### equals

    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 `XmlValue`
  Returns:
    true if the elements are equal, false otherwise

### clone

    java.lang.Object clone()

  Creates and returns a copy of this XmlElement. The returned copy is a deep clone of this XmlElement, and is "unlinked" from the parent and mutable.

  Specified by:
    `clone` in interface `XmlValue`
  Returns:
    a clone of this instance.

Overview | Package | Class | Tree | Index | Help

Oracle® Coherence Java API Reference
v3.5.3
E15583-01
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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