001 /*
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements. See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership. The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License. You may obtain a copy of the License at
009 *
010 * http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing,
013 * software distributed under the License is distributed on an
014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 * KIND, either express or implied. See the License for the
016 * specific language governing permissions and limitations
017 * under the License.
018 *
019 */
020 package org.apache.directory.server.xdbm;
021
022
023
024 import java.util.Comparator;
025
026 import org.apache.directory.shared.ldap.cursor.Cursor;
027
028
029 /**
030 * A wrapper interface around BTree implementations used to abstract away
031 * implementation details.
032 *
033 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
034 * @version $Rev: 774124 $
035 */
036 public interface Table<K, V>
037 {
038 /**
039 * Gets the key comparator used by this Table: may be null if this Table
040 * was not initialized with one.
041 *
042 * @return the key comparator or null if this Table was not created with
043 * one.
044 */
045 Comparator<K> getKeyComparator();
046
047
048 /**
049 * Gets the value comparator used by this Table: may be null if this Table
050 * was not initialized with one.
051 *
052 * @return the value comparator or null if this Table was not created with
053 * one.
054 */
055 Comparator<V> getValueComparator();
056
057
058 /**
059 * Gets the name of this Table.
060 *
061 * @return the name
062 */
063 String getName();
064
065
066 /**
067 * Checks to see if this Table has allows for duplicate keys (a.k.a.
068 * multiple values for the same key).
069 *
070 * @return true if duplicate keys are enabled, false otherwise
071 */
072 boolean isDupsEnabled();
073
074
075 /**
076 * Checks whether or not calls to count the number of keys greater than or
077 * less than the key are exact.
078 *
079 * Checking to see the number of values greater than or less than some key
080 * may be excessively costly. Since this is not a critical function but
081 * one that assists in optimizing searches some implementations can just
082 * return a worst case (maximum) guess.
083 *
084 * @return true if the count is an exact value or a worst case guess
085 */
086 boolean isCountExact();
087
088
089 // ------------------------------------------------------------------------
090 // Simple Table Key/Value Assertions
091 // ------------------------------------------------------------------------
092
093
094 /**
095 * Checks to see if this table has one or more tuples with a specific key:
096 * this is exactly the same as a get call with a check to see if the
097 * returned value is null or not.
098 *
099 * @param key the Object of the key to check for
100 * @return true if the key exists, false otherwise
101 * @throws Exception if there is a failure to read the underlying Db
102 */
103 boolean has( K key ) throws Exception;
104
105
106 /**
107 * Checks to see if this table has a key with a specific value.
108 *
109 * @param key the key to check for
110 * @param value the value to check for
111 * @return true if a record with the key and value exists, false otherwise
112 * @throws Exception if there is a failure to read the underlying Db
113 */
114 boolean has( K key, V value ) throws Exception;
115
116
117 /**
118 * Checks to see if this table has a record with a key greater than or
119 * equal to the key argument. The key argument need not exist for this
120 * call to return true. The underlying database must sort keys based on a
121 * key comparator because this method depends on key ordering.
122 *
123 * @param key the key to compare keys to
124 * @return true if a Tuple with a key greater than or equal to the key
125 * argument exists, false otherwise
126 * @throws Exception if there is a failure to read the underlying Db
127 */
128 boolean hasGreaterOrEqual( K key ) throws Exception;
129
130
131 /**
132 * Checks to see if this table has a record with a key less than or
133 * equal to the key argument. The key argument need not exist for this
134 * call to return true. The underlying database must sort keys based on a
135 * key comparator because this method depends on key ordering.
136 *
137 * @param key the key to compare keys to
138 * @return true if a Tuple with a key less than or equal to the key
139 * argument exists, false otherwise
140 * @throws Exception if there is a failure to read the underlying Db
141 */
142 boolean hasLessOrEqual( K key ) throws Exception;
143
144
145 /**
146 * Checks to see if this table has a Tuple with a key equal to the key
147 * argument, yet with a value greater than or equal to the value argument
148 * provided. The key argument <strong>MUST</strong> exist for this call
149 * to return true and the underlying Db must allow for values of duplicate
150 * keys to be sorted. The entire basis to this method depends on the fact
151 * that tuples of the same key have values sorted according to a valid
152 * value comparator.
153 *
154 * If the table does not support duplicates then an
155 * UnsupportedOperationException is thrown.
156 *
157 * @param key the key
158 * @param val the value to compare values to
159 * @return true if a Tuple with a key equal to the key argument and a
160 * value greater than the value argument exists, false otherwise
161 * @throws Exception if there is a failure to read the underlying Db
162 * or if the underlying Db is not of the Btree type that allows sorted
163 * duplicate values.
164 */
165 boolean hasGreaterOrEqual( K key, V val ) throws Exception;
166
167
168 /**
169 * Checks to see if this table has a Tuple with a key equal to the key
170 * argument, yet with a value less than or equal to the value argument
171 * provided. The key argument <strong>MUST</strong> exist for this call
172 * to return true and the underlying Db must allow for values of duplicate
173 * keys to be sorted. The entire basis to this method depends on the fact
174 * that tuples of the same key have values sorted according to a valid
175 * value comparator.
176 *
177 * If the table does not support duplicates then an
178 * UnsupportedOperationException is thrown.
179 *
180 * @param key the key
181 * @param val the value to compare values to
182 * @return true if a Tuple with a key equal to the key argument and a
183 * value less than the value argument exists, false otherwise
184 * @throws Exception if there is a failure to read the underlying Db
185 * or if the underlying Db is not of the Btree type that allows sorted
186 * duplicate values.
187 */
188 boolean hasLessOrEqual( K key, V val ) throws Exception;
189
190
191 // ------------------------------------------------------------------------
192 // Table Value Accessors/Mutators
193 // ------------------------------------------------------------------------
194
195 /**
196 * Gets the value of a record by key if the key exists. If this Table
197 * allows duplicate keys then the first key will be returned. If this
198 * Table sorts keys then the key will be the smallest key in the Table as
199 * specificed by this Table's comparator or the default bytewise lexical
200 * comparator.
201 *
202 * @param key the key of the record
203 * @return the value of the record with the specified key if key exists or
204 * null if no such key exists.
205 * @throws Exception if there is a failure to read the underlying Db
206 */
207 V get( K key ) throws Exception;
208
209
210 /**
211 * Puts a record into this Table. Null is not allowed for keys or values
212 * and should result in an IllegalArgumentException.
213 *
214 * @param key the key of the record
215 * @param value the value of the record.
216 * @throws Exception if there is a failure to read or write to the
217 * underlying Db
218 * @throws IllegalArgumentException if a null key or value is used
219 */
220 void put( K key, V value ) throws Exception;
221
222
223 /**
224 * Removes all records with a specified key from this Table.
225 *
226 * @param key the key of the records to remove
227 * @throws Exception if there is a failure to read or write to
228 * the underlying Db
229 */
230 void remove( K key ) throws Exception;
231
232
233 /**
234 * Removes a single key value pair with a specified key and value from
235 * this Table.
236 *
237 * @param key the key of the record to remove
238 * @param value the value of the record to remove
239 * @throws Exception if there is a failure to read or write to
240 * the underlying Db
241 */
242 void remove( K key, V value ) throws Exception;
243
244
245 /**
246 * Creates a Cursor that traverses Tuples in a Table.
247 *
248 * @return a Cursor over Tuples containing the key value pairs
249 * @throws Exception if there are failures accessing underlying stores
250 */
251 Cursor<Tuple<K,V>> cursor() throws Exception;
252
253
254 /**
255 * Creates a Cursor that traverses Table Tuples for the same key. Only
256 * Tuples with the provided key will be returned if the key exists at
257 * all. If the key does not exist an empty Cursor is returned. The
258 * motivation behind this method is to minimize the need for callers to
259 * actively constrain Cursor operations based on the Tuples they return
260 * to a specific key. This Cursor is naturally limited to return only
261 * the tuples for the same key.
262 *
263 * @param key the duplicate key to return the Tuples of
264 * @return a Cursor over Tuples containing the same key
265 * @throws Exception if there are failures accessing underlying stores
266 */
267 Cursor<Tuple<K,V>> cursor( K key ) throws Exception;
268
269
270 /**
271 * Creates a Cursor that traverses Table values for the same key. Only
272 * Tuples with the provided key will have their values returned if the key
273 * exists at all. If the key does not exist an empty Cursor is returned.
274 * The motivation behind this method is to minimize the need for callers
275 * to actively constrain Cursor operations to a specific key while
276 * removing overheads in creating new Tuples or population one that is
277 * reused to return key value pairs. This Cursor is naturally limited to
278 * return only the values for the same key.
279 *
280 * @param key the duplicate key to return the values of
281 * @return a Cursor over values of a key
282 * @throws Exception if there are failures accessing underlying stores
283 */
284 Cursor<V> valueCursor( K key ) throws Exception;
285
286
287 // ------------------------------------------------------------------------
288 // Table Record Count Methods
289 // ------------------------------------------------------------------------
290
291
292 /**
293 * Gets the count of the number of records in this Table.
294 *
295 * @return the number of records
296 * @throws Exception if there is a failure to read the underlying Db
297 */
298 int count() throws Exception;
299
300
301 /**
302 * Gets the count of the number of records in this Table with a specific
303 * key: returns the number of duplicates for a key.
304 *
305 * @param key the Object key to count.
306 * @return the number of duplicate records for a key.
307 * @throws Exception if there is a failure to read the underlying Db
308 */
309 int count( K key ) throws Exception;
310
311
312 /**
313 * Gets the number of records greater than or equal to a key value. The
314 * specific key argument provided need not exist for this call to return
315 * a non-zero value.
316 *
317 * @param key the key to use in comparisons
318 * @return the number of keys greater than or equal to the key
319 * @throws Exception if there is a failure to read the underlying db
320 */
321 int greaterThanCount( K key ) throws Exception;
322
323
324 /**
325 * Gets the number of records less than or equal to a key value. The
326 * specific key argument provided need not exist for this call to return
327 * a non-zero value.
328 *
329 * @param key the key to use in comparisons
330 * @return the number of keys less than or equal to the key
331 * @throws Exception if there is a failure to read the underlying db
332 */
333 int lessThanCount( K key ) throws Exception;
334
335
336 /**
337 * Closes the underlying Db of this Table.
338 *
339 * @throws Exception on any failures
340 */
341 void close() throws Exception;
342 }