001: /*
002: ItsNat Java Web Application Framework
003: Copyright (C) 2007 Innowhere Software Services S.L., Spanish Company
004: Author: Jose Maria Arranz Santamaria
005:
006: This program is free software: you can redistribute it and/or modify
007: it under the terms of the GNU Affero General Public License as published by
008: the Free Software Foundation, either version 3 of the License, or
009: (at your option) any later version. See the GNU Affero General Public
010: License for more details. See the copy of the GNU Affero General Public License
011: included in this program. If not, see <http://www.gnu.org/licenses/>.
012: */
013:
014: package org.itsnat.core.domutil;
015:
016: import org.w3c.dom.Element;
017: import org.w3c.dom.Node;
018: import org.w3c.dom.NodeList;
019:
020: /**
021: * This utility interface represents and manages an integer indexed DOM Element list, a list
022: * of consecutive elements with a single parent element.
023: *
024: * <p>Objects implementing this interface are attached to a real DOM element list
025: * with a single parent element, this "initial" list may be not empty,
026: * in fact it is automatically synchronized with the "real" DOM element list
027: * to show the current state when the utility object is created.</p>
028: *
029: * <p>This interface only manages DOM Element objects as list elements, other node types like text nodes are ignored (filtered).</p>
030: *
031: * <p>Indexes are zero-based.</p>
032: *
033: * <p>When a DOM element is added or removed using this interface, this element
034: * is added/removed to/from the DOM list too.</p>
035: *
036: * <p>The interface inherits from <code>org.w3c.dom.NodeList</code>, the method
037: * <code>NodeList.item(int)</code> is equivalent to {@link #getElementAt(int)}
038: * and <code>NodeList.getLength()</code> return the number of child DOM Elements
039: * in the list.</p>
040: *
041: *
042: * @author Jose Maria Arranz Santamaria
043: */
044: public interface ElementListBase extends ElementGroup, NodeList {
045: /**
046: * Informs whether the list is empty (no elements).
047: *
048: * @return true if the list is empty.
049: */
050: public boolean isEmpty();
051:
052: /**
053: * Removes the specified element.
054: *
055: * @param index index of the element to remove.
056: * @return the removed element or null if index is out of bounds.
057: */
058: public Element removeElementAt(int index);
059:
060: /**
061: * Removes the elements between the specified indexes.
062: *
063: * @param fromIndex low index (inclusive).
064: * @param toIndex high index (inclusive).
065: */
066: public void removeElementRange(int fromIndex, int toIndex);
067:
068: /**
069: * Removes all elements. The list is now empty.
070: */
071: public void removeAllElements();
072:
073: /**
074: * Moves one or more elements from the inclusive range <code>start</code> to
075: * <code>end</code> to the <code>to</code> position in the list.
076: * After the move, the element that was at index <code>start</code>
077: * will be at index <code>to</code>.
078: *
079: * <pre>
080: * Examples of moves:
081: * <p>
082: * 1. moveRow(1,3,5);
083: * a|B|C|D|e|f|g|h|i|j|k - before
084: * a|e|f|g|h|B|C|D|i|j|k - after
085: * <p>
086: * 2. moveRow(6,7,1);
087: * a|b|c|d|e|f|G|H|i|j|k - before
088: * a|G|H|b|c|d|e|f|i|j|k - after
089: * <p>
090: * </pre>
091: *
092: * <p>Behavior and documentation is based on <code>DefaultTableModel.moveRow(int,int,int)</code></p>
093: *
094: * @param start the starting element index to be moved
095: * @param end the ending element index to be moved
096: * @param to the destination of the elements to be moved
097: */
098: public void moveElement(int start, int end, int to);
099:
100: /**
101: * Returns the element list as an array.
102: *
103: * @return the element array.
104: */
105: public Element[] getElements();
106:
107: /**
108: * Returns the element at the specified index.
109: *
110: * @param index index of the element to search.
111: * @return the element in this position or null if index is out of range.
112: */
113: public Element getElementAt(int index);
114:
115: /**
116: * Returns the first child element (element at position 0).
117: *
118: * @return the first child element or null is the list is empty.
119: */
120: public Element getFirstElement();
121:
122: /**
123: * Returns the last child element (element at position <code>getLength() - 1</code>).
124: *
125: * @return the last child element or null is the list is empty.
126: */
127: public Element getLastElement();
128:
129: /**
130: * Returns the position of the specified element.
131: *
132: * @param elem the element to search.
133: * @return the position or -1 if the specified element is not in the list.
134: */
135: public int indexOfElement(Element elem);
136:
137: /**
138: * Returns the position of the specified element searching backwards.
139: *
140: * <p>The result must be the same as {@link #indexOfElement(Element)} because
141: * there is no "duplicated" elements. Use this method if the specified
142: * element is near to the end of the list.</p>
143: *
144: * @param elem the element to search.
145: * @return the element position or -1 if the specified element is not in the list.
146: */
147: public int lastIndexOfElement(Element elem);
148:
149: /**
150: * Returns the child element of the list containing the specified node. If the node
151: * is itself an element of the list, self is returned.
152: *
153: * @param node the node to search for.
154: * @return the element containing or equal the specified node. Null if this node is not contained by the list.
155: * @see #indexOfElement(Element)
156: * @see #getListElementInfoFromNode(Node)
157: */
158: public Element getElementFromNode(Node node);
159:
160: /**
161: * Returns an object info of the child element at the specified position.
162: *
163: * @param index index of the element to search for.
164: * @return the object info of the matched child element. Null if index is out of range.
165: * @see #getElementFromNode(Node)
166: */
167: public ListElementInfo getListElementInfoAt(int index);
168:
169: /**
170: * Returns an object info of the child element containing the specified node (or the node
171: * is itself an element of the list).
172: *
173: * @param node the node to search for.
174: * @return the object info of the matched child element. Null if this node is not contained by the list.
175: * @see #getListElementInfoAt(int)
176: */
177: public ListElementInfo getListElementInfoFromNode(Node node);
178: }
|