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:
019: /**
020: * This utility interface represents and manages an integer indexed DOM Element table, a row list
021: * of consecutive elements with a single parent element, every row element contains again an element list (cells).
022: *
023: * <p>Objects implementing this interface are attached to a real DOM element table
024: * with a single parent element, this "initial" table may be not empty,
025: * in fact it is automatically synchronized with the "real" DOM element table
026: * to show the current state when the utility object is created.</p>
027: *
028: * <p>This interface only manages DOM Element objects as row and cell elements, other node types like text nodes are ignored (filtered).</p>
029: *
030: * <p>Indexes are zero-based.</p>
031: *
032: * <p>When a DOM element (a new row or a new cell/column) is added or removed using this interface, this element
033: * is added/removed to/from the DOM table too.</p>
034: *
035: * <p>This interface inherits from {@link ElementListBase}, the list interface
036: * see the table as a list of rows.</p>
037: *
038: * @author Jose Maria Arranz Santamaria
039: */
040: public interface ElementTableBase extends ElementListBase {
041: /**
042: * Removes the specified row element.
043: *
044: * @param row index of the row element to remove.
045: * @return the removed element or null if index is out of bounds.
046: */
047: public Element removeRowAt(int row);
048:
049: /**
050: * Removes the row elements between the specified indexes.
051: *
052: * @param fromIndex low index (inclusive).
053: * @param toIndex high index (inclusive).
054: */
055: public void removeRowRange(int fromIndex, int toIndex);
056:
057: /**
058: * Removes all row elements. The table is now empty.
059: */
060: public void removeAllRows();
061:
062: /**
063: * Moves one or more row elements from the inclusive range <code>start</code> to
064: * <code>end</code> to the <code>to</code> position in the table.
065: * After the move, the row element that was at index <code>start</code>
066: * will be at index <code>to</code>.
067: *
068: * <p>The algorithm is explained in {@link ElementListBase#moveElement(int,int,int)}.</p>
069: *
070: * @param start the starting element index to be moved
071: * @param end the ending element index to be moved
072: * @param to the destination of the elements to be moved
073: */
074: public void moveRow(int start, int end, int to);
075:
076: /**
077: * Returns the number of rows.
078: *
079: * @return the number of rows.
080: */
081: public int getRowCount();
082:
083: /**
084: * Returns the row element list as an array.
085: *
086: * @return the element array.
087: */
088: public Element[] getElementRows();
089:
090: /**
091: * Returns the row element at the specified index.
092: *
093: * @param row index of the row to search.
094: * @return the row element in this position or null if index is out of range.
095: */
096: public Element getRowElementAt(int row);
097:
098: /**
099: * Returns the first row element (row at position 0).
100: *
101: * @return the first row element or null is the table is empty.
102: */
103: public Element getFirstRowElement();
104:
105: /**
106: * Returns the last row element (row at position length - 1).
107: *
108: * @return the last row element or null is the table is empty.
109: */
110: public Element getLastRowElement();
111:
112: /**
113: * Returns the position of the specified row element.
114: *
115: * @param elem the element to search.
116: * @return the position or -1 if the specified element is not in the row list.
117: */
118: public int indexOfRowElement(Element elem);
119:
120: /**
121: * Returns the position of the specified row element searching backwards.
122: *
123: * <p>The result must be the same as {@link #indexOfRowElement(Element)} because
124: * there is no "duplicated" elements. Use this method if the specified
125: * element is near to the end of the list.</p>
126: *
127: * @param elem the element to search.
128: * @return the element position or -1 if the specified element is not in the row list.
129: */
130: public int lastIndexOfRowElement(Element elem);
131:
132: /**
133: * Returns the row element of the table containing the specified node. If the node
134: * is itself a row element, self is returned.
135: *
136: *
137: * @param node the node to search for.
138: * @return the row element containing or equal the specified node. Null if this node is not contained by the table.
139: * @see #indexOfRowElement(Element)
140: * @see #getRowListElementInfoFromNode(Node)
141: */
142: public Element getRowElementFromNode(Node node);
143:
144: /**
145: * Returns an object info of the row element at the specified position.
146: *
147: * @param index index of the row.
148: * @return the object info of the specified row element. Null if index is out of range.
149: * @see #getRowListElementInfoFromNode(Node)
150: */
151: public ListElementInfo getRowListElementInfoAt(int index);
152:
153: /**
154: * Returns an object info of the row element containing the specified node (or the node
155: * is itself a row element).
156: *
157: *
158: * @param node the node to search for.
159: * @return the object info of the matched row element. Null if this node is not contained by the table.
160: * @see #getRowElementFromNode(Node)
161: */
162: public ListElementInfo getRowListElementInfoFromNode(Node node);
163:
164: /**
165: * Returns an object info of the cell element containing the specified node (or the node
166: * is itself a cell element of the table).
167: *
168: *
169: * @param node the node to search for.
170: * @return the object info of the matched cell element. Null if this node is not contained by the table.
171: * @see #getTableCellElementInfoAt(int,int)
172: */
173: public TableCellElementInfo getTableCellElementInfoFromNode(
174: Node node);
175:
176: /**
177: * Returns an object info of the cell element specified by the row and column indexes.
178: *
179: * @param row row index of the cell element.
180: * @param column column index of the cell element.
181: * @return the object info of the matched cell element. Null if some index is out of range.
182: * @see #getTableCellElementInfoFromNode(Node)
183: */
184: public TableCellElementInfo getTableCellElementInfoAt(int row,
185: int column);
186:
187: /**
188: * Returns the cell elements of the specified row as an array.
189: *
190: * @param row the row index.
191: * @return the cell element array or null if index is out of range.
192: */
193: public Element[] getCellElementsOfRow(int row);
194:
195: /**
196: * Returns the cell element at the specified row and column.
197: *
198: * @param row the row index of the cell element to search.
199: * @param column the column index of the cell element to search.
200: * @return the element in this position or null if some index is out of range.
201: */
202: public Element getCellElementAt(int row, int column);
203:
204: /**
205: * Removes the specified column.
206: *
207: * @param column index of the column to remove.
208: */
209: public void removeColumnAt(int column);
210:
211: /**
212: * Removes all columns. The table remains as a row list with no cells.
213: */
214: public void removeAllColumns();
215:
216: /**
217: * Moves the column at <code>columnIndex</code> to
218: * <code>newIndex</code>. The old column at <code>columnIndex</code>
219: * will now be found at <code>newIndex</code>. The column
220: * that used to be at <code>newIndex</code> is shifted
221: * left or right to make room. This will not move any columns if
222: * <code>columnIndex</code> equals <code>newIndex</code>.
223: *
224: * @param columnIndex the index of the column to be moved
225: * @param newIndex new index to move the column
226: */
227: public void moveColumn(int columnIndex, int newIndex);
228:
229: /**
230: * Returns the cell elements of the specified column as an array.
231: *
232: * @param column the column index.
233: * @return the cell element array or null if index is out of range..
234: */
235: public Element[] getCellElementsOfColumn(int column);
236: }
|