001: /* Group.java
002:
003: {{IS_NOTE
004:
005: Purpose:
006: Description:
007: History:
008: 2001/10/23 23:50:54, 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 java.util.List;
021: import java.util.Set;
022: import java.util.Collection;
023:
024: /**
025: * Represents an item might have children. Group is also a item.
026: * Developers usually extend new classes from
027: * {@link org.zkoss.idom.impl.AbstractGroup}, rather than
028: * implement this interface directly.
029: *
030: * <p>Design consideration: we don't support removeChildren and setChild
031: * or alike, because they can be done easily with List's methods and
032: * getAttributeIndex.
033: *
034: * @author tomyeh
035: * @see Item
036: * @see Attributable
037: * @see Namespaceable
038: * @see Binable
039: */
040: public interface Group extends Item {
041: /**
042: * Gets all children.
043: *
044: * <p>The returned list is "live". Any modification to it affects
045: * the node. On the other hand, {@link #getElements(String)} returns
046: * a copy.
047: *
048: * <p>Unlike JDOM, it won't coalesce adjacent children automatically
049: * since it might violate the caller's expection about List.
050: * Rather, we provide coalesce to let caller do the merging
051: * explicity.
052: * Note: when building a iDOM tree from a source
053: * (SAXBuilder.build), coalesce() will be inovked automatically.
054: *
055: * <p>Note: not all items supports children. If this item doesn't,
056: * it returns an empty list. And, if any invocation tries to add
057: * vertices to the returned list will cause UnsupportOperationException.
058: */
059: public List getChildren();
060:
061: /** Detaches all children and returns them in a list.
062: *
063: * <p>Note: you cannot add children to anther Group by doing
064: * <code>group.addAll(e.getChildren())</code>, because you have to detach
065: * them first. Then, you could use this method:<br>
066: * <code>group.addAll(e.detachChildren());</code>
067: */
068: public List detachChildren();
069:
070: /**
071: * Coalesces children if they are siblings with the same type
072: * instances of Textual, Textual.isCoalesceable returns true.
073: *
074: * <p>SAXBuilder.build will do the merging automatically.
075: *
076: * @param recursive true to coalesce all descendants;
077: * false to coalesce only the direct children
078: */
079: public int coalesce(boolean recursive);
080:
081: /**
082: * Gets the index of the Element-type first child that match the specified
083: * criteria.
084: *
085: * <p>Note: only Element-type children are returned, since others
086: * have no name.
087: *
088: * @param indexFrom the index to start searching from; 0 for beginning
089: * @param namespace the namspace URI if FIND_BY_PREFIX is not specified;
090: * the namespace prefix if FIND_BY_PREFIX specified; null to ingore
091: * @param name the local name if FIND_BY_TAGNAME is not sepcified;
092: * the tag name if FIND_BY_TAGNAME specified; null to ignore
093: * @param mode the serach mode; zero or any combination of
094: * Item.FIND_xxx, except FIND_RECURSIVE
095: * @return the index if found; -1 if not found
096: */
097: public int getElementIndex(int indexFrom, String namespace,
098: String name, int mode);
099:
100: /**
101: * Gets the index of the first Element-type child with the specified name.
102: *
103: * <p>Note: only Element-type children are returned, since others
104: * have no name.
105: *
106: * <p><code><pre>getChildren().add(getElementIndex(0, "pre:name"),
107: * new Element("pre:another"));</pre></code>
108: *
109: * @param indexFrom the index to start searching from; 0 for beginning
110: * @param tname the tag name (i.e., Namespaceable.getName)
111: * @return the index if found; -1 if not found
112: */
113: public int getElementIndex(int indexFrom, String tname);
114:
115: /**
116: * Gets the value of the first Element-type child that matches
117: * the giving criteria, with a trimming option.
118: *
119: * @param namespace the namspace URI if FIND_BY_PREFIX is not specified;
120: * the namespace prefix if FIND_BY_PREFIX specified; null to ingore
121: * @param name the local name if FIND_BY_TAGNAME is not sepcified;
122: * the tag name if FIND_BY_TAGNAME specified; null to ignore
123: * @return the value of the first Element-type child ; null if not found
124: */
125: public String getElementValue(String namespace, String name,
126: int mode, boolean trim);
127:
128: /**
129: * Gets the text of the first Element-type child with the tag name,
130: * with a trimming option.
131: *
132: * @param tname the tag name (i.e., Namespaceable.getName)
133: * @return the text of the first Element-type child with
134: * the tag name; null if not found
135: */
136: public String getElementValue(String tname, boolean trim);
137:
138: /**
139: * Gets the first Element-type child that matches the giving criteria.
140: *
141: * <p>Note: only Element-type children are returned. Depending on
142: * the mode, the searching is usually linear -- take O(n) to complete.
143: *
144: * @param namespace the namspace URI if FIND_BY_PREFIX is not specified;
145: * the namespace prefix if FIND_BY_PREFIX specified; null to ingore
146: * @param name the local name if FIND_BY_TAGNAME is not sepcified;
147: * the tag name if FIND_BY_TAGNAME specified; null to ignore
148: * @param mode the search mode; zero or any combination of FIND_xxx.
149: * @return the found element; null if not found or not supported
150: */
151: public Element getElement(String namespace, String name, int mode);
152:
153: /**
154: * Gets the first Element-type child with the tag name.
155: * It is the same as childOf(nsURI, lname, null, 0).
156: *
157: * <p>Note: only Element-type children are returned. Also, we did some
158: * optimization for this method so its access time is nearly constant.
159: *
160: * @param tname the tag name (i.e., Namespaceable.getName)
161: * @return the found element; null if not found or not supported
162: */
163: public Element getElement(String tname);
164:
165: /**
166: * Gets a readonly list of Element-type children that match the giving
167: * criteria.
168: *
169: * <p>Unlike {@link Element#getElementsByTagName}, this method only
170: * returns child elements, excluding grand children and other descedants.
171: *
172: * <p>The returned list is a 'live-facade' of the real ones, so
173: * the performance is good, and any modification to {@link #getChildren}
174: * will affect it.
175: *
176: * <p>Note: only Element-type children are returned. Depending on
177: * the mode, the searching is usually linear -- take O(n) to complete.
178: *
179: * @param namespace the namspace URI if FIND_BY_PREFIX is not specified;
180: * the namespace prefix if FIND_BY_PREFIX specified; null to ingore
181: * @param name the local name if FIND_BY_TAGNAME is not sepcified;
182: * the tag name if FIND_BY_TAGNAME specified; null to ignore
183: * @param mode the search mode; zero or any combination of FIND_xxx.
184: * @return a read-only list containing all matched children;
185: * an empty list if not found or not supported
186: */
187: public List getElements(String namespace, String name, int mode);
188:
189: /**
190: * Gets a readonly list of children with the tag name.
191: *
192: * <p>Unlike {@link Element#getElementsByTagName}, this method only
193: * returns child elements, excluding grand children and other descedants.
194: *
195: * <p>The returned list is a 'live-facade' of the real ones, so
196: * the performance is good, and any modification to {@link #getChildren}
197: * will affect it.
198: *
199: * <p>Note: only Element-type children are returned. Also, we did some
200: * optimization for this method so its access time is nearly constant.
201: *
202: * @param tname the tag name (i.e., Namespaceable.getName)
203: */
204: public List getElements(String tname);
205:
206: /** Returns a readonly set of names of element children.
207: * Then, you could use {@link #getElements} to get elements.
208: *
209: * <p>The returned list is a 'live-facade' of the real ones, so
210: * the performance is good, and any modification to {@link #getChildren}
211: * will affect it.
212: *
213: * @see #getElements()
214: */
215: public Set getElementNames();
216:
217: /** Returns a cloned copy of all element childrens
218: *
219: * <p>Unlike {@link #getChildren} and {@link #getElementNames},
220: * the returned list is NOT a 'live-facade' of the real ones.
221: *
222: * @see #getElementNames()
223: */
224: public List getElements();
225: }
|