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.mavibot.btree;
21  
22  
23  import java.io.IOException;
24  import java.util.Comparator;
25  
26  import org.apache.directory.mavibot.btree.exception.KeyNotFoundException;
27  import org.apache.directory.mavibot.btree.serializer.ElementSerializer;
28  
29  
30  /**
31   * A BTree interface, to be implemented by the PersistedBTree or the InMemoryBTree
32   *
33   * @param <K> The Key type
34   * @param <V> The Value type
35   *
36   * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
37   */
38  public interface BTree<K, V>
39  {
40      /** Default page size (number of entries per node) */
41      static final int DEFAULT_PAGE_SIZE = 16;
42  
43      /** Default size of the buffer used to write data on disk. Around 1Mb */
44      static final int DEFAULT_WRITE_BUFFER_SIZE = 4096 * 250;
45  
46      /** Define a default delay for a read transaction. This is 10 seconds */
47      static final long DEFAULT_READ_TIMEOUT = 10 * 1000L;
48  
49      /** The BTree allows duplicate values */
50      static final boolean ALLOW_DUPLICATES = true;
51  
52      /** The BTree forbids duplicate values */
53      static final boolean FORBID_DUPLICATES = false;
54  
55  
56      /**
57       * Initialize the BTree.
58       *
59       * @throws IOException If we get some exception while initializing the BTree
60       */
61      void init() throws IOException;
62  
63  
64      /**
65       * Close the BTree, cleaning up all the data structure
66       */
67      void close() throws IOException;
68  
69  
70      /**
71       * Set the maximum number of elements we can store in a page. This must be a
72       * number greater than 1, and a power of 2. The default page size is 16.
73       * <br/>
74       * If the provided size is below 2, we will default to DEFAULT_PAGE_SIZE.<br/>
75       * If the provided size is not a power of 2, we will select the closest power of 2
76       * higher than the given number<br/>
77       *
78       * @param pageSize The requested page size
79       */
80      void setPageSize( int pageSize );
81  
82  
83      /**
84       * @return the pageSize
85       */
86      int getPageSize();
87  
88  
89      /**
90       * Insert an entry in the BTree.
91       * <p>
92       * We will replace the value if the provided key already exists in the
93       * btree.
94       *
95       * @param key Inserted key
96       * @param value Inserted value
97       * @return Existing value, if any.
98       * @throws IOException TODO
99       */
100     V insert( K key, V value ) throws IOException;
101 
102 
103     /**
104      * Delete the entry which key is given as a parameter. If the entry exists, it will
105      * be removed from the tree, the old tuple will be returned. Otherwise, null is returned.
106      *
107      * @param key The key for the entry we try to remove
108      * @return A Tuple<K, V> containing the removed entry, or null if it's not found.
109      */
110     Tuple<K, V> delete( K key ) throws IOException;
111 
112 
113     /**
114      * Delete the value from an entry associated with the given key. If the value
115      * If the value is present, it will be deleted first, later if there are no other
116      * values associated with this key(which can happen when duplicates are enabled),
117      * we will remove the key from the tree.
118      *
119      * @param key The key for the entry we try to remove
120      * @param value The value to delete (can be null)
121      * @return A Tuple<K, V> containing the removed entry, or null if it's not found.
122      */
123     Tuple<K, V> delete( K key, V value ) throws IOException;
124 
125 
126     /**
127      * Find a value in the tree, given its key. If the key is not found,
128      * it will throw a KeyNotFoundException. <br/>
129      * Note that we can get a null value stored, or many values.
130      *
131      * @param key The key we are looking at
132      * @return The found value, or null if the key is not present in the tree
133      * @throws KeyNotFoundException If the key is not found in the BTree
134      * @throws IOException TODO
135      */
136     V get( K key ) throws IOException, KeyNotFoundException;
137 
138 
139     /**
140      * Get the rootPage associated to a given revision.
141      *
142      * @param revision The revision we are looking for
143      * @return The rootPage associated to this revision
144      * @throws IOException If we had an issue while accessing the underlying file
145      * @throws KeyNotFoundException If the revision does not exist for this Btree
146      */
147     Page<K, V> getRootPage( long revision ) throws IOException, KeyNotFoundException;
148 
149 
150     /**
151      * Get the current rootPage
152      *
153      * @return The current rootPage
154      */
155     Page<K, V> getRootPage();
156 
157 
158     /**
159      * @see Page#getValues(Object)
160      */
161     ValueCursor<V> getValues( K key ) throws IOException, KeyNotFoundException;
162 
163 
164     /**
165      * Find a value in the tree, given its key, at a specific revision. If the key is not found,
166      * it will throw a KeyNotFoundException. <br/>
167      * Note that we can get a null value stored, or many values.
168      *
169      * @param revision The revision for which we want to find a key
170      * @param key The key we are looking at
171      * @return The found value, or null if the key is not present in the tree
172      * @throws KeyNotFoundException If the key is not found in the BTree
173      * @throws IOException If there was an issue while fetching data from the disk
174      */
175     V get( long revision, K key ) throws IOException, KeyNotFoundException;
176 
177 
178     /**
179      * Checks if the given key exists.
180      *
181      * @param key The key we are looking at
182      * @return true if the key is present, false otherwise
183      * @throws IOException If we have an error while trying to access the page
184      */
185     boolean hasKey( K key ) throws IOException;
186 
187 
188     /**
189      * Checks if the given key exists for a given revision.
190      *
191      * @param revision The revision for which we want to find a key
192      * @param key The key we are looking at
193      * @return true if the key is present, false otherwise
194      * @throws IOException If we have an error while trying to access the page
195      * @throws KeyNotFoundException If the key is not found in the BTree
196      */
197     boolean hasKey( long revision, K key ) throws IOException, KeyNotFoundException;
198 
199 
200     /**
201      * Checks if the BTree contains the given key with the given value.
202      *
203      * @param key The key we are looking for
204      * @param value The value associated with the given key
205      * @return true if the key and value are associated with each other, false otherwise
206      */
207     boolean contains( K key, V value ) throws IOException;
208 
209 
210     /**
211      * Checks if the BTree contains the given key with the given value for a given revision
212      *
213      * @param revision The revision we would like to browse
214      * @param key The key we are looking for
215      * @param value The value associated with the given key
216      * @return true if the key and value are associated with each other, false otherwise
217      * @throws KeyNotFoundException If the key is not found in the BTree
218      */
219     boolean contains( long revision, K key, V value ) throws IOException, KeyNotFoundException;
220 
221 
222     /**
223      * Creates a cursor starting at the beginning of the tree
224      *
225      * @return A cursor on the btree
226      * @throws IOException
227      */
228     TupleCursor<K, V> browse() throws IOException;
229 
230 
231     /**
232      * Creates a cursor starting at the beginning of the tree, for a given revision
233      *
234      * @param revision The revision we would like to browse
235      * @return A cursor on the btree
236      * @throws IOException If we had an issue while fetching data from the disk
237      * @throws KeyNotFoundException If the key is not found in the BTree
238      */
239     TupleCursor<K, V> browse( long revision ) throws IOException, KeyNotFoundException;
240 
241 
242     /**
243      * Creates a cursor starting on the given key
244      *
245      * @param key The key which is the starting point. If the key is not found,
246      * then the cursor will always return null.
247      * @return A cursor on the btree
248      * @throws IOException
249      */
250     TupleCursor<K, V> browseFrom( K key ) throws IOException;
251 
252 
253     /**
254      * Creates a cursor starting on the given key at the given revision
255      *
256      * @param The revision we are looking for
257      * @param key The key which is the starting point. If the key is not found,
258      * then the cursor will always return null.
259      * @return A cursor on the btree
260      * @throws IOException If wxe had an issue reading the BTree from disk
261      * @throws KeyNotFoundException  If we can't find a rootPage for this revision
262      */
263     TupleCursor<K, V> browseFrom( long revision, K key ) throws IOException, KeyNotFoundException;
264 
265 
266     /**
267      * @return the comparator
268      */
269     Comparator<K> getComparator();
270 
271 
272     /**
273      * @param keySerializer the Key serializer to set
274      */
275     void setKeySerializer( ElementSerializer<K> keySerializer );
276 
277 
278     /**
279      * @param valueSerializer the Value serializer to set
280      */
281     void setValueSerializer( ElementSerializer<V> valueSerializer );
282 
283 
284     /**
285      * Flush the latest revision to disk. We will replace the current file by the new one, as
286      * we flush in a temporary file.
287      */
288     void flush() throws IOException;
289 
290 
291     /**
292      * @return the readTimeOut
293      */
294     long getReadTimeOut();
295 
296 
297     /**
298      * @param readTimeOut the readTimeOut to set
299      */
300     void setReadTimeOut( long readTimeOut );
301 
302 
303     /**
304      * @return the name
305      */
306     String getName();
307 
308 
309     /**
310      * @param name the name to set
311      */
312     void setName( String name );
313 
314 
315     /**
316      * @return the writeBufferSize
317      */
318     int getWriteBufferSize();
319 
320 
321     /**
322      * @param writeBufferSize the writeBufferSize to set
323      */
324     void setWriteBufferSize( int writeBufferSize );
325 
326 
327     /**
328      * @return the keySerializer
329      */
330     ElementSerializer<K> getKeySerializer();
331 
332 
333     /**
334      * @return the keySerializer FQCN
335      */
336     String getKeySerializerFQCN();
337 
338 
339     /**
340      * @return the valueSerializer
341      */
342     ElementSerializer<V> getValueSerializer();
343 
344 
345     /**
346      * @return the valueSerializer FQCN
347      */
348     String getValueSerializerFQCN();
349 
350 
351     /**
352      * @return The current BTree revision
353      */
354     long getRevision();
355 
356 
357     /**
358      * @return The current number of elements in the BTree
359      */
360     long getNbElems();
361 
362 
363     /**
364      * @return true if this BTree allow duplicate values
365      */
366     boolean isAllowDuplicates();
367 
368 
369     /**
370      * @param allowDuplicates True if the BTree will allow duplicate values
371      */
372     void setAllowDuplicates( boolean allowDuplicates );
373 
374 
375     /**
376      * @return the type
377      */
378     BTreeTypeEnum getType();
379 
380 
381     /**
382      * Starts a transaction
383      */
384     void beginTransaction();
385 
386 
387     /**
388      * Commits a transaction
389      */
390     void commit();
391 
392 
393     /**
394      * Rollback a transaction
395      */
396     void rollback();
397 }