1 /*! 2 @header BDBDatabase 3 @abstract Contains a class representing a database 4 5 @availability OS X, GNUstep 6 @copyright (C) 2004, 2005, 2006 Oliver Langer 7 8 Author: Oliver Langer 9 10 This library is free software; you can redistribute it and/or 11 modify it under the terms of the GNU Lesser General Public 12 License as published by the Free Software Foundation; either 13 version 2.1 of the License, or (at your option) any later version. 14 15 This library is distributed in the hope that it will be useful, 16 but WITHOUT ANY WARRANTY; without even the implied warranty of 17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 18 Lesser General Public License for more details. 19 20 You should have received a copy of the GNU Lesser General Public 21 License along with this library; if not, write to the Free Software 22 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA 23 24 <pre> 25 ------------------------------------------------------------------------- 26 Modification history 27 28 09.12.2005 ola initial version 29 22.08.2006 ola license changed 30 ------------------------------------------------------------------------- 31 </pre> 32 ******************************************************************************/ 33 34 35 #if !defined(__BDBDATABASE_H) 36 #define __BDBDATABASE_H 37 38 #include <db.h> 39 #include <Foundation/Foundation.h> 40 #include <BDB/BDBObject.h> 41 #include <BDB/BDBOperationStatus.h> 42 #include <BDB/BDBTransaction.h> 43 #include <BDB/BDBDatabaseConfig.h> 44 #include <BDB/BDBCursorConfig.h> 45 #include <BDB/BDBCursor.h> 46 #include <BDB/BDBDatabaseEntry.h> 47 #include <BDB/BDBDatabaseRecordNumber.h> 48 49 /*! 50 * @class BDBDatabase 51 * @abstract Wrapper for a DB instance 52 * @discussion Use instances of this class to load/store values 53 */ 54 @interface BDBDatabase : BDBObject { 55 @private 56 /** 57 * Underlying berkeley handle 58 */ 59 DB *db; 60 61 62 63 /** 64 * Database configuration 65 */ 66 BDBDatabaseConfig *dbConfig; 67 68 69 /** 70 * Name (not filename) of the database. May equal nil. 71 */ 72 NSString *databaseName; 73 } 74 75 + (void) initialize; 76 77 78 /*! 79 * @method initWithFilename 80 * @abstract open a database with the given file name, database name 81 * and configuration. 82 * @discussion Depending on the configuration the database may be 83 * created if not existent. Also, the configuration determines the kind of 84 * database to use. 85 * @param fileName name of database file 86 * @param databaseName name of database. Useful if multiple databases will 87 * be used within a single file. May equal nil. If nil is given 88 * during creation then subsequent calls with values different from nil 89 * will be ignored. 90 * @param aDbConfig configuration parameters 91 * 92 */ 93 + (BDBDatabase *) initWithFilename: (NSString *) fileName 94 databaseName: (NSString *) databaseName 95 databaseConfig: (BDBDatabaseConfig *) aDbConfig; 96 - init; 97 98 99 /** 100 * Used to close the database if opened at this stage 101 */ 102 - (void) dealloc; 103 104 105 /*! 106 * @method appendEntry 107 * @abstract appends the given entry to the end of the database 108 * @discussion This method is only defined for one of the modes 109 * {@link #BDB_RECNO}, {@link #BDB_QUEUE} 110 * @param transaction transaction to use 111 * @param entryToAppend value to add 112 * @param recordNr will contain the record number after appending the value. 113 * The underlying database entry instance has to be instantiated by the 114 * caller. If nil is passed then no record number will be returned this way. 115 * @result status of the operation 116 * @throws ECIllegalArgumentException if the given database entry contains no 117 * data. 118 * @throws ECIllegalOperationException if the database type is wrong or if 119 * an attempt was made to modify a read-only database. 120 * @throws DB_REP_HANDLE_DEAD invalid database handle due to a replication 121 * which unrolled a committed transaction. 122 * @throws DB_LOCK_DEADLOCK 123 * @throws DB_LOCK_NOTGRANTED 124 * @throws EINVAL The operation failed because of an invalid length of 125 * an record (in fixed record mode); OR attempt was made to append data to a 126 * secondary index. 127 * @throws BDBBtreeMaximumDepthReachedException 128 */ 129 - (BDBOperationStatus) appendEntryWithTransaction: 130 (BDBTransaction *) transaction 131 entryToAppend: (BDBDatabaseEntryData *) entryToAppend 132 resultingRecordNr: (BDBDatabaseRecordNumber *) recordNr; 133 134 135 /*! 136 * Closes the database. After this call all settings related to the database 137 * are being invalidated. The previously hand-off configuration may be reused. 138 */ 139 - close; 140 141 142 /*! 143 * @method deleteEntryWithTransaction 144 * @discussion In case of duplicate entries specified by the key 145 * <b>all</b> entries will be removed. 146 * @param transaction 147 * @param key key specifying the entry to be deleted 148 * @result status which may equal BDB_STATUS_NOTFOUND, BDB_STATUS_KEYEMPTY 149 * or BDB_STATUS_SUCCESS 150 * @throws BDBDeadLockExcepion 151 * @throws BDBException 152 */ 153 - (BDBOperationStatus) deleteEntryWithTransaction:( BDBTransaction *) transaction 154 key: (BDBDatabaseEntryData *) key; 155 156 157 /*! 158 * @param transaction underlying transaction. May equal nil 159 * @param key key to look for 160 * @param data entry to fill with the found data entry 161 * @return status of the operation 162 * @see BDBOperationStatus 163 * @throws BDBDeadLockException 164 * @throws BDBLockNotGrantedException 165 * @throws BDBIllegalIndexReference 166 * @throws BDBNoValueForKeyException 167 */ 168 - (BDBOperationStatus) getEntryWithTransaction: (BDBTransaction *) transaction 169 key: (BDBDatabaseEntryData *) key data: (BDBDatabaseEntryData *) data; 170 171 172 /*! 173 * @method getEntryWithTransaction 174 * @abstract retriev a value by its record number 175 * @param transaction underlying transaction. May equal nil 176 * @param key key to look for 177 * @param data entry to fill with the found data entry 178 * @return status of the operation 179 * @throws BDBDeadLockException 180 * @throws BDBLockNotGrantedException 181 * @throws BDBIllegalIndexReference 182 * @throws BDBNoValueForKeyException 183 */ 184 185 - (BDBOperationStatus) getEntryWithTransaction: (BDBTransaction *) transaction 186 recordNumber: (BDBDatabaseRecordNumber *) recNo 187 data: (BDBDatabaseEntryData *) data; 188 189 190 /*! 191 * @method openCursor 192 * @abstract open and return a cursor used. 193 * @param transaction underlying transaction. May be nil 194 * @param config settings for the cursor to be created 195 * ®result related cursor 196 * @throws BDBException 197 * @throws ECIllegalArgumentException 198 */ 199 - (BDBCursor *) openCursor: (BDBTransaction *) transaction 200 cursorConfig: (BDBCursorConfig *) config; 201 202 203 /*! 204 * @method putEntryWithTransaction 205 * @abstract Stores an entry in the database. 206 * @param key value for the key to be used. The handling of duplicates depends 207 * on the the configuration previously being set. 208 * @param value 209 * @result status of operation 210 * @throws BDBDeadLockException 211 * @throws BDBLockNotGrantedException 212 * @throws BDBException 213 */ 214 - (BDBOperationStatus) putEntryWithTransaction: (BDBTransaction *) transaction 215 key: (BDBDatabaseEntryData *) key value: (BDBDatabaseEntryData *) value; 216 217 218 /*! 219 * Stores an entry in the database 220 * @param key may not be null. The handling of duplicates depends 221 * on the the configuration previously being set. 222 * @param value may not be null. 223 * @throws BDBDeadLockException 224 * @throws BDBLockNotGrantedException 225 * @throws BDBException 226 */ 227 - (BDBOperationStatus) putDataWithTransaction: (BDBTransaction *) transaction 228 key: (NSData *) key value: (NSData *) value; 229 230 @end 231 232 #endif 233 234