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