1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17 package org.apache.ldap.server.db;
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: 157708 $
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 * @return TODO
186 * @throws NamingException if something goes wrong
187 */
188 Object put( Object key, NamingEnumeration values ) throws NamingException;
189
190 /***
191 * Removes all records with key from this Table.
192 *
193 * @param key the key of the records to remove
194 * @return TODO
195 * @throws NamingException if there is a failure to read or write to
196 * the underlying Db
197 */
198 Object remove( Object key ) throws NamingException;
199
200 /***
201 * Removes a single specific record with key and value from this Table.
202 *
203 * @param key the key of the record to remove
204 * @param value the value of the record to remove
205 * @return TODO
206 * @throws NamingException if there is a failure to read or write to
207 * the underlying Db
208 */
209 Object remove( Object key, Object value ) throws NamingException;
210
211
212 /***
213 * Removes a set of values with the same key from this Table. If this
214 * table does not allow duplicates the method will attempt to remove the
215 * first value in the enumeration if one exists. If there is more than one
216 * value within the enumeration after the first drop an
217 * UnsupportedOperationException is thrown. Nothing is removed if there is
218 * more than one element on the enumeration and the table does not support
219 * duplicates.
220 *
221 * @param key the key of the records to remove
222 * @param values TODO
223 * @return TODO
224 * @throws NamingException if there is a failure to read or write to
225 * the underlying Db
226 */
227 Object remove( Object key, NamingEnumeration values )
228 throws NamingException;
229
230
231 /***
232 * Sets a enumeration to the first record in the Table with a key value of
233 * key and enables single next steps across all duplicate records with
234 * this key. This enumeration will only iterate over duplicates of the key.
235 * Unlike listTuples(Object) which returns Tuples from the enumerations
236 * advances methods this call returns an enumeration with just the values
237 * of the key.
238 *
239 * @param key the key to iterate over
240 * @return TODO
241 * @throws NamingException if the underlying browser could not be set
242 */
243 NamingEnumeration listValues( Object key ) throws NamingException;
244
245
246
247
248
249
250
251 /***
252 * Sets a cursor to the first record in the Table and enables single
253 * next steps across all records.
254 *
255 * @return TODO
256 * @throws NamingException if the underlying cursor could not be set.
257 */
258 NamingEnumeration listTuples() throws NamingException;
259
260 /***
261 * Sets a cursor to the first record in the Table with a key value of
262 * key and enables single next steps across all duplicate records with
263 * this key. This cursor will only iterate over duplicates of the key.
264 *
265 * @param key the key to iterate over
266 * @return TODO
267 * @throws NamingException if the underlying cursor could not be set
268 */
269 NamingEnumeration listTuples( Object key ) throws NamingException;
270
271 /***
272 * Sets a cursor to the first record in the Table with a key value
273 * greater/less than or equal to key and enables single next steps across
274 * all records with key values equal to or less/greater than key.
275 *
276 * @param key the key to use to position this cursor to record with a key
277 * greater/less than or equal to it
278 * @param isGreaterThan if true the cursor iterates up over ascending keys
279 * greater than or equal to the key argument, but if false this cursor
280 * iterates down over descending keys less than or equal to key argument
281 * @return TODO
282 * @throws NamingException if the underlying cursor could not be set
283 */
284 NamingEnumeration listTuples( Object key, boolean isGreaterThan )
285 throws NamingException;
286
287 /***
288 * Sets a cursor to the first record in the Table with a key equal to
289 * the key argument whose value is greater/less than or equal to key and
290 * enables single next steps across all records with key equal to key.
291 * Hence this cursor will only iterate over duplicate keys where values are
292 * less than or greater than or equal to val.
293 *
294 * @param key the key to use to position this cursor to record with a key
295 * equal to it.
296 * @param val the value to use to position this cursor to record with a
297 * value greater/less than or equal to it.
298 * @param isGreaterThan if true the cursor iterates up over ascending
299 * values greater than or equal to the val argument, but if false this
300 * cursor iterates down over descending values less than or equal to val
301 * argument starting from the largest value going down
302 * @return TODO
303 * @throws NamingException if the underlying cursor could not be set or
304 * this method is called over a cursor on a table that does not have sorted
305 * duplicates enabled.
306 */
307 NamingEnumeration listTuples( Object key, Object val, boolean isGreaterThan )
308 throws NamingException;
309
310
311
312
313
314
315
316 /***
317 * Gets the count of the number of records in this Table.
318 *
319 * @return the number of records
320 * @throws NamingException if there is a failure to read the underlying Db
321 */
322 int count() throws NamingException;
323
324 /***
325 * Gets the count of the number of records in this Table with a specific
326 * key: returns the number of duplicates for a key.
327 *
328 * @param key the Object key to count.
329 * @return the number of duplicate records for a key.
330 * @throws NamingException if there is a failure to read the underlying Db
331 */
332 int count( Object key ) throws NamingException;
333
334 /***
335 * Returns the number of records greater than or less than a key value. The
336 * key need not exist for this call to return a non-zero value.
337 *
338 * @param key the Object key to count.
339 * @param isGreaterThan boolean set to true to count for greater than and
340 * equal to record keys, or false for less than or equal to keys.
341 * @return the number of keys greater or less than key.
342 * @throws NamingException if there is a failure to read the underlying Db
343 */
344 int count( Object key, boolean isGreaterThan ) throws NamingException;
345
346 /***
347 * Closes the underlying Db of this Table.
348 *
349 * @throws NamingException on any failures
350 */
351 void close() throws NamingException;
352 }