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