Table


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.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: 169198 $
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      * @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     // listTuple overloads
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     // Table Record Count Methods
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 }
353
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags