| org.zkoss.idom.Item
All known Subclasses: org.zkoss.idom.impl.AbstractItem,
| Item | | public interface Item (Code) | | Represents an item (aka., 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 redudant (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 carefult that some methods look similar, but behave different.
Refer to package.html.
author:
tomyeh
See Also: Attributable
See Also: Binable |
| Field Summary | |
| final public static int | FIND_BY_PREFIX
Indicates the namespace argument is a prefix rather
than URI. | | final public static int | FIND_BY_REGEX
Indicates the searching is based on regular expression
(upon the name argument). | | final public static int | FIND_BY_TAGNAME
Indicates the name argument is a tag name
rather than local name. | | final public static int | FIND_IGNORE_CASE
Indicates the searching is case insensitive. | | final public static int | FIND_RECURSIVE
Indicates the searching looks for all descendants. |
| Method Summary | |
| public void | clearModified(boolean includingDescendant)
Clears the modification flag of this item and all its children
if includingDescendant is true. | | public Item | clone(boolean preserveModified)
Clones this item. | | public 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. | | public Document | getDocument()
Gets the document that owns this item. | | public Locator | getLocator()
Gets the locator of this item. | | public String | getName()
Gets the name of the item. | | public Group | getParent()
Gets the parent item. | | public String | getText()
Gets the text of this item, or null if it is neither
Textual nor
Element .
For Element, the text is the catenation of all its textual
children, including Text, CDATA, and Binary.
Besides String-type value, some item, e.g., Binary, allows
any type of objects. | | public boolean | isModified()
Tests whether this item (or any of its children) is modified,
i.e., the modification flag is set. | | public boolean | isReadonly()
Tests whether this item is read-only. | | public void | setLocator(Locator loc)
Sets the locator of this item. | | public void | setModified()
Sets the modification flag. | | public void | setName(String name)
Sets the name of the item. | | public void | setParent(Group parent)
Sets the parent item.
DO NOT call this method. | | public void | setReadonly(boolean readonly)
Sets the read-only flag of this item. | | public void | setText(String obj)
Sets the text of this item. |
| FIND_BY_PREFIX | | final public static int FIND_BY_PREFIX(Code) | | Indicates the namespace argument is a prefix rather
than URI.
|
| FIND_BY_REGEX | | final public static int FIND_BY_REGEX(Code) | | Indicates the searching is based on regular expression
(upon the name argument).
If not specified, exact-match is required.
|
| FIND_BY_TAGNAME | | final public static int FIND_BY_TAGNAME(Code) | | Indicates the name argument is a tag name
rather than local name.
|
| FIND_IGNORE_CASE | | final public static int FIND_IGNORE_CASE(Code) | | Indicates the searching is case insensitive.
This flag is ignored if FIND_BY_REGEX is specified.
|
| FIND_RECURSIVE | | final public static int FIND_RECURSIVE(Code) | | Indicates the searching looks for all descendants.
If not specified, only the children (not children of children)
is searched.
|
| clearModified | | public void clearModified(boolean includingDescendant)(Code) | | Clears the modification flag of this item and all its children
if includingDescendant is true.
Unlike other methods, it doesn't affected by the read-only flag.
Parameters:
includingDescendant - whether to clear the modified flagsof descendants |
| clone | | public Item clone(boolean preserveModified)(Code) | | Clones this item. Unlike other objects, it does a deep cloning.
Also, the returned object is detached by default.
The readonly flags are cleaned. If preserveModified is false,
all modification flags of the returned object are cleaned, too.
|
| detach | | public Item detach()(Code) | | 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().
this item |
| getDocument | | public Document getDocument()(Code) | | 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.
|
| getLocator | | public Locator getLocator()(Code) | | Gets the locator of this item.
the locator; null if not available (default) |
| getName | | public String getName()(Code) | | Gets the name of the item.
For vertices that support namespace (implements Namespaceable),
it is the same as getTagName.
See Also: Namespaceable.getTagName |
| getParent | | public Group getParent()(Code) | | Gets the parent item.
|
| getText | | public String getText()(Code) | | Gets the text of this item, or null if it is neither
Textual nor
Element .
For Element, the text is the catenation 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.
|
| isModified | | public boolean isModified()(Code) | | Tests whether this item (or any of its children) is modified,
i.e., the modification flag is set.
IDOM is smart enough to set the modification flag only if
it is really modified -- i.e., assigning a different value (not just
calling any setter).
When an object is serialized, the modification flag is reset.
Also, an object generated by
Item.clone(boolean) with
preservedModified==false has also no modification flag set.
|
| isReadonly | | public boolean isReadonly()(Code) | | Tests whether this item is read-only.
Note: A item is read-only if the read-only flag is set (
Item.setReadonly )
or any of its ancestor is read-only (i.e., the read-only flag is set).
|
| setLocator | | public void setLocator(Locator loc)(Code) | | Sets the locator of this item.
Unlike other methods, it won't change the modification flag.
Parameters:
loc - the locator; null if not available |
| setModified | | public void setModified()(Code) | | Sets the modification flag. Unlike
Item.clearModified , it won't set
children's modification flags, rather it sets its parent's modification
flag.
The modifiaction flag is maintain automatically, so you rarely needs
to call this method.
Unlike other methods, it doesn't affected by the read-only flag.
|
| setName | | public void setName(String name)(Code) | | Sets the name of the item.
For vertices that support namespace (implements Namespaceable),
it is the same as setTagName.
exception:
DOMException - with NOT_SUPPORTED_ERR if this itemdoesn't allow to change the name, e.g., Document and DocType
See Also: Namespaceable.setTagName |
| setParent | | public void setParent(Group parent)(Code) | | Sets the parent item.
DO NOT call this method. It is used internally.
Instead, use detach or thru getChildren().
|
| setReadonly | | public void setReadonly(boolean readonly)(Code) | | Sets the read-only flag of this item. It causes this item
and all its descendants read-only, see
Item.isReadonly .
|
| setText | | public void setText(String obj)(Code) | | Sets the text of this item.
exception:
DOMException - with NOT_SUPPORTED_ERR if this itemdoesn't allow to change the value, e.g., Document and Element |
|
|