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 }