001/* 002 * The contents of this file are subject to the terms of the Common Development and 003 * Distribution License (the License). You may not use this file except in compliance with the 004 * License. 005 * 006 * You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the 007 * specific language governing permission and limitations under the License. 008 * 009 * When distributing Covered Software, include this CDDL Header Notice in each file and include 010 * the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL 011 * Header, with the fields enclosed by brackets [] replaced by your own identifying 012 * information: "Portions Copyright [year] [name of copyright owner]". 013 * 014 * Copyright 2008 Sun Microsystems, Inc. 015 */ 016package org.forgerock.opendj.server.config.server; 017 018 019 020import java.util.SortedSet; 021import org.forgerock.opendj.config.server.ConfigurationChangeListener; 022 023 024 025/** 026 * A server-side interface for querying JE Backend settings. 027 * <p> 028 * A JE Backend stores application data in a Berkeley DB Java Edition 029 * database. 030 */ 031public interface JEBackendCfg extends PluggableBackendCfg { 032 033 /** 034 * Gets the configuration class associated with this JE Backend. 035 * 036 * @return Returns the configuration class associated with this JE Backend. 037 */ 038 Class<? extends JEBackendCfg> configurationClass(); 039 040 041 042 /** 043 * Register to be notified when this JE Backend is changed. 044 * 045 * @param listener 046 * The JE Backend configuration change listener. 047 */ 048 void addJEChangeListener(ConfigurationChangeListener<JEBackendCfg> listener); 049 050 051 052 /** 053 * Deregister an existing JE Backend configuration change listener. 054 * 055 * @param listener 056 * The JE Backend configuration change listener. 057 */ 058 void removeJEChangeListener(ConfigurationChangeListener<JEBackendCfg> listener); 059 060 061 062 /** 063 * Gets the "db-cache-percent" property. 064 * <p> 065 * Specifies the percentage of JVM memory to allocate to the 066 * database cache. 067 * <p> 068 * Specifies the percentage of memory available to the JVM that 069 * should be used for caching database contents. Note that this is 070 * only used if the value of the db-cache-size property is set to "0 071 * MB". Otherwise, the value of that property is used instead to 072 * control the cache size configuration. 073 * 074 * @return Returns the value of the "db-cache-percent" property. 075 */ 076 int getDBCachePercent(); 077 078 079 080 /** 081 * Gets the "db-cache-size" property. 082 * <p> 083 * The amount of JVM memory to allocate to the database cache. 084 * <p> 085 * Specifies the amount of memory that should be used for caching 086 * database contents. A value of "0 MB" indicates that the 087 * db-cache-percent property should be used instead to specify the 088 * cache size. 089 * 090 * @return Returns the value of the "db-cache-size" property. 091 */ 092 long getDBCacheSize(); 093 094 095 096 /** 097 * Gets the "db-checkpointer-bytes-interval" property. 098 * <p> 099 * Specifies the maximum number of bytes that may be written to the 100 * database before it is forced to perform a checkpoint. 101 * <p> 102 * This can be used to bound the recovery time that may be required 103 * if the database environment is opened without having been properly 104 * closed. If this property is set to a non-zero value, the 105 * checkpointer wakeup interval is not used. To use time-based 106 * checkpointing, set this property to zero. 107 * 108 * @return Returns the value of the "db-checkpointer-bytes-interval" property. 109 */ 110 long getDBCheckpointerBytesInterval(); 111 112 113 114 /** 115 * Gets the "db-checkpointer-wakeup-interval" property. 116 * <p> 117 * Specifies the maximum length of time that may pass between 118 * checkpoints. 119 * <p> 120 * Note that this is only used if the value of the checkpointer 121 * bytes interval is zero. 122 * 123 * @return Returns the value of the "db-checkpointer-wakeup-interval" property. 124 */ 125 long getDBCheckpointerWakeupInterval(); 126 127 128 129 /** 130 * Gets the "db-cleaner-min-utilization" property. 131 * <p> 132 * Specifies the occupancy percentage for "live" data in this 133 * backend's database. 134 * <p> 135 * When the amount of "live" data in the database drops below this 136 * value, cleaners will act to increase the occupancy percentage by 137 * compacting the database. 138 * 139 * @return Returns the value of the "db-cleaner-min-utilization" property. 140 */ 141 int getDBCleanerMinUtilization(); 142 143 144 145 /** 146 * Gets the "db-directory" property. 147 * <p> 148 * Specifies the path to the filesystem directory that is used to 149 * hold the Berkeley DB Java Edition database files containing the 150 * data for this backend. 151 * <p> 152 * The path may be either an absolute path or a path relative to the 153 * directory containing the base of the OpenDJ directory server 154 * installation. The path may be any valid directory path in which 155 * the server has appropriate permissions to read and write files and 156 * has sufficient space to hold the database contents. 157 * 158 * @return Returns the value of the "db-directory" property. 159 */ 160 String getDBDirectory(); 161 162 163 164 /** 165 * Gets the "db-directory-permissions" property. 166 * <p> 167 * Specifies the permissions that should be applied to the directory 168 * containing the server database files. 169 * <p> 170 * They should be expressed as three-digit octal values, which is 171 * the traditional representation for UNIX file permissions. The 172 * three digits represent the permissions that are available for the 173 * directory's owner, group members, and other users (in that order), 174 * and each digit is the octal representation of the read, write, and 175 * execute bits. Note that this only impacts permissions on the 176 * database directory and not on the files written into that 177 * directory. On UNIX systems, the user's umask controls permissions 178 * given to the database files. 179 * 180 * @return Returns the value of the "db-directory-permissions" property. 181 */ 182 String getDBDirectoryPermissions(); 183 184 185 186 /** 187 * Gets the "db-evictor-core-threads" property. 188 * <p> 189 * Specifies the core number of threads in the eviction thread pool. 190 * <p> 191 * Specifies the core number of threads in the eviction thread pool. 192 * These threads help keep memory usage within cache bounds, 193 * offloading work from application threads. db-evictor-core-threads, 194 * db-evictor-max-threads and db-evictor-keep-alive are used to 195 * configure the core, max and keepalive attributes for the eviction 196 * thread pool. 197 * 198 * @return Returns the value of the "db-evictor-core-threads" property. 199 */ 200 int getDBEvictorCoreThreads(); 201 202 203 204 /** 205 * Gets the "db-evictor-keep-alive" property. 206 * <p> 207 * The duration that excess threads in the eviction thread pool will 208 * stay idle. After this period, idle threads will terminate. 209 * <p> 210 * The duration that excess threads in the eviction thread pool will 211 * stay idle. After this period, idle threads will terminate. 212 * db-evictor-core-threads, db-evictor-max-threads and 213 * db-evictor-keep-alive are used to configure the core, max and 214 * keepalive attributes for the eviction thread pool. 215 * 216 * @return Returns the value of the "db-evictor-keep-alive" property. 217 */ 218 long getDBEvictorKeepAlive(); 219 220 221 222 /** 223 * Gets the "db-evictor-lru-only" property. 224 * <p> 225 * Indicates whether the database should evict existing data from 226 * the cache based on an LRU policy (where the least recently used 227 * information will be evicted first). 228 * <p> 229 * If set to "false", then the eviction keeps internal nodes of the 230 * underlying Btree in the cache over leaf nodes, even if the leaf 231 * nodes have been accessed more recently. This may be a better 232 * configuration for databases in which only a very small portion of 233 * the data is cached. 234 * 235 * @return Returns the value of the "db-evictor-lru-only" property. 236 */ 237 boolean isDBEvictorLruOnly(); 238 239 240 241 /** 242 * Gets the "db-evictor-max-threads" property. 243 * <p> 244 * Specifies the maximum number of threads in the eviction thread 245 * pool. 246 * <p> 247 * Specifies the maximum number of threads in the eviction thread 248 * pool. These threads help keep memory usage within cache bounds, 249 * offloading work from application threads. db-evictor-core-threads, 250 * db-evictor-max-threads and db-evictor-keep-alive are used to 251 * configure the core, max and keepalive attributes for the eviction 252 * thread pool. 253 * 254 * @return Returns the value of the "db-evictor-max-threads" property. 255 */ 256 int getDBEvictorMaxThreads(); 257 258 259 260 /** 261 * Gets the "db-evictor-nodes-per-scan" property. 262 * <p> 263 * Specifies the number of Btree nodes that should be evicted from 264 * the cache in a single pass if it is determined that it is 265 * necessary to free existing data in order to make room for new 266 * information. 267 * <p> 268 * Changes to this property do not take effect until the backend is 269 * restarted. It is recommended that you also change this property 270 * when you set db-evictor-lru-only to false. This setting controls 271 * the number of Btree nodes that are considered, or sampled, each 272 * time a node is evicted. A setting of 10 often produces good 273 * results, but this may vary from application to application. The 274 * larger the nodes per scan, the more accurate the algorithm. 275 * However, don't set it too high. When considering larger numbers of 276 * nodes for each eviction, the evictor may delay the completion of a 277 * given database operation, which impacts the response time of the 278 * application thread. In JE 4.1 and later, setting this value too 279 * high in an application that is largely CPU bound can reduce the 280 * effectiveness of cache eviction. It's best to start with the 281 * default value, and increase it gradually to see if it is 282 * beneficial for your application. 283 * 284 * @return Returns the value of the "db-evictor-nodes-per-scan" property. 285 */ 286 int getDBEvictorNodesPerScan(); 287 288 289 290 /** 291 * Gets the "db-log-filecache-size" property. 292 * <p> 293 * Specifies the size of the file handle cache. 294 * <p> 295 * The file handle cache is used to keep as much opened log files as 296 * possible. When the cache is smaller than the number of logs, the 297 * database needs to close some handles and open log files it needs, 298 * resulting in less optimal performances. Ideally, the size of the 299 * cache should be higher than the number of files contained in the 300 * database. Make sure the OS number of open files per process is 301 * also tuned appropriately. 302 * 303 * @return Returns the value of the "db-log-filecache-size" property. 304 */ 305 int getDBLogFilecacheSize(); 306 307 308 309 /** 310 * Gets the "db-log-file-max" property. 311 * <p> 312 * Specifies the maximum size for a database log file. 313 * 314 * @return Returns the value of the "db-log-file-max" property. 315 */ 316 long getDBLogFileMax(); 317 318 319 320 /** 321 * Gets the "db-logging-file-handler-on" property. 322 * <p> 323 * Indicates whether the database should maintain a je.info file in 324 * the same directory as the database log directory. 325 * <p> 326 * This file contains information about the internal processing 327 * performed by the underlying database. 328 * 329 * @return Returns the value of the "db-logging-file-handler-on" property. 330 */ 331 boolean isDBLoggingFileHandlerOn(); 332 333 334 335 /** 336 * Gets the "db-logging-level" property. 337 * <p> 338 * Specifies the log level that should be used by the database when 339 * it is writing information into the je.info file. 340 * <p> 341 * The database trace logging level is (in increasing order of 342 * verbosity) chosen from: OFF, SEVERE, WARNING, INFO, CONFIG, FINE, 343 * FINER, FINEST, ALL. 344 * 345 * @return Returns the value of the "db-logging-level" property. 346 */ 347 String getDBLoggingLevel(); 348 349 350 351 /** 352 * Gets the "db-num-cleaner-threads" property. 353 * <p> 354 * Specifies the number of threads that the backend should maintain 355 * to keep the database log files at or near the desired utilization. 356 * <p> 357 * In environments with high write throughput, multiple cleaner 358 * threads may be required to maintain the desired utilization. 359 * 360 * @return Returns the value of the "db-num-cleaner-threads" property. 361 */ 362 Integer getDBNumCleanerThreads(); 363 364 365 366 /** 367 * Gets the "db-num-lock-tables" property. 368 * <p> 369 * Specifies the number of lock tables that are used by the 370 * underlying database. 371 * <p> 372 * This can be particularly important to help improve scalability by 373 * avoiding contention on systems with large numbers of CPUs. The 374 * value of this configuration property should be set to a prime 375 * number that is less than or equal to the number of worker threads 376 * configured for use in the server. 377 * 378 * @return Returns the value of the "db-num-lock-tables" property. 379 */ 380 Integer getDBNumLockTables(); 381 382 383 384 /** 385 * Gets the "db-run-cleaner" property. 386 * <p> 387 * Indicates whether the cleaner threads should be enabled to 388 * compact the database. 389 * <p> 390 * The cleaner threads are used to periodically compact the database 391 * when it reaches a percentage of occupancy lower than the amount 392 * specified by the db-cleaner-min-utilization property. They 393 * identify database files with a low percentage of live data, and 394 * relocate their remaining live data to the end of the log. 395 * 396 * @return Returns the value of the "db-run-cleaner" property. 397 */ 398 boolean isDBRunCleaner(); 399 400 401 402 /** 403 * Gets the "db-txn-no-sync" property. 404 * <p> 405 * Indicates whether database writes should be primarily written to 406 * an internal buffer but not immediately written to disk. 407 * <p> 408 * Setting the value of this configuration attribute to "true" may 409 * improve write performance but could cause the most recent changes 410 * to be lost if the OpenDJ directory server or the underlying JVM 411 * exits abnormally, or if an OS or hardware failure occurs (a 412 * behavior similar to running with transaction durability disabled 413 * in the Sun Java System Directory Server). 414 * 415 * @return Returns the value of the "db-txn-no-sync" property. 416 */ 417 boolean isDBTxnNoSync(); 418 419 420 421 /** 422 * Gets the "db-txn-write-no-sync" property. 423 * <p> 424 * Indicates whether the database should synchronously flush data as 425 * it is written to disk. 426 * <p> 427 * If this value is set to "false", then all data written to disk is 428 * synchronously flushed to persistent storage and thereby providing 429 * full durability. If it is set to "true", then data may be cached 430 * for a period of time by the underlying operating system before 431 * actually being written to disk. This may improve performance, but 432 * could cause the most recent changes to be lost in the event of an 433 * underlying OS or hardware failure (but not in the case that the 434 * OpenDJ directory server or the JVM exits abnormally). 435 * 436 * @return Returns the value of the "db-txn-write-no-sync" property. 437 */ 438 boolean isDBTxnWriteNoSync(); 439 440 441 442 /** 443 * Gets the "disk-full-threshold" property. 444 * <p> 445 * Full disk threshold to limit database updates 446 * <p> 447 * When the available free space on the disk used by this database 448 * instance falls below the value specified, no updates are permitted 449 * and the server returns an UNWILLING_TO_PERFORM error. Updates are 450 * allowed again as soon as free space rises above the threshold. 451 * 452 * @return Returns the value of the "disk-full-threshold" property. 453 */ 454 long getDiskFullThreshold(); 455 456 457 458 /** 459 * Gets the "disk-low-threshold" property. 460 * <p> 461 * Low disk threshold to limit database updates 462 * <p> 463 * Specifies the "low" free space on the disk. When the available 464 * free space on the disk used by this database instance falls below 465 * the value specified, protocol updates on this database are 466 * permitted only by a user with the BYPASS_LOCKDOWN privilege. 467 * 468 * @return Returns the value of the "disk-low-threshold" property. 469 */ 470 long getDiskLowThreshold(); 471 472 473 474 /** 475 * Gets the "java-class" property. 476 * <p> 477 * Specifies the fully-qualified name of the Java class that 478 * provides the backend implementation. 479 * 480 * @return Returns the value of the "java-class" property. 481 */ 482 String getJavaClass(); 483 484 485 486 /** 487 * Gets the "je-property" property. 488 * <p> 489 * Specifies the database and environment properties for the 490 * Berkeley DB Java Edition database serving the data for this 491 * backend. 492 * <p> 493 * Any Berkeley DB Java Edition property can be specified using the 494 * following form: property-name=property-value. Refer to OpenDJ 495 * documentation for further information on related properties, their 496 * implications, and range values. The definitive identification of 497 * all the property parameters is available in the example.properties 498 * file of Berkeley DB Java Edition distribution. 499 * 500 * @return Returns an unmodifiable set containing the values of the "je-property" property. 501 */ 502 SortedSet<String> getJEProperty(); 503 504}