View Javadoc

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