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 }