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