Package org.zkoss.idom

## Interface Item

- All Superinterfaces:
    `java.lang.Cloneable`
  All Known Subinterfaces:
    `Group`
  All Known Implementing Classes:
    `AbstractGroup`, `AbstractItem`, `AbstractTextual`, `Attribute`, `Binary`, `CData`, `Comment`, `DocType`, `Document`, `Element`, `EntityReference`, `ProcessingInstruction`, `Text`

      public interface Item
      extends java.lang.Cloneable

  Represents an item (a.k.a., node) of a iDOM tree. A iDOM tree is not necessary also a W3C/DOM tree. However, in iDOM's implement, it is because all Vertices also implement related interface, such as Node.

  Some vertices, currently only Element, might support attributes by implementing Attributable.

  Due to the implementation of both Item and W3C/DOM's interfaces, many methods seem redundant (e.g., parent vs. getParentNode, and children vs. getChildNodes). Caller could use them interchangeably . However, it is suggested to use Item's API instead of Node's, because, like JDOM, Item's API is based Java collection classes and more consistent (from my point of view). The W3C/DOM API is used to work with utilities that work only with W3C/DOM.

  Be careful that some methods look similar, but behave different. Refer to package.html.

  Author:
    tomyeh
  See Also:
    `Attributable`, `Binable`

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static int` | `FIND_BY_PREFIX` | Indicates the namespace argument is a prefix rather than URI.
    `static int` | `FIND_BY_REGEX` | Indicates the searching is based on regular expression (upon the name argument).
    `static int` | `FIND_BY_TAGNAME` | Indicates the name argument is a tag name rather than local name.
    `static int` | `FIND_IGNORE_CASE` | Indicates the searching is case insensitive.
    `static int` | `FIND_RECURSIVE` | Indicates the searching looks for all descendants.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `java.lang.Object` | `clone()` | Clones this item.
    `Item` | `detach()` | Detach this item from its parent.
    `Document` | `getDocument()` | Gets the document that owns this item.
    `Locator` | `getLocator()` | Gets the locator of this item.
    `java.lang.String` | `getName()` | Gets the name of the item.
    `Group` | `getParent()` | Gets the parent item.
    `java.lang.String` | `getText()` | Gets the text of this item, or null if it is neither `Textual` nor `Element`.
    `void` | `setLocator​(Locator loc)` | Sets the locator of this item.
    `void` | `setName​(java.lang.String name)` | Sets the name of the item.
    `void` | `setParent​(Group parent)` | Sets the parent item.
    `void` | `setText​(java.lang.String obj)` | Sets the text of this item.

- - ### Field Detail

    - #### FIND_BY_REGEX

          static final int FIND_BY_REGEX

      Indicates the searching is based on regular expression (upon the name argument). If not specified, exact-match is required.
      See Also:
        Constant Field Values

    - #### FIND_IGNORE_CASE

          static final int FIND_IGNORE_CASE

      Indicates the searching is case insensitive. This flag is ignored if FIND_BY_REGEX is specified.
      See Also:
        Constant Field Values

    - #### FIND_BY_TAGNAME

          static final int FIND_BY_TAGNAME

      Indicates the name argument is a tag name rather than local name.
      See Also:
        Constant Field Values

    - #### FIND_BY_PREFIX

          static final int FIND_BY_PREFIX

      Indicates the namespace argument is a prefix rather than URI.
      See Also:
        Constant Field Values

    - #### FIND_RECURSIVE

          static final int FIND_RECURSIVE

      Indicates the searching looks for all descendants. If not specified, only the children (not children of children) is searched.
      See Also:
        Constant Field Values

  - ### Method Detail

    - #### getName

          java.lang.String getName()

      Gets the name of the item. For vertices that support namespace (implements Namespaceable), it is the same as getTagName.
      See Also:
        `Namespaceable.getTagName()`

    - #### setName

          void setName​(java.lang.String name)

      Sets the name of the item. For vertices that support namespace (implements Namespaceable), it is the same as setTagName.
      Throws:
        `DOMException` - with NOT_SUPPORTED_ERR if this item doesn't allow to change the name, e.g., Document and DocType
      See Also:
        `Namespaceable.setTagName(java.lang.String)`

    - #### getText

          java.lang.String getText()

      Gets the text of this item, or null if it is neither `Textual` nor `Element`. For Element, the text is the concatenation of all its textual children, including Text, CDATA, and Binary.

      Besides String-type value, some item, e.g., Binary, allows any type of objects. Caller could test whether a item implements the Binable interface, and use Binable.getValue instead. For binable vertices, getText is actually getValue().toString().

      The returned value is neither trimmed nor normalized.

    - #### setText

          void setText​(java.lang.String obj)

      Sets the text of this item.
      Throws:
        `DOMException` - with NOT_SUPPORTED_ERR if this item doesn't allow to change the value, e.g., Document and Element

    - #### getDocument

          Document getDocument()

      Gets the document that owns this item. The owning document is the first document in its ancestor. For DOM, the document can only be the root, so the owning documents of vertices in a DOM tree are all the same.

    - #### detach

          Item detach()

      Detach this item from its parent.

      Because each item can belong to at most one parent at a time, it is important to detach it first, before added to another tree -- even if it is the same tree/parent.

      It has the similar effect as:
      getParent().getChildren().remove(this).

      Naming reason: we don't call this method as getChildren() to be compatible with the naming style of Attributable.attributes -- which is limited to org.w3c.dom.Attr.getAttributes. Also, it doesn't have the setter and it is "live", so it 'seem' better to call it getChildren().

      Returns:
        this item

    - #### getParent

          Group getParent()

      Gets the parent item.

    - #### getLocator

          Locator getLocator()

      Gets the locator of this item.
      Returns:
        the locator; null if not available (default)

    - #### setLocator

          void setLocator​(Locator loc)

      Sets the locator of this item.

      Unlike other methods, it won't change the modification flag.

      Parameters:
        `loc` - the locator; null if not available

    - #### clone

          java.lang.Object clone()

      Clones this item. Unlike other objects, it does a deep cloning.
      Since:
        5.0,8

    - #### setParent

          void setParent​(Group parent)

      Sets the parent item.

      DO NOT call this method. It is used internally. Instead, use detach or thru getChildren().