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 }