1/*- 2 * See the file LICENSE for redistribution information. 3 * 4 * Copyright (c) 2009 Oracle. All rights reserved. 5 * 6 */ 7using System; 8using System.Collections.Generic; 9using System.Text; 10 11namespace BerkeleyDB { 12 /// <summary> 13 /// A class representing configuration parameters for <see cref="Database"/> 14 /// </summary> 15 public class DatabaseConfig { 16 /// <summary> 17 /// The Berkeley DB environment within which to create a database. If 18 /// null, the database will be created stand-alone; that is, it is not 19 /// part of any Berkeley DB environment. 20 /// </summary> 21 /// <remarks> 22 /// The database access methods automatically make calls to the other 23 /// subsystems in Berkeley DB, based on the enclosing environment. For 24 /// example, if the environment has been configured to use locking, the 25 /// access methods will automatically acquire the correct locks when 26 /// reading and writing pages of the database. 27 /// </remarks> 28 public DatabaseEnvironment Env; 29 30 /// <summary> 31 /// The cache priority for pages referenced by the database. 32 /// </summary> 33 /// <remarks> 34 /// The priority of a page biases the replacement algorithm to be more 35 /// or less likely to discard a page when space is needed in the buffer 36 /// pool. The bias is temporary, and pages will eventually be discarded 37 /// if they are not referenced again. This priority is only advisory, 38 /// and does not guarantee pages will be treated in a specific way. 39 /// </remarks> 40 public CachePriority Priority; 41 42 /// <summary> 43 /// The size of the shared memory buffer pool -- that is, the cache. 44 /// </summary> 45 /// <remarks> 46 /// <para> 47 /// The cache should be the size of the normal working data set of the 48 /// application, with some small amount of additional memory for unusual 49 /// situations. (Note: the working set is not the same as the number of 50 /// pages accessed simultaneously, and is usually much larger.) 51 /// </para> 52 /// <para> 53 /// The default cache size is 256KB, and may not be specified as less 54 /// than 20KB. Any cache size less than 500MB is automatically increased 55 /// by 25% to account for buffer pool overhead; cache sizes larger than 56 /// 500MB are used as specified. The maximum size of a single cache is 57 /// 4GB on 32-bit systems and 10TB on 64-bit systems. (All sizes are in 58 /// powers-of-two, that is, 256KB is 2^18 not 256,000.) For information 59 /// on tuning the Berkeley DB cache size, see Selecting a cache size in 60 /// the Programmer's Reference Guide. 61 /// </para> 62 /// </remarks> 63 public CacheInfo CacheSize; 64 65 /// <summary> 66 /// The byte order for integers in the stored database metadata. The 67 /// host byte order of the machine where the Berkeley DB library was 68 /// compiled is the default value. 69 /// </summary> 70 /// <remarks> 71 /// <para> 72 /// The access methods provide no guarantees about the byte ordering of 73 /// the application data stored in the database, and applications are 74 /// responsible for maintaining any necessary ordering. 75 /// </para> 76 /// <para> 77 /// If creating additional databases in a single physical file, this 78 /// parameter will be ignored and the byte order of the existing 79 /// databases will be used. 80 /// </para> 81 /// </remarks> 82 public ByteOrder ByteOrder = ByteOrder.MACHINE; 83 84 internal bool pagesizeIsSet; 85 private uint pgsz; 86 /// <summary> 87 /// The size of the pages used to hold items in the database, in bytes. 88 /// </summary> 89 /// <remarks> 90 /// <para> 91 /// The minimum page size is 512 bytes, the maximum page size is 64K 92 /// bytes, and the page size must be a power-of-two. If the page size is 93 /// not explicitly set, one is selected based on the underlying 94 /// filesystem I/O block size. The automatically selected size has a 95 /// lower limit of 512 bytes and an upper limit of 16K bytes. 96 /// </para> 97 /// <para> 98 /// For information on tuning the Berkeley DB page size, see Selecting a 99 /// page size in the Programmer's Reference Guide. 100 /// </para> 101 /// <para> 102 /// If creating additional databases in a single physical file, this 103 /// parameter will be ignored and the page size of the existing 104 /// databases will be used. 105 /// </para> 106 /// </remarks> 107 public uint PageSize { 108 get { return pgsz; } 109 set { 110 pagesizeIsSet = true; 111 pgsz = value; 112 } 113 } 114 115 internal bool encryptionIsSet; 116 private String encryptPwd; 117 private EncryptionAlgorithm encryptAlg; 118 /// <summary> 119 /// Set the password and algorithm used by the Berkeley DB library to 120 /// perform encryption and decryption. 121 /// </summary> 122 /// <param name="password"> 123 /// The password used to perform encryption and decryption. 124 /// </param> 125 /// <param name="alg"> 126 /// The algorithm used to perform encryption and decryption. 127 /// </param> 128 public void SetEncryption(String password, EncryptionAlgorithm alg) { 129 encryptionIsSet = true; 130 encryptPwd = password; 131 encryptAlg = alg; 132 } 133 /// <summary> 134 /// The password used to perform encryption and decryption. 135 /// </summary> 136 public string EncryptionPassword { get { return encryptPwd; } } 137 /// <summary> 138 /// The algorithm used to perform encryption and decryption. 139 /// </summary> 140 public EncryptionAlgorithm EncryptAlgorithm { 141 get { return encryptAlg; } 142 } 143 144 /// <summary> 145 /// The prefix string that appears before error messages issued by 146 /// Berkeley DB. 147 /// </summary> 148 public String ErrorPrefix; 149 /// <summary> 150 /// The mechanism for reporting error messages to the application. 151 /// </summary> 152 /// <remarks> 153 /// <para> 154 /// In some cases, when an error occurs, Berkeley DB will call 155 /// ErrorFeedback with additional error information. It is up to the 156 /// delegate function to display the error message in an appropriate 157 /// manner. 158 /// </para> 159 /// <para> 160 /// This error-logging enhancement does not slow performance or 161 /// significantly increase application size, and may be run during 162 /// normal operation as well as during application debugging. 163 /// </para> 164 /// <para> 165 /// For databases opened inside of Berkeley DB environments, setting 166 /// ErrorFeedback affects the entire environment and is equivalent to 167 /// setting <see cref="DatabaseEnvironment.ErrorFeedback"/>. 168 /// </para> 169 /// </remarks> 170 public ErrorFeedbackDelegate ErrorFeedback; 171 172 /// <summary> 173 /// 174 /// </summary> 175 public DatabaseFeedbackDelegate Feedback; 176 177 /// <summary> 178 /// If true, do checksum verification of pages read into the cache from 179 /// the backing filestore. 180 /// </summary> 181 /// <remarks> 182 /// <para> 183 /// Berkeley DB uses the SHA1 Secure Hash Algorithm if encryption is 184 /// configured and a general hash algorithm if it is not. 185 /// </para> 186 /// <para> 187 /// If the database already exists, this setting will be ignored. 188 /// </para> 189 /// </remarks> 190 public bool DoChecksum; 191 192 /// <summary> 193 /// If true, Berkeley DB will not write log records for this database. 194 /// </summary> 195 /// <remarks> 196 /// If Berkeley DB does not write log records, updates of this database 197 /// will exhibit the ACI (atomicity, consistency, and isolation) 198 /// properties, but not D (durability); that is, database integrity will 199 /// be maintained, but if the application or system fails, integrity 200 /// will not persist. The database file must be verified and/or restored 201 /// from backup after a failure. In order to ensure integrity after 202 /// application shut down, the database must be synced when closed, or 203 /// all database changes must be flushed from the database environment 204 /// cache using either 205 /// <see cref="DatabaseEnvironment.Checkpoint"/> or 206 /// <see cref="DatabaseEnvironment.SyncMemPool"/>. All database objects 207 /// for a single physical file must set NonDurableTxns, including 208 /// database objects for different databases in a physical file. 209 /// </remarks> 210 public bool NonDurableTxns; 211 212 internal uint flags { 213 get { 214 uint ret = 0; 215 ret |= DoChecksum ? Internal.DbConstants.DB_CHKSUM : 0; 216 ret |= encryptionIsSet ? Internal.DbConstants.DB_ENCRYPT : 0; 217 ret |= NonDurableTxns ? Internal.DbConstants.DB_TXN_NOT_DURABLE : 0; 218 return ret; 219 } 220 } 221 222 /// <summary> 223 /// Enclose the open call within a transaction. If the call succeeds, 224 /// the open operation will be recoverable and all subsequent database 225 /// modification operations based on this handle will be transactionally 226 /// protected. If the call fails, no database will have been created. 227 /// </summary> 228 public bool AutoCommit; 229 /// <summary> 230 /// Cause the database object to be free-threaded; that is, concurrently 231 /// usable by multiple threads in the address space. 232 /// </summary> 233 public bool FreeThreaded; 234 /// <summary> 235 /// Do not map this database into process memory. 236 /// </summary> 237 public bool NoMMap; 238 /// <summary> 239 /// Open the database for reading only. Any attempt to modify items in 240 /// the database will fail, regardless of the actual permissions of any 241 /// underlying files. 242 /// </summary> 243 public bool ReadOnly; 244 /// <summary> 245 /// Support transactional read operations with degree 1 isolation. 246 /// </summary> 247 /// <remarks> 248 /// Read operations on the database may request the return of modified 249 /// but not yet committed data. This flag must be specified on all 250 /// database objects used to perform dirty reads or database updates, 251 /// otherwise requests for dirty reads may not be honored and the read 252 /// may block. 253 /// </remarks> 254 public bool ReadUncommitted; 255 /// <summary> 256 /// Physically truncate the underlying file, discarding all previous databases it might have held. 257 /// </summary> 258 /// <remarks> 259 /// <para> 260 /// Underlying filesystem primitives are used to implement this flag. 261 /// For this reason, it is applicable only to the file and cannot be 262 /// used to discard databases within a file. 263 /// </para> 264 /// <para> 265 /// This setting cannot be lock or transaction-protected, and it is an 266 /// error to specify it in a locking or transaction-protected 267 /// environment. 268 /// </para> 269 /// </remarks> 270 public bool Truncate; 271 /// <summary> 272 /// Open the database with support for multiversion concurrency control. 273 /// </summary> 274 /// <remarks> 275 /// This will cause updates to the database to follow a copy-on-write 276 /// protocol, which is required to support snapshot isolation. This 277 /// settting requires that the database be transactionally protected 278 /// during its open and is not supported by the queue format. 279 /// </remarks> 280 public bool UseMVCC; 281 internal uint openFlags { 282 get { 283 uint ret = 0; 284 ret |= AutoCommit ? Internal.DbConstants.DB_AUTO_COMMIT : 0; 285 ret |= FreeThreaded ? Internal.DbConstants.DB_THREAD : 0; 286 ret |= NoMMap ? Internal.DbConstants.DB_NOMMAP : 0; 287 ret |= ReadOnly ? Internal.DbConstants.DB_RDONLY : 0; 288 ret |= ReadUncommitted ? Internal.DbConstants.DB_READ_UNCOMMITTED : 0; 289 ret |= Truncate ? Internal.DbConstants.DB_TRUNCATE : 0; 290 ret |= UseMVCC ? Internal.DbConstants.DB_MULTIVERSION : 0; 291 return ret; 292 } 293 } 294 295 /// <summary> 296 /// Instantiate a new DatabaseConfig object 297 /// </summary> 298 public DatabaseConfig() { 299 Env = null; 300 Priority = CachePriority.DEFAULT; 301 pagesizeIsSet = false; 302 encryptionIsSet = false; 303 ErrorPrefix = null; 304 Feedback = null; 305 DoChecksum = false; 306 NonDurableTxns = false; 307 AutoCommit = false; 308 FreeThreaded = false; 309 NoMMap = false; 310 ReadOnly = false; 311 ReadUncommitted = false; 312 Truncate = false; 313 UseMVCC = false; 314 } 315 } 316}