001: /* Item.java
002:
003: {{IS_NOTE
004:
005: Purpose:
006: Description:
007: History:
008: 2001/10/21 15:54:59, Create, Tom M. Yeh.
009: }}IS_NOTE
010:
011: Copyright (C) 2001 Potix Corporation. All Rights Reserved.
012:
013: {{IS_RIGHT
014: This program is distributed under GPL Version 2.0 in the hope that
015: it will be useful, but WITHOUT ANY WARRANTY.
016: }}IS_RIGHT
017: */
018: package org.zkoss.idom;
019:
020: import org.w3c.dom.Node;
021:
022: import org.zkoss.xml.Locator;
023:
024: /**
025: * Represents an item (aka., node) of a iDOM tree. A iDOM tree is not necessary
026: * also a W3C/DOM tree. However, in iDOM's implement, it is
027: * because all Vertices also implement related interface, such as Node.
028: *
029: * <p>Some vertices, currently only Element, might support attributes
030: * by implementing Attributable.
031: *
032: * <p>Due to the implementation of both Item and W3C/DOM's interfaces,
033: * many methods seem redudant (e.g., parent vs. getParentNode, and
034: * children vs. getChildNodes).
035: * Caller could use them interchangeably . However, it is
036: * suggested to use Item's API instead of Node's, because, like JDOM,
037: * Item's API is based Java collection classes and more consistent
038: * (from my point of view). The W3C/DOM API is used to work with utilities
039: * that work only with W3C/DOM.
040: *
041: * <p>Be carefult that some methods look similar, but behave different.
042: * Refer to package.html.
043: *
044: * @author tomyeh
045: * @see Attributable
046: * @see Binable
047: */
048: public interface Item {
049: /** Indicates the searching is based on regular expression
050: * (upon the name argument).
051: * If not specified, exact-match is required.
052: */
053: public static final int FIND_BY_REGEX = 0x0001;
054: /** Indicates the searching is case insensitive.
055: * This flag is ignored if FIND_BY_REGEX is specified.
056: */
057: public static final int FIND_IGNORE_CASE = 0x0002;
058: /** Indicates the name argument is a tag name
059: * rather than local name.
060: */
061: public static final int FIND_BY_TAGNAME = 0x0004;
062: /** Indicates the namespace argument is a prefix rather
063: * than URI.
064: */
065: public static final int FIND_BY_PREFIX = 0x0008;
066: /** Indicates the searching looks for all descendants.
067: * If not specified, only the children (not children of children)
068: * is searched.
069: */
070: public static final int FIND_RECURSIVE = 0x0100;
071:
072: /**
073: * Tests whether this item is read-only.
074: * Note: A item is read-only if the read-only flag is set ({@link #setReadonly})
075: * or any of its ancestor is read-only (i.e., the read-only flag is set).
076: */
077: public boolean isReadonly();
078:
079: /**
080: * Sets the read-only flag of this item. It causes this item
081: * and all its descendants read-only, see {@link #isReadonly}.
082: */
083: public void setReadonly(boolean readonly);
084:
085: /**
086: * Gets the name of the item.
087: * For vertices that support namespace (implements Namespaceable),
088: * it is the same as getTagName.
089: *
090: * @see Namespaceable#getTagName
091: */
092: public String getName();
093:
094: /**
095: * Sets the name of the item.
096: * For vertices that support namespace (implements Namespaceable),
097: * it is the same as setTagName.
098: *
099: * @exception DOMException with NOT_SUPPORTED_ERR if this item
100: * doesn't allow to change the name, e.g., Document and DocType
101: *
102: * @see Namespaceable#setTagName
103: */
104: public void setName(String name);
105:
106: /**
107: * Gets the text of this item, or null if it is neither {@link Textual}
108: * nor {@link Element}.
109: * For Element, the text is the catenation of all its textual
110: * children, including Text, CDATA, and Binary.
111: *
112: * <p>Besides String-type value, some item, e.g., Binary, allows
113: * any type of objects. Caller could test whether a item implements
114: * the Binable interface, and use Binable.getValue instead.
115: * For binable vertices, getText is actually getValue().toString().
116: *
117: * <p>The returned value is neither trimmed nor normalized.
118: */
119: public String getText();
120:
121: /**
122: * Sets the text of this item.
123: *
124: * @exception DOMException with NOT_SUPPORTED_ERR if this item
125: * doesn't allow to change the value, e.g., Document and Element
126: */
127: public void setText(String obj);
128:
129: /**
130: * Gets the document that owns this item.
131: * The owning document is the first document in its ancestor.
132: * For DOM, the document can only be the root, so the owning documents
133: * of vertices in a DOM tree are all the same.
134: */
135: public Document getDocument();
136:
137: /**
138: * Detach this item from its parent.
139: *
140: * <p>Because each item can belong to at most one parent at a time, it
141: * is important to detach it first, before added to another tree -- even
142: * if it is the same tree/parent.
143: *
144: * <p>It has the similar effect as:<br>
145: * getParent().getChildren().remove(this).
146: *
147: * <p>Naming reason: we don't call this method as getChildren() to be
148: * compatible with the naming style of Attributable.attributes -- which
149: * is limited to org.w3c.dom.Attr.getAttributes.
150: * Also, it doesn't have the setter and it is "live", so it
151: * 'seem' better to call it getChildren().
152: *
153: * @return this item
154: */
155: public Item detach();
156:
157: /**
158: * Gets the parent item.
159: */
160: public Group getParent();
161:
162: /**
163: * Gets the locator of this item.
164: * @return the locator; null if not available (default)
165: */
166: public Locator getLocator();
167:
168: /**
169: * Sets the locator of this item.
170: *
171: * <p>Unlike other methods, it won't change the modification flag.
172: *
173: * @param loc the locator; null if not available
174: */
175: public void setLocator(Locator loc);
176:
177: /**
178: * Clones this item. Unlike other objects, it does a deep cloning.
179: * Also, the returned object is detached by default.
180: * The readonly flags are cleaned. If preserveModified is false,
181: * all modification flags of the returned object are cleaned, too.
182: */
183: public Item clone(boolean preserveModified);
184:
185: /**
186: * Tests whether this item (or any of its children) is modified,
187: * i.e., the modification flag is set.
188: *
189: * <p>IDOM is smart enough to set the modification flag only if
190: * it is really modified -- i.e., assigning a different value (not just
191: * calling any setter).
192: *
193: * <p>When an object is serialized, the modification flag is reset.
194: * Also, an object generated by {@link #clone(boolean)} with
195: * preservedModified==false has also no modification flag set.
196: */
197: public boolean isModified();
198:
199: /**
200: * Clears the modification flag of this item and all its children
201: * if includingDescendant is true.
202: *
203: * <p>Unlike other methods, it doesn't affected by the read-only flag.
204: *
205: * @param includingDescendant whether to clear the modified flags
206: * of descendants
207: */
208: public void clearModified(boolean includingDescendant);
209:
210: /**
211: * Sets the modification flag. Unlike {@link #clearModified}, it won't set
212: * children's modification flags, rather it sets its parent's modification
213: * flag.
214: *
215: * <p>The modifiaction flag is maintain automatically, so you rarely needs
216: * to call this method.
217: *
218: * <p>Unlike other methods, it doesn't affected by the read-only flag.
219: */
220: public void setModified();
221:
222: //-- Internal Methods --//
223: /**
224: * Sets the parent item.
225: *
226: * <p><b><i>DO NOT</i></b> call this method. It is used internally.
227: * Instead, use detach or thru getChildren().
228: */
229: public void setParent(Group parent);
230: }
|