1 /*
2 Copyright (c) 2013 James Ahlborn
3
4 Licensed under the Apache License, Version 2.0 (the "License");
5 you may not use this file except in compliance with the License.
6 You may obtain a copy of the License at
7
8 http://www.apache.org/licenses/LICENSE-2.0
9
10 Unless required by applicable law or agreed to in writing, software
11 distributed under the License is distributed on an "AS IS" BASIS,
12 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 See the License for the specific language governing permissions and
14 limitations under the License.
15 */
16
17 package com.healthmarketscience.jackcess;
18
19 import java.io.IOException;
20
21 import com.healthmarketscience.jackcess.util.EntryIterableBuilder;
22
23 /**
24 * Cursor backed by an {@link Index} with extended traversal options. Table
25 * traversal will be in the order defined by the backing index. Lookups which
26 * utilize the columns of the index will be fast.
27 *
28 * @author James Ahlborn
29 * @usage _general_class_
30 */
31 public interface IndexCursor extends Cursor
32 {
33
34 public Index getIndex();
35
36 /**
37 * Finds the first row (as defined by the cursor) where the index entries
38 * match the given values. If a match is not found (or an exception is
39 * thrown), the cursor is restored to its previous state.
40 *
41 * @param entryValues the column values for the index's columns.
42 * @return the matching row or {@code null} if a match could not be found.
43 */
44 public Row findRowByEntry(Object... entryValues)
45 throws IOException;
46
47 /**
48 * Moves to the first row (as defined by the cursor) where the index entries
49 * match the given values. If a match is not found (or an exception is
50 * thrown), the cursor is restored to its previous state.
51 * <p>
52 * Warning, this method <i>always</i> starts searching from the beginning of
53 * the Table (you cannot use it to find successive matches).
54 *
55 * @param entryValues the column values for the index's columns.
56 * @return {@code true} if a valid row was found with the given values,
57 * {@code false} if no row was found
58 */
59 public boolean findFirstRowByEntry(Object... entryValues)
60 throws IOException;
61
62 /**
63 * Moves to the first row (as defined by the cursor) where the index entries
64 * are >= the given values. If a an exception is thrown, the cursor is
65 * restored to its previous state.
66 *
67 * @param entryValues the column values for the index's columns.
68 */
69 public void findClosestRowByEntry(Object... entryValues)
70 throws IOException;
71
72 /**
73 * Returns {@code true} if the current row matches the given index entries.
74 *
75 * @param entryValues the column values for the index's columns.
76 */
77 public boolean currentRowMatchesEntry(Object... entryValues)
78 throws IOException;
79
80 /**
81 * Convenience method for constructing a new EntryIterableBuilder for this
82 * cursor. An EntryIterableBuilder provides a variety of options for more
83 * flexible iteration based on a specific index entry.
84 *
85 * @param entryValues the column values for the index's columns.
86 */
87 public EntryIterableBuilder newEntryIterable(Object... entryValues);
88 }