1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one
3 * or more contributor license agreements. See the NOTICE file
4 * distributed with this work for additional information
5 * regarding copyright ownership. The ASF licenses this file
6 * to you under the Apache License, Version 2.0 (the
7 * "License"); you may not use this file except in compliance
8 * with the License. You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing,
13 * software distributed under the License is distributed on an
14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15 * KIND, either express or implied. See the License for the
16 * specific language governing permissions and limitations
17 * under the License.
18 */
19 package org.apache.myfaces.trinidad.model;
20
21 /**
22 * Defines a set of "local" APIs for a CollectionModel.
23 * The "local" APIs allow a client to query the model and determine if a
24 * set of rows are locally available. "Locally available" can mean the
25 * model has the given set of rows in a local cache and can honor a fetch request
26 * efficiently (for example, without performing a SQL query).
27 */
28 public interface LocalRowKeyIndex
29 {
30
31 /**
32 * Given a row index, check if a row is locally available
33 * @param rowIndex index of row to check
34 * @return <code>true</code> if row is locally available <code>flase</code> otherwise
35 */
36 public boolean isRowLocallyAvailable(int rowIndex);
37
38 /**
39 * Given a row key, check if a row is locally available
40 * @param rowKey row key for the row to check
41 * @return <code>true</code> if row is locally available <code>flase</code> otherwise
42 */
43 public boolean isRowLocallyAvailable(Object rowKey);
44
45 /**
46 * Check if a range of rows is locally available starting from a row index
47 * @param startIndex staring index for the range
48 * @param rowCount number of rows in the range
49 * @return <code>true</code> if range of rows is locally available <code>flase</code> otherwise
50 */
51 public boolean areRowsLocallyAvailable(int startIndex, int rowCount);
52
53 /**
54 * Check if a range of rows is locally available starting from a row key
55 * @param startRowKey staring row key for the range
56 * @param rowCount number of rows in the range
57 * @return <code>true</code> if range of rows is locally available <code>flase</code> otherwise
58 */
59 public boolean areRowsLocallyAvailable(Object startRowKey, int rowCount);
60
61 /**
62 * Check if a range of rows is locally available starting from the current row
63 * @param rowCount number of rows in the range
64 * @return <code>true</code> if range of rows is locally available <code>flase</code> otherwise
65 */
66 public boolean areRowsLocallyAvailable(int rowCount);
67
68 /**
69 * Convenient API to return a row count estimate. This method can be optimized
70 * to avoid a data fetch which may be required to return an exact row count.
71 * <p>
72 * This method can return -1 or a row count estimate if determining
73 * exact row count requires a data fetch. When dealing with estimated row counts,
74 * the caller needs to gracefully handle the case where <code>isRowAvailable</code>
75 * returns <code>false</code> for a row index or a row key.
76 * @return estimated row count
77 */
78 public int getEstimatedRowCount();
79
80
81 /**
82 * Helper API to determine if the row count returned from {@link #getEstimatedRowCount}
83 * is EXACT, or an ESTIMATE
84 */
85 public Confidence getEstimatedRowCountConfidence();
86
87
88 /**
89 * Enum used in the {@link #getEstimatedRowCountConfidence} API to determine
90 * if the row count is exact or an estimate
91 */
92 public enum Confidence
93 {
94 /**
95 * The row count returned by {@link #getEstimatedRowCount} is exact
96 */
97 EXACT,
98
99 /**
100 * The row count returned by {@link #getEstimatedRowCount} is an estimate
101 */
102 ESTIMATE,
103
104 /**
105 * The row count returned by {@link #getEstimatedRowCount} is unknown (-1)
106 */
107 UNKNOWN
108 }
109
110
111 //
112 // Local Cache management APIs
113 //
114
115 /**
116 * clear all rows from the local cache
117 */
118 public void clearLocalCache();
119
120 /**
121 * Clear the requested range of rows from the local cache
122 * @param startingIndex starting row index for the range to clear
123 * @param rowsToClear number of rows to clear from the cache
124 */
125 public void clearCachedRows(int startingIndex, int rowsToClear);
126
127 /**
128 * Clear the requested range of rows from the local cache
129 * @param startingRowKey starting row key for the range to clear
130 * @param rowsToClear number of rows to clear from the cache
131 */
132 public void clearCachedRows(Object startingRowKey, int rowsToClear);
133
134 /**
135 * Clear a row from the local cache by row index
136 * @param index row index for the row to clear from the cache
137 */
138 public void clearCachedRow(int index);
139
140 /**
141 * Clear a row from the local cache by row key
142 * @param rowKey row key for the row to clear from the cache
143 */
144 public void clearCachedRow(Object rowKey);
145
146 /**
147 * Indicates the caching strategy supported by the model
148 * @see LocalCachingStrategy
149 * @return caching strategy supported by the model
150 */
151 public LocalCachingStrategy getCachingStrategy();
152
153 /**
154 * Enum used to indicate the type of caching supported by the model
155 * @see #getCachingStrategy()
156 */
157 public enum LocalCachingStrategy
158 {
159 /**
160 * Caching is not supported
161 */
162 NONE,
163
164 /**
165 * Supports caching certain ranges of rows
166 */
167 PARTIAL,
168
169 /**
170 * Caches all rows
171 */
172 ALL
173 }
174 }