001    /*
002     *  Licensed to the Apache Software Foundation (ASF) under one
003     *  or more contributor license agreements.  See the NOTICE file
004     *  distributed with this work for additional information
005     *  regarding copyright ownership.  The ASF licenses this file
006     *  to you under the Apache License, Version 2.0 (the
007     *  "License"); you may not use this file except in compliance
008     *  with the License.  You may obtain a copy of the License at
009     *  
010     *    http://www.apache.org/licenses/LICENSE-2.0
011     *  
012     *  Unless required by applicable law or agreed to in writing,
013     *  software distributed under the License is distributed on an
014     *  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015     *  KIND, either express or implied.  See the License for the
016     *  specific language governing permissions and limitations
017     *  under the License. 
018     *  
019     */
020    package org.apache.directory.server.xdbm;
021    
022    
023    import java.util.Comparator;
024    
025    import org.apache.directory.shared.ldap.cursor.Cursor;
026    
027    
028    /**
029     * A wrapper interface around BTree implementations used to abstract away
030     * implementation details.
031     * 
032     * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
033     * @version $Rev: 917231 $
034     */
035    public interface Table<K, V>
036    {
037        /**
038         * Gets the key comparator used by this Table: may be null if this Table
039         * was not initialized with one.
040         *
041         * @return the key comparator or null if this Table was not created with
042         * one.
043         */
044        Comparator<K> getKeyComparator();
045    
046    
047        /**
048         * Gets the value comparator used by this Table: may be null if this Table
049         * was not initialized with one.
050         *
051         * @return the value comparator or null if this Table was not created with
052         * one.
053         */
054        Comparator<V> getValueComparator();
055    
056    
057        /**
058         * Gets the name of this Table.
059         *
060         * @return the name
061         */
062        String getName();
063    
064    
065        /**
066         * Checks to see if this Table has allows for duplicate keys (a.k.a.
067         * multiple values for the same key).
068         *
069         * @return true if duplicate keys are enabled, false otherwise
070         */
071        boolean isDupsEnabled();
072    
073    
074        /**
075         * Checks whether or not calls to count the number of keys greater than or
076         * less than the key are exact.
077         * 
078         * Checking to see the number of values greater than or less than some key
079         * may be excessively costly.  Since this is not a critical function but 
080         * one that assists in optimizing searches some implementations can just 
081         * return a worst case (maximum) guess.  
082         *
083         * @return true if the count is an exact value or a worst case guess 
084         */
085        boolean isCountExact();
086    
087    
088        // ------------------------------------------------------------------------
089        // Simple Table Key/Value Assertions 
090        // ------------------------------------------------------------------------
091    
092        /**
093         * Checks to see if this table has one or more tuples with a specific key:
094         * this is exactly the same as a get call with a check to see if the
095         * returned value is null or not.
096         *
097         * @param key the Object of the key to check for
098         * @return true if the key exists, false otherwise
099         * @throws Exception if there is a failure to read the underlying Db
100         */
101        boolean has( K key ) throws Exception;
102    
103    
104        /**
105         * Checks to see if this table has a key with a specific value.
106         *
107         * @param key the key to check for
108         * @param value the value to check for
109         * @return true if a record with the key and value exists, false otherwise
110         * @throws Exception if there is a failure to read the underlying Db
111         */
112        boolean has( K key, V value ) throws Exception;
113    
114    
115        /**
116         * Checks to see if this table has a record with a key greater than or
117         * equal to the key argument.  The key argument need not exist for this
118         * call to return true.  The underlying database must sort keys based on a
119         * key comparator because this method depends on key ordering.
120         *
121         * @param key the key to compare keys to
122         * @return true if a Tuple with a key greater than or equal to the key
123         * argument exists, false otherwise
124         * @throws Exception if there is a failure to read the underlying Db
125         */
126        boolean hasGreaterOrEqual( K key ) throws Exception;
127    
128    
129        /**
130         * Checks to see if this table has a record with a key less than or
131         * equal to the key argument.  The key argument need not exist for this
132         * call to return true.  The underlying database must sort keys based on a
133         * key comparator because this method depends on key ordering.
134         *
135         * @param key the key to compare keys to
136         * @return true if a Tuple with a key less than or equal to the key
137         * argument exists, false otherwise
138         * @throws Exception if there is a failure to read the underlying Db
139         */
140        boolean hasLessOrEqual( K key ) throws Exception;
141    
142    
143        /**
144         * Checks to see if this table has a Tuple with a key equal to the key
145         * argument, yet with a value greater than or equal to the value argument
146         * provided.  The key argument <strong>MUST</strong> exist for this call
147         * to return true and the underlying Db must allow for values of duplicate
148         * keys to be sorted.  The entire basis to this method depends on the fact
149         * that tuples of the same key have values sorted according to a valid
150         * value comparator.
151         *
152         * If the table does not support duplicates then an
153         * UnsupportedOperationException is thrown.
154         *
155         * @param key the key
156         * @param val the value to compare values to
157         * @return true if a Tuple with a key equal to the key argument and a
158         * value greater than the value argument exists, false otherwise
159         * @throws Exception if there is a failure to read the underlying Db
160         * or if the underlying Db is not of the Btree type that allows sorted
161         * duplicate values.
162         */
163        boolean hasGreaterOrEqual( K key, V val ) throws Exception;
164    
165    
166        /**
167         * Checks to see if this table has a Tuple with a key equal to the key
168         * argument, yet with a value less than or equal to the value argument
169         * provided.  The key argument <strong>MUST</strong> exist for this call
170         * to return true and the underlying Db must allow for values of duplicate
171         * keys to be sorted.  The entire basis to this method depends on the fact
172         * that tuples of the same key have values sorted according to a valid
173         * value comparator.
174         *
175         * If the table does not support duplicates then an
176         * UnsupportedOperationException is thrown.
177         *
178         * @param key the key
179         * @param val the value to compare values to
180         * @return true if a Tuple with a key equal to the key argument and a
181         * value less than the value argument exists, false otherwise
182         * @throws Exception if there is a failure to read the underlying Db
183         * or if the underlying Db is not of the Btree type that allows sorted
184         * duplicate values.
185         */
186        boolean hasLessOrEqual( K key, V val ) throws Exception;
187    
188    
189        // ------------------------------------------------------------------------
190        // Table Value Accessors/Mutators
191        // ------------------------------------------------------------------------
192    
193        /**
194         * Gets the value of a record by key if the key exists.  If this Table
195         * allows duplicate keys then the first key will be returned.  If this
196         * Table sorts keys then the key will be the smallest key in the Table as
197         * specificed by this Table's comparator or the default bytewise lexical
198         * comparator.
199         *
200         * @param key the key of the record
201         * @return the value of the record with the specified key if key exists or
202         * null if no such key exists.
203         * @throws Exception if there is a failure to read the underlying Db
204         */
205        V get( K key ) throws Exception;
206    
207    
208        /**
209         * Puts a record into this Table.  Null is not allowed for keys or values
210         * and should result in an IllegalArgumentException.
211         *
212         * @param key the key of the record
213         * @param value the value of the record.
214         * @throws Exception if there is a failure to read or write to the
215         * underlying Db
216         * @throws IllegalArgumentException if a null key or value is used
217         */
218        void put( K key, V value ) throws Exception;
219    
220    
221        /**
222         * Removes all records with a specified key from this Table.
223         *
224         * @param key the key of the records to remove
225         * @throws Exception if there is a failure to read or write to
226         * the underlying Db
227         */
228        void remove( K key ) throws Exception;
229    
230    
231        /**
232         * Removes a single key value pair with a specified key and value from
233         * this Table.
234         *
235         * @param key the key of the record to remove
236         * @param value the value of the record to remove
237         * @throws Exception if there is a failure to read or write to
238         * the underlying Db
239         */
240        void remove( K key, V value ) throws Exception;
241    
242    
243        /**
244         * Creates a Cursor that traverses Tuples in a Table.
245         *
246         * @return a Cursor over Tuples containing the key value pairs
247         * @throws Exception if there are failures accessing underlying stores
248         */
249        Cursor<Tuple<K, V>> cursor() throws Exception;
250    
251    
252        /**
253         * Creates a Cursor that traverses Table Tuples for the same key. Only
254         * Tuples with the provided key will be returned if the key exists at
255         * all.  If the key does not exist an empty Cursor is returned.  The
256         * motivation behind this method is to minimize the need for callers to
257         * actively constrain Cursor operations based on the Tuples they return
258         * to a specific key.  This Cursor is naturally limited to return only
259         * the tuples for the same key.
260         *
261         * @param key the duplicate key to return the Tuples of
262         * @return a Cursor over Tuples containing the same key
263         * @throws Exception if there are failures accessing underlying stores
264         */
265        Cursor<Tuple<K, V>> cursor( K key ) throws Exception;
266    
267    
268        /**
269         * Creates a Cursor that traverses Table values for the same key. Only
270         * Tuples with the provided key will have their values returned if the key
271         * exists at all.  If the key does not exist an empty Cursor is returned.
272         * The motivation behind this method is to minimize the need for callers
273         * to actively constrain Cursor operations to a specific key while
274         * removing overheads in creating new Tuples or population one that is
275         * reused to return key value pairs.  This Cursor is naturally limited to
276         * return only the values for the same key.
277         *
278         * @param key the duplicate key to return the values of
279         * @return a Cursor over values of a key
280         * @throws Exception if there are failures accessing underlying stores
281         */
282        Cursor<V> valueCursor( K key ) throws Exception;
283    
284    
285        // ------------------------------------------------------------------------
286        // Table Record Count Methods
287        // ------------------------------------------------------------------------
288    
289        /**
290         * Gets the count of the number of records in this Table.
291         *
292         * @return the number of records
293         * @throws Exception if there is a failure to read the underlying Db
294         */
295        int count() throws Exception;
296    
297    
298        /**
299         * Gets the count of the number of records in this Table with a specific
300         * key: returns the number of duplicates for a key.
301         *
302         * @param key the Object key to count.
303         * @return the number of duplicate records for a key.
304         * @throws Exception if there is a failure to read the underlying Db
305         */
306        int count( K key ) throws Exception;
307    
308    
309        /**
310         * Gets the number of records greater than or equal to a key value.  The 
311         * specific key argument provided need not exist for this call to return 
312         * a non-zero value.
313         *
314         * @param key the key to use in comparisons
315         * @return the number of keys greater than or equal to the key
316         * @throws Exception if there is a failure to read the underlying db
317         */
318        int greaterThanCount( K key ) throws Exception;
319    
320    
321        /**
322         * Gets the number of records less than or equal to a key value.  The 
323         * specific key argument provided need not exist for this call to return 
324         * a non-zero value.
325         *
326         * @param key the key to use in comparisons
327         * @return the number of keys less than or equal to the key
328         * @throws Exception if there is a failure to read the underlying db
329         */
330        int lessThanCount( K key ) throws Exception;
331    
332    
333        /**
334         * Closes the underlying Db of this Table.
335         *
336         * @throws Exception on any failures
337         */
338        void close() throws Exception;
339    }