View Javadoc

1   /*
2    *   Copyright 2004 The Apache Software Foundation
3    *
4    *   Licensed under the Apache License, Version 2.0 (the "License");
5    *   you may not use this file except in compliance with the License.
6    *   You may obtain a copy of the License at
7    *
8    *       http://www.apache.org/licenses/LICENSE-2.0
9    *
10   *   Unless required by applicable law or agreed to in writing, software
11   *   distributed under the License is distributed on an "AS IS" BASIS,
12   *   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   *   See the License for the specific language governing permissions and
14   *   limitations under the License.
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      // Simple Table Key/Value Assertions 
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     // Table Value Accessors/Mutators
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     // listTuple overloads
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     // Table Record Count Methods
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 }