1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17 package org.apache.ldap.server.partition.impl.btree;
18
19
20 import javax.naming.NamingEnumeration;
21 import javax.naming.NamingException;
22
23
24 /***
25 * A backend friendly wrapper around a JDBM BTree that transparent enables
26 * duplicates when the BTree does not support them.
27 *
28 * TODO Need to rewrite the Javadocs in this interface.
29 *
30 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
31 * @version $Rev: 264732 $
32 */
33 public interface Table
34 {
35 /***
36 * Gets the comparator used by this Table: may be null if this Table was
37 * not initialized with one.
38 *
39 * @return the final comparator instance or null if this Table was not
40 * created with one.
41 */
42 TupleComparator getComparator();
43
44 /***
45 * Gets the data renderer used by this Table to display or log records keys
46 * and values.
47 *
48 * @return the renderer used
49 */
50 TupleRenderer getRenderer();
51
52 /***
53 * Sets the data renderer to by used by this Table to display or log record
54 * keys and values.
55 *
56 * @param renderer the DataRenderer instance to used as the renderer.
57 */
58 void setRenderer( TupleRenderer renderer );
59
60 /***
61 * Gets the name of this Table.
62 *
63 * @return the name
64 */
65 String getName();
66
67 /***
68 * Checks to see if this Table has enabled the use of duplicate keys.
69 *
70 * @return true if duplicate keys are enabled, false otherwise.
71 */
72 boolean isDupsEnabled();
73
74 /***
75 * Checks to see if this Table has enabled sorting on the values of
76 * duplicate keys.
77 *
78 * @return true if duplicate key values are sorted, false otherwise.
79 */
80 boolean isSortedDupsEnabled();
81
82
83
84
85
86
87
88 /***
89 * Checks to see if this table has a key: same as a get call with a check to
90 * see if the returned value is null or not.
91 *
92 * @param key the Object of the key to check for
93 * @return true if the key exists, false otherwise.
94 * @throws NamingException if there is a failure to read the underlying Db
95 */
96 boolean has( Object key ) throws NamingException;
97
98 /***
99 * Checks to see if this table has a key with a specific value.
100 *
101 * @param key the key Object to check for
102 * @param value the value Object to check for
103 * @return true if a record with the key and value exists, false otherwise.
104 * @throws NamingException if there is a failure to read the underlying Db
105 */
106 boolean has( Object key, Object value ) throws NamingException;
107
108 /***
109 * Checks to see if this table has a record with a key greater/less than or
110 * equal to the key argument. The key argument need not exist for this
111 * call to return true. The underlying database must be a BTree because
112 * this method depends on the use of sorted keys.
113 *
114 * @param key the key Object to compare keys to
115 * @param isGreaterThan boolean for greater than or less then comparison
116 * @return true if a record with a key greater/less than the key argument
117 * exists, false otherwise
118 * @throws NamingException if there is a failure to read the underlying Db,
119 * or if the underlying Db is not a Btree.
120 */
121 boolean has( Object key, boolean isGreaterThan ) throws NamingException;
122
123 /***
124 * Checks to see if this table has a record with a key equal to the
125 * argument key with a value greater/less than or equal to the value
126 * argument provided. The key argument <strong>MUST</strong> exist for
127 * this call to return true and the underlying Db must be a Btree that
128 * allows for sorted duplicate values. The entire basis to this method
129 * depends on the fact that duplicate key values are sorted according to
130 * a valid value comparator function.
131 *
132 * @param key the key Object
133 * @param val the value Object to compare values to
134 * @param isGreaterThan boolean for greater than or less then comparison
135 * @return true if a record with a key greater/less than the key argument
136 * exists, false otherwise
137 * @throws NamingException if there is a failure to read the underlying Db
138 * or if the underlying Db is not of the Btree type that allows sorted
139 * duplicate values.
140 */
141 boolean has( Object key, Object val, boolean isGreaterThan )
142 throws NamingException;
143
144
145
146
147
148
149 /***
150 * Gets the value of a record by key if the key exists. If this Table
151 * allows duplicate keys then the first key will be returned. If this
152 * Table is also a Btree that first key will be the smallest key in the
153 * Table as specificed by this Table's comparator or the default berkeley
154 * bytewise lexical comparator.
155 *
156 * @param key the key of the record
157 * @return the value of the record with key if key exists or null if
158 * no such record exists.
159 * @throws NamingException if there is a failure to read the underlying Db
160 */
161 Object get( Object key ) throws NamingException;
162
163 /***
164 * Puts a record into this Table.
165 *
166 * @param key the key of the record
167 * @param value the value of the record.
168 * @return the last value present for key or null if this the key did not
169 * exist before.
170 * @throws NamingException if there is a failure to read or write to
171 * the underlying Db
172 */
173 Object put( Object key, Object value ) throws NamingException;
174
175 /***
176 * Efficiently puts a set of values into the Table. If the Table does not
177 * support duplicate keys then only the first key within the enumeration is
178 * added. If there are more elements left after this single addition an
179 * UnsupportedOperationException is thrown. Nothing is added if the table
180 * does not support duplicates and there is more than one element in the
181 * enumeration.
182 *
183 * @param key the key to use for the values
184 * @param values the values supplied as an enumeration
185 * @throws NamingException if something goes wrong
186 */
187 Object put( Object key, NamingEnumeration values ) throws NamingException;
188
189 /***
190 * Removes all records with key from this Table.
191 *
192 * @param key the key of the records to remove
193 * @throws NamingException if there is a failure to read or write to
194 * the underlying Db
195 */
196 Object remove( Object key ) throws NamingException;
197
198 /***
199 * Removes a single specific record with key and value from this Table.
200 *
201 * @param key the key of the record to remove
202 * @param value the value of the record to remove
203 * @throws NamingException if there is a failure to read or write to
204 * the underlying Db
205 */
206 Object remove( Object key, Object value ) throws NamingException;
207
208
209 /***
210 * Removes a set of values with the same key from this Table. If this
211 * table does not allow duplicates the method will attempt to remove the
212 * first value in the enumeration if one exists. If there is more than one
213 * value within the enumeration after the first drop an
214 * UnsupportedOperationException is thrown. Nothing is removed if there is
215 * more than one element on the enumeration and the table does not support
216 * duplicates.
217 *
218 * @param key the key of the records to remove
219 * @throws NamingException if there is a failure to read or write to
220 * the underlying Db
221 */
222 Object remove( Object key, NamingEnumeration values )
223 throws NamingException;
224
225
226 /***
227 * Sets a enumeration to the first record in the Table with a key value of
228 * key and enables single next steps across all duplicate records with
229 * this key. This enumeration will only iterate over duplicates of the key.
230 * Unlike listTuples(Object) which returns Tuples from the enumerations
231 * advances methods this call returns an enumeration with just the values
232 * of the key.
233 *
234 * @param key the key to iterate over
235 * @throws NamingException if the underlying browser could not be set
236 */
237 NamingEnumeration listValues( Object key ) throws NamingException;
238
239
240
241
242
243
244
245 /***
246 * Sets a cursor to the first record in the Table and enables single
247 * next steps across all records.
248 *
249 * @throws NamingException if the underlying cursor could not be set.
250 */
251 NamingEnumeration listTuples() throws NamingException;
252
253 /***
254 * Sets a cursor to the first record in the Table with a key value of
255 * key and enables single next steps across all duplicate records with
256 * this key. This cursor will only iterate over duplicates of the key.
257 *
258 * @param key the key to iterate over
259 * @throws NamingException if the underlying cursor could not be set
260 */
261 NamingEnumeration listTuples( Object key ) throws NamingException;
262
263 /***
264 * Sets a cursor to the first record in the Table with a key value
265 * greater/less than or equal to key and enables single next steps across
266 * all records with key values equal to or less/greater than key.
267 *
268 * @param key the key to use to position this cursor to record with a key
269 * greater/less than or equal to it
270 * @param isGreaterThan if true the cursor iterates up over ascending keys
271 * greater than or equal to the key argument, but if false this cursor
272 * iterates down over descending keys less than or equal to key argument
273 * @throws NamingException if the underlying cursor could not be set
274 */
275 NamingEnumeration listTuples( Object key, boolean isGreaterThan )
276 throws NamingException;
277
278 /***
279 * Sets a cursor to the first record in the Table with a key equal to
280 * the key argument whose value is greater/less than or equal to key and
281 * enables single next steps across all records with key equal to key.
282 * Hence this cursor will only iterate over duplicate keys where values are
283 * less than or greater than or equal to val.
284 *
285 * @param key the key to use to position this cursor to record with a key
286 * equal to it.
287 * @param val the value to use to position this cursor to record with a
288 * value greater/less than or equal to it.
289 * @param isGreaterThan if true the cursor iterates up over ascending
290 * values greater than or equal to the val argument, but if false this
291 * cursor iterates down over descending values less than or equal to val
292 * argument starting from the largest value going down
293 * @throws NamingException if the underlying cursor could not be set or
294 * this method is called over a cursor on a table that does not have sorted
295 * duplicates enabled.
296 */
297 NamingEnumeration listTuples( Object key, Object val, boolean isGreaterThan )
298 throws NamingException;
299
300
301
302
303
304
305
306 /***
307 * Gets the count of the number of records in this Table.
308 *
309 * @return the number of records
310 * @throws NamingException if there is a failure to read the underlying Db
311 */
312 int count() throws NamingException;
313
314 /***
315 * Gets the count of the number of records in this Table with a specific
316 * key: returns the number of duplicates for a key.
317 *
318 * @param key the Object key to count.
319 * @return the number of duplicate records for a key.
320 * @throws NamingException if there is a failure to read the underlying Db
321 */
322 int count( Object key ) throws NamingException;
323
324 /***
325 * Returns the number of records greater than or less than a key value. The
326 * key need not exist for this call to return a non-zero value.
327 *
328 * @param key the Object key to count.
329 * @param isGreaterThan boolean set to true to count for greater than and
330 * equal to record keys, or false for less than or equal to keys.
331 * @return the number of keys greater or less than key.
332 * @throws NamingException if there is a failure to read the underlying Db
333 */
334 int count( Object key, boolean isGreaterThan ) throws NamingException;
335
336 /***
337 * Closes the underlying Db of this Table.
338 *
339 * @throws NamingException on any failures
340 */
341 void close() throws NamingException;
342 }