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 */
20 package org.apache.directory.server.xdbm;
21
22
23 import org.apache.directory.server.core.cursor.Cursor;
24
25 import java.util.Comparator;
26
27
28 /**
29 * A wrapper interface around BTree implementations used to abstract away
30 * implementation details.
31 *
32 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
33 * @version $Rev: 662411 $
34 */
35 public interface Table<K, V>
36 {
37 /**
38 * Gets the key comparator used by this Table: may be null if this Table
39 * was not initialized with one.
40 *
41 * @return the key comparator or null if this Table was not created with
42 * one.
43 */
44 Comparator<K> getKeyComparator();
45
46
47 /**
48 * Gets the value comparator used by this Table: may be null if this Table
49 * was not initialized with one.
50 *
51 * @return the value comparator or null if this Table was not created with
52 * one.
53 */
54 Comparator<V> getValueComparator();
55
56
57 /**
58 * Gets the name of this Table.
59 *
60 * @return the name
61 */
62 String getName();
63
64
65 /**
66 * Checks to see if this Table has allows for duplicate keys (a.k.a.
67 * multiple values for the same key).
68 *
69 * @return true if duplicate keys are enabled, false otherwise
70 */
71 boolean isDupsEnabled();
72
73
74 /**
75 * Checks whether or not calls to count the number of keys greater than or
76 * less than the key are exact.
77 *
78 * Checking to see the number of values greater than or less than some key
79 * may be excessively costly. Since this is not a critical function but
80 * one that assists in optimizing searches some implementations can just
81 * return a worst case (maximum) guess.
82 *
83 * @return true if the count is an exact value or a worst case guess
84 */
85 boolean isCountExact();
86
87
88 // ------------------------------------------------------------------------
89 // Simple Table Key/Value Assertions
90 // ------------------------------------------------------------------------
91
92
93 /**
94 * Checks to see if this table has one or more tuples with a specific key:
95 * this is exactly the same as a get call with a check to see if the
96 * returned value is null or not.
97 *
98 * @param key the Object of the key to check for
99 * @return true if the key exists, false otherwise
100 * @throws Exception if there is a failure to read the underlying Db
101 */
102 boolean has( K key ) throws Exception;
103
104
105 /**
106 * Checks to see if this table has a key with a specific value.
107 *
108 * @param key the key to check for
109 * @param value the value to check for
110 * @return true if a record with the key and value exists, false otherwise
111 * @throws Exception if there is a failure to read the underlying Db
112 */
113 boolean has( K key, V value ) throws Exception;
114
115
116 /**
117 * Checks to see if this table has a record with a key greater than or
118 * equal to the key argument. The key argument need not exist for this
119 * call to return true. The underlying database must sort keys based on a
120 * key comparator because this method depends on key ordering.
121 *
122 * @param key the key to compare keys to
123 * @return true if a Tuple with a key greater than or equal to the key
124 * argument exists, false otherwise
125 * @throws Exception if there is a failure to read the underlying Db
126 */
127 boolean hasGreaterOrEqual( K key ) throws Exception;
128
129
130 /**
131 * Checks to see if this table has a record with a key less than or
132 * equal to the key argument. The key argument need not exist for this
133 * call to return true. The underlying database must sort keys based on a
134 * key comparator because this method depends on key ordering.
135 *
136 * @param key the key to compare keys to
137 * @return true if a Tuple with a key less than or equal to the key
138 * argument exists, false otherwise
139 * @throws Exception if there is a failure to read the underlying Db
140 */
141 boolean hasLessOrEqual( K key ) throws Exception;
142
143
144 /**
145 * Checks to see if this table has a Tuple with a key equal to the key
146 * argument, yet with a value greater than or equal to the value argument
147 * provided. The key argument <strong>MUST</strong> exist for this call
148 * to return true and the underlying Db must allow for values of duplicate
149 * keys to be sorted. The entire basis to this method depends on the fact
150 * that tuples of the same key have values sorted according to a valid
151 * value comparator.
152 *
153 * If the table does not support duplicates then an
154 * UnsupportedOperationException is thrown.
155 *
156 * @param key the key
157 * @param val the value to compare values to
158 * @return true if a Tuple with a key equal to the key argument and a
159 * value greater than the value argument exists, false otherwise
160 * @throws Exception if there is a failure to read the underlying Db
161 * or if the underlying Db is not of the Btree type that allows sorted
162 * duplicate values.
163 */
164 boolean hasGreaterOrEqual( K key, V val ) throws Exception;
165
166
167 /**
168 * Checks to see if this table has a Tuple with a key equal to the key
169 * argument, yet with a value less than or equal to the value argument
170 * provided. The key argument <strong>MUST</strong> exist for this call
171 * to return true and the underlying Db must allow for values of duplicate
172 * keys to be sorted. The entire basis to this method depends on the fact
173 * that tuples of the same key have values sorted according to a valid
174 * value comparator.
175 *
176 * If the table does not support duplicates then an
177 * UnsupportedOperationException is thrown.
178 *
179 * @param key the key
180 * @param val the value to compare values to
181 * @return true if a Tuple with a key equal to the key argument and a
182 * value less than the value argument exists, false otherwise
183 * @throws Exception if there is a failure to read the underlying Db
184 * or if the underlying Db is not of the Btree type that allows sorted
185 * duplicate values.
186 */
187 boolean hasLessOrEqual( K key, V val ) throws Exception;
188
189
190 // ------------------------------------------------------------------------
191 // Table Value Accessors/Mutators
192 // ------------------------------------------------------------------------
193
194 /**
195 * Gets the value of a record by key if the key exists. If this Table
196 * allows duplicate keys then the first key will be returned. If this
197 * Table sorts keys then the key will be the smallest key in the Table as
198 * specificed by this Table's comparator or the default bytewise lexical
199 * comparator.
200 *
201 * @param key the key of the record
202 * @return the value of the record with the specified key if key exists or
203 * null if no such key exists.
204 * @throws Exception if there is a failure to read the underlying Db
205 */
206 V get( K key ) throws Exception;
207
208
209 /**
210 * Puts a record into this Table. Null is not allowed for keys or values
211 * and should result in an IllegalArgumentException.
212 *
213 * @param key the key of the record
214 * @param value the value of the record.
215 * @throws Exception if there is a failure to read or write to the
216 * underlying Db
217 * @throws IllegalArgumentException if a null key or value is used
218 */
219 void put( K key, V value ) throws Exception;
220
221
222 /**
223 * Removes all records with a specified key from this Table.
224 *
225 * @param key the key of the records to remove
226 * @throws Exception if there is a failure to read or write to
227 * the underlying Db
228 */
229 void remove( K key ) throws Exception;
230
231
232 /**
233 * Removes a single key value pair with a specified key and value from
234 * this Table.
235 *
236 * @param key the key of the record to remove
237 * @param value the value of the record to remove
238 * @throws Exception if there is a failure to read or write to
239 * the underlying Db
240 */
241 void remove( K key, V value ) throws Exception;
242
243
244 /**
245 * Creates a Cursor that traverses Tuples in a Table.
246 *
247 * @return a Cursor over Tuples containing the key value pairs
248 * @throws Exception if there are failures accessing underlying stores
249 */
250 Cursor<Tuple<K,V>> cursor() throws Exception;
251
252
253 /**
254 * Creates a Cursor that traverses Table Tuples for the same key. Only
255 * Tuples with the provided key will be returned if the key exists at
256 * all. If the key does not exist an empty Cursor is returned. The
257 * motivation behind this method is to minimize the need for callers to
258 * actively constrain Cursor operations based on the Tuples they return
259 * to a specific key. This Cursor is naturally limited to return only
260 * the tuples for the same key.
261 *
262 * @param key the duplicate key to return the Tuples of
263 * @return a Cursor over Tuples containing the same key
264 * @throws Exception if there are failures accessing underlying stores
265 */
266 Cursor<Tuple<K,V>> cursor( K key ) throws Exception;
267
268
269 /**
270 * Creates a Cursor that traverses Table values for the same key. Only
271 * Tuples with the provided key will have their values returned if the key
272 * exists at all. If the key does not exist an empty Cursor is returned.
273 * The motivation behind this method is to minimize the need for callers
274 * to actively constrain Cursor operations to a specific key while
275 * removing overheads in creating new Tuples or population one that is
276 * reused to return key value pairs. This Cursor is naturally limited to
277 * return only the values for the same key.
278 *
279 * @param key the duplicate key to return the values of
280 * @return a Cursor over values of a key
281 * @throws Exception if there are failures accessing underlying stores
282 */
283 Cursor<V> valueCursor( K key ) throws Exception;
284
285
286 // ------------------------------------------------------------------------
287 // Table Record Count Methods
288 // ------------------------------------------------------------------------
289
290
291 /**
292 * Gets the count of the number of records in this Table.
293 *
294 * @return the number of records
295 * @throws Exception if there is a failure to read the underlying Db
296 */
297 int count() throws Exception;
298
299
300 /**
301 * Gets the count of the number of records in this Table with a specific
302 * key: returns the number of duplicates for a key.
303 *
304 * @param key the Object key to count.
305 * @return the number of duplicate records for a key.
306 * @throws Exception if there is a failure to read the underlying Db
307 */
308 int count( K key ) throws Exception;
309
310
311 /**
312 * Gets the number of records greater than or equal to a key value. The
313 * specific key argument provided need not exist for this call to return
314 * a non-zero value.
315 *
316 * @param key the key to use in comparisons
317 * @return the number of keys greater than or equal to the key
318 * @throws Exception if there is a failure to read the underlying db
319 */
320 int greaterThanCount( K key ) throws Exception;
321
322
323 /**
324 * Gets the number of records less than or equal to a key value. The
325 * specific key argument provided need not exist for this call to return
326 * a non-zero value.
327 *
328 * @param key the key to use in comparisons
329 * @return the number of keys less than or equal to the key
330 * @throws Exception if there is a failure to read the underlying db
331 */
332 int lessThanCount( K key ) throws Exception;
333
334
335 /**
336 * Closes the underlying Db of this Table.
337 *
338 * @throws Exception on any failures
339 */
340 void close() throws Exception;
341 }