001: /*
002: * Copyright 2004-2008 H2 Group. Licensed under the H2 License, Version 1.0
003: * (http://h2database.com/html/license.html).
004: * Initial Developer: H2 Group
005: */
006: package org.h2.index;
007:
008: import java.sql.SQLException;
009:
010: import org.h2.engine.Session;
011: import org.h2.result.Row;
012: import org.h2.result.SearchRow;
013: import org.h2.schema.SchemaObject;
014: import org.h2.table.Column;
015: import org.h2.table.IndexColumn;
016: import org.h2.table.Table;
017:
018: /**
019: * An index. Indexes are used to speed up searching data.
020: */
021: public interface Index extends SchemaObject {
022:
023: /**
024: * Indicates that there is no head record yet.
025: */
026: int EMPTY_HEAD = -1;
027:
028: /**
029: * Create a duplicate key exception with a message that contains the index name
030: *
031: * @return the exception
032: */
033: SQLException getDuplicateKeyException();
034:
035: /**
036: * Get the message to show in a EXPLAIN statement.
037: *
038: * @return the plan
039: */
040: String getPlanSQL();
041:
042: /**
043: * Close this index.
044: *
045: * @param session the session used to write data
046: */
047: void close(Session session) throws SQLException;
048:
049: /**
050: * Add a row to the index.
051: *
052: * @param session the session to use
053: * @param row the data
054: */
055: void add(Session session, Row row) throws SQLException;
056:
057: /**
058: * Remove a row from the index.
059: *
060: * @param session the session
061: * @param row the data
062: */
063: void remove(Session session, Row row) throws SQLException;
064:
065: /**
066: * Find a row or a list of rows and create a cursor to iterate over the result.
067: *
068: * @param session the session
069: * @param first the first row, or null for no limit
070: * @param last the last row, or null for no limit
071: * @return the cursor
072: */
073: Cursor find(Session session, SearchRow first, SearchRow last)
074: throws SQLException;
075:
076: /**
077: * Estimate the cost to search for rows given the search mask.
078: *
079: * @param session the session
080: * @param masks the search mask
081: * @return the estimated cost
082: */
083: double getCost(Session session, int[] masks) throws SQLException;
084:
085: /**
086: * Remove the index.
087: *
088: * @param session the session
089: */
090: void remove(Session session) throws SQLException;
091:
092: /**
093: * Remove all rows from the index.
094: *
095: * @param session the session
096: */
097: void truncate(Session session) throws SQLException;
098:
099: /**
100: * Check if the index can directly look up the lowest or highest value of a
101: * column.
102: *
103: * @return true if it can
104: */
105: boolean canGetFirstOrLast();
106:
107: /**
108: * Check if the index can get the next higher value.
109: *
110: * @return true if it can
111: */
112: boolean canFindNext();
113:
114: /**
115: * Find a row or a list of rows that is larger and create a cursor to
116: * iterate over the result.
117: *
118: * @param session the session
119: * @param higherThan the lower limit (excluding)
120: * @param last the last row, or null for no limit
121: * @return the cursor
122: */
123:
124: Cursor findNext(Session session, SearchRow higherThan,
125: SearchRow last) throws SQLException;
126:
127: /**
128: * Find the lowest or highest value of a column.
129: *
130: * @param session the session
131: * @param first true if the first (lowest for ascending indexes) or last
132: * value should be returned
133: * @return the search row with the value
134: */
135: SearchRow findFirstOrLast(Session session, boolean first)
136: throws SQLException;
137:
138: /**
139: * Check if the index needs to be rebuilt.
140: * This method is called after opening an index.
141: *
142: * @return true if a rebuild is required.
143: */
144: boolean needRebuild();
145:
146: /**
147: * Get the row count of this table, for the given session.
148: *
149: * @param session the session
150: * @return the row count
151: */
152: long getRowCount(Session session);
153:
154: /**
155: * Estimate the cost required to search a number of rows.
156: *
157: * @param rowCount the row count
158: * @return the estimated cost
159: */
160: int getLookupCost(long rowCount);
161:
162: /**
163: * Estimate the cost required to search one row, and then iterate over the
164: * given number of rows.
165: *
166: * @param masks the search mask
167: * @param rowCount the row count
168: * @return the estimated cost
169: */
170: long getCostRangeIndex(int[] masks, long rowCount)
171: throws SQLException;
172:
173: /**
174: * Compare two rows.
175: *
176: * @param rowData the first row
177: * @param compare the second row
178: * @return 0 if both rows are equal, -1 if the first row is smaller, otherwise 1
179: */
180: int compareRows(SearchRow rowData, SearchRow compare)
181: throws SQLException;
182:
183: /**
184: * Check if a row is NULL.
185: *
186: * @param newRow
187: * @return if it is null
188: */
189: boolean isNull(Row newRow);
190:
191: /**
192: * Compare the positions of two rows.
193: *
194: * @param rowData the first row
195: * @param compare the second row
196: * @return 0 if both rows are equal, -1 if the first row is smaller, otherwise 1
197: */
198: int compareKeys(SearchRow rowData, SearchRow compare);
199:
200: /**
201: * Get the index of a column in the list of index columns
202: *
203: * @param col the column
204: * @return the index (0 meaning first column)
205: */
206: int getColumnIndex(Column col);
207:
208: /**
209: * Get the list of columns as a string.
210: *
211: * @return the list of columns
212: */
213: String getColumnListSQL();
214:
215: /**
216: * Get the indexed columns as index columns (with ordering information).
217: *
218: * @return the index columns
219: */
220: IndexColumn[] getIndexColumns();
221:
222: /**
223: * Get the indexed columns.
224: *
225: * @return the columns
226: */
227: Column[] getColumns();
228:
229: /**
230: * Get the index type.
231: *
232: * @return the index type
233: */
234: IndexType getIndexType();
235:
236: /**
237: * Get the table on which this index is based.
238: *
239: * @return the table
240: */
241: Table getTable();
242:
243: /**
244: * Commit the operation for a row. This is only important for multi-version
245: * indexes.
246: *
247: * @param operation the operation type
248: * @param row the row
249: */
250: void commit(int operation, Row row) throws SQLException;
251:
252: }
|