001: /* ListX.java
002:
003: {{IS_NOTE
004:
005: Purpose: The extended list interface.
006: Description:
007: History:
008: 2001/5/9, Tom M. Yeh: Created.
009:
010: }}IS_NOTE
011:
012: Copyright (C) 2001 Potix Corporation. All Rights Reserved.
013:
014: {{IS_RIGHT
015: This program is distributed under GPL Version 2.0 in the hope that
016: it will be useful, but WITHOUT ANY WARRANTY.
017: }}IS_RIGHT
018: */
019: package org.zkoss.util;
020:
021: /**
022: * The extended list interface. It provides methods
023: * to access the entry of each node in the list.
024: *
025: * <p>Any class implementing
026: * this interface guarantees the binding between the entry and the
027: * element never changes even after removed.
028: *
029: * @author tomyeh
030: * @see TreeArray
031: */
032: public interface ListX {
033: /**
034: * Represents the entry of each node in the list.
035: */
036: public interface Entry {
037: /**
038: * Gets the element stored in the entry.
039: */
040: public Object getElement();
041:
042: /**
043: * Sets the entry to store the specified element.
044: */
045: public void setElement(Object element);
046:
047: /*
048: * Gets the entry next to this one.
049: *
050: * @return the next entry; null if no more
051: */
052: public Entry next();
053:
054: /*
055: * Gets the entry previous to this one.
056: *
057: * @return the previous entry; null if no more
058: */
059: public Entry previous();
060:
061: /**
062: * Tests whether an entry is an orphan -- being removed from a list.
063: */
064: public boolean isOrphan();
065: }
066:
067: /**
068: * Gets the entry of the specified index, rather than the element
069: * added by List.add. An entry is an internal representation of an
070: * object that holding the element stored by List.add.
071: *
072: * <p>The caller should consider the returned entry as opaque.
073: * The caller could store it for later use. It is useful when you
074: * want to extend the list's features, such as providing two or
075: * more indexing methods.
076: *
077: * <p>In other words, even if the underlying structure of a list is
078: * changed (e.g., a new element is inserted), the caller holding entries
079: * won't be affected.
080: *
081: * @param index the index from which the entry is retrieved
082: * @return the entry
083: */
084: public Entry getEntry(int index);
085:
086: /**
087: * Gets the index of the specified entry.
088: *
089: * @param entry the entry to locate
090: * @return the index; -1 if entry is orphan
091: */
092: public int indexOfEntry(Entry entry);
093:
094: /**
095: * Inserts the sepcified element in front of the specified entry.
096: *
097: * <p>Shifts the element currently at that position (if any)
098: * and any subsequent elements to the right (adds one to their indices).
099: *
100: * @param insertBefore the entry before which an new entry will be
101: * inserted; append is assumed if null
102: * @param element the element to insert
103: * @return the new entry containing the inserted element.
104: */
105: public Entry addEntry(Entry insertBefore, Object element);
106:
107: /**
108: * Inserts the specified element at the specified position in this list.
109: * It is an enhanced version of List.add -- it returns the entry
110: * containing the element.
111: *
112: * @param index index at which the specified element is to be inserted.
113: * @param element element to be inserted.
114: * @return the new entry that conatining the inserted element.
115: */
116: public Entry addEntry(int index, Object element);
117:
118: /**
119: * Appends the specified element to the end of this list.
120: * It is an enhanced version of List.add -- it returns the entry
121: * containing the element.
122: *
123: * @param element the element to be inserted.
124: * @return the new entry that conatining the inserted element.
125: */
126: public Entry addEntry(Object element);
127:
128: /**
129: * Remove the entry from the list. The entry object does not
130: * be deleted, and it is just no longer referenced by the list.
131: *
132: * @param entry the entry returned by getEntry.
133: */
134: public void removeEntry(Entry entry);
135:
136: /**
137: * Remove the entry at the specified location from the list.
138: * Unlike List.remove(int), it returns the entry being removed.
139: *
140: * @param index the location of the entry to remove
141: * @return the entry being removed
142: */
143: public Entry removeEntry(int index);
144: }
|