001 /* 002 * CDDL HEADER START 003 * 004 * The contents of this file are subject to the terms of the 005 * Common Development and Distribution License, Version 1.0 only 006 * (the "License"). You may not use this file except in compliance 007 * with the License. 008 * 009 * You can obtain a copy of the license at 010 * trunk/opends/resource/legal-notices/OpenDS.LICENSE 011 * or https://OpenDS.dev.java.net/OpenDS.LICENSE. 012 * See the License for the specific language governing permissions 013 * and limitations under the License. 014 * 015 * When distributing Covered Code, include this CDDL HEADER in each 016 * file and include the License file at 017 * trunk/opends/resource/legal-notices/OpenDS.LICENSE. If applicable, 018 * add the following below this CDDL HEADER, with the fields enclosed 019 * by brackets "[]" replaced with your own identifying information: 020 * Portions Copyright [yyyy] [name of copyright owner] 021 * 022 * CDDL HEADER END 023 * 024 * 025 * Copyright 2008 Sun Microsystems, Inc. 026 */ 027 package org.opends.server.admin.std.server; 028 029 030 031 import java.util.SortedSet; 032 import org.opends.server.admin.server.ConfigurationAddListener; 033 import org.opends.server.admin.server.ConfigurationChangeListener; 034 import org.opends.server.admin.server.ConfigurationDeleteListener; 035 import org.opends.server.admin.std.meta.BackendCfgDefn.WritabilityMode; 036 import org.opends.server.config.ConfigException; 037 038 039 040 /** 041 * A server-side interface for querying Local DB Backend settings. 042 * <p> 043 * The Local DB Backend uses the Berkeley DB Java Edition to store 044 * user-provided data in a local repository. 045 */ 046 public interface LocalDBBackendCfg extends BackendCfg { 047 048 /** 049 * Gets the configuration class associated with this Local DB Backend. 050 * 051 * @return Returns the configuration class associated with this Local DB Backend. 052 */ 053 Class<? extends LocalDBBackendCfg> configurationClass(); 054 055 056 057 /** 058 * Register to be notified when this Local DB Backend is changed. 059 * 060 * @param listener 061 * The Local DB Backend configuration change listener. 062 */ 063 void addLocalDBChangeListener(ConfigurationChangeListener<LocalDBBackendCfg> listener); 064 065 066 067 /** 068 * Deregister an existing Local DB Backend configuration change listener. 069 * 070 * @param listener 071 * The Local DB Backend configuration change listener. 072 */ 073 void removeLocalDBChangeListener(ConfigurationChangeListener<LocalDBBackendCfg> listener); 074 075 076 077 /** 078 * Gets the "compact-encoding" property. 079 * <p> 080 * Indicates whether the backend should use a compact form when 081 * encoding entries by compressing the attribute descriptions and 082 * object class sets. 083 * <p> 084 * Note that this property applies only to the entries themselves 085 * and does not impact the index data. 086 * 087 * @return Returns the value of the "compact-encoding" property. 088 */ 089 boolean isCompactEncoding(); 090 091 092 093 /** 094 * Gets the "db-cache-percent" property. 095 * <p> 096 * Specifies the percentage of JVM memory to allocate to the 097 * database cache. 098 * <p> 099 * Specifies the percentage of memory available to the JVM that 100 * should be used for caching database contents. Note that this is 101 * only used if the value of the db-cache-size property is set to "0 102 * MB". Otherwise, the value of that property is used instead to 103 * control the cache size configuration. 104 * 105 * @return Returns the value of the "db-cache-percent" property. 106 */ 107 int getDBCachePercent(); 108 109 110 111 /** 112 * Gets the "db-cache-size" property. 113 * <p> 114 * The amount of JVM memory to allocate to the database cache. 115 * <p> 116 * Specifies the amount of memory that should be used for caching 117 * database contents. A value of "0 MB" indicates that the 118 * db-cache-percent property should be used instead to specify the 119 * cache size. 120 * 121 * @return Returns the value of the "db-cache-size" property. 122 */ 123 long getDBCacheSize(); 124 125 126 127 /** 128 * Gets the "db-checkpointer-bytes-interval" property. 129 * <p> 130 * Specifies the maximum number of bytes that may be written to the 131 * database before it is forced to perform a checkpoint. 132 * <p> 133 * This can be used to bound the recovery time that may be required 134 * if the database environment is opened without having been properly 135 * closed. If this property is set to a non-zero value, the 136 * checkpointer wakeup interval is not used. To use time-based 137 * checkpointing, set this property to zero. 138 * 139 * @return Returns the value of the "db-checkpointer-bytes-interval" property. 140 */ 141 long getDBCheckpointerBytesInterval(); 142 143 144 145 /** 146 * Gets the "db-checkpointer-wakeup-interval" property. 147 * <p> 148 * Specifies the maximum length of time that may pass between 149 * checkpoints. 150 * <p> 151 * Note that this is only used if the value of the checkpointer 152 * bytes interval is zero. 153 * 154 * @return Returns the value of the "db-checkpointer-wakeup-interval" property. 155 */ 156 long getDBCheckpointerWakeupInterval(); 157 158 159 160 /** 161 * Gets the "db-cleaner-min-utilization" property. 162 * <p> 163 * Specifies the minimum percentage of "live" data that the database 164 * cleaner attempts to keep in database log files. 165 * <p> 166 * If the amount of live data in any database log file drops below 167 * this percentage, then the cleaner moves the remaining live data in 168 * that file to the end of the database and deletes the original file 169 * in order to keep the database relatively compact. 170 * 171 * @return Returns the value of the "db-cleaner-min-utilization" property. 172 */ 173 int getDBCleanerMinUtilization(); 174 175 176 177 /** 178 * Gets the "db-directory" property. 179 * <p> 180 * Specifies the path to the filesystem directory that is used to 181 * hold the Berkeley DB Java Edition database files containing the 182 * data for this backend. 183 * <p> 184 * The path may be either an absolute path or a path relative to the 185 * directory containing the base of the OpenDS Directory Server 186 * installation. The path may be any valid directory path in which 187 * the server has appropriate permissions to read and write files and 188 * has sufficient space to hold the database contents. 189 * 190 * @return Returns the value of the "db-directory" property. 191 */ 192 String getDBDirectory(); 193 194 195 196 /** 197 * Gets the "db-directory-permissions" property. 198 * <p> 199 * Specifies the permissions that should be applied to the directory 200 * containing the server database files. 201 * <p> 202 * They should be expressed as three-digit octal values, which is 203 * the traditional representation for UNIX file permissions. The 204 * three digits represent the permissions that are available for the 205 * directory's owner, group members, and other users (in that order), 206 * and each digit is the octal representation of the read, write, and 207 * execute bits. Note that this only impacts permissions on the 208 * database directory and not on the files written into that 209 * directory. On UNIX systems, the user's umask controls permissions 210 * given to the database files. 211 * 212 * @return Returns the value of the "db-directory-permissions" property. 213 */ 214 String getDBDirectoryPermissions(); 215 216 217 218 /** 219 * Gets the "db-evictor-lru-only" property. 220 * <p> 221 * Indicates whether the database should evict existing data from 222 * the cache based on an LRU policy (where the least recently used 223 * information will be evicted first). 224 * <p> 225 * If set to "false", then the eviction keeps internal nodes of the 226 * underlying Btree in the cache over leaf notes, even if the leaf 227 * nodes have been accessed more recently. This may be a better 228 * configuration for databases in which only a very small portion of 229 * the data is cached. 230 * 231 * @return Returns the value of the "db-evictor-lru-only" property. 232 */ 233 boolean isDBEvictorLruOnly(); 234 235 236 237 /** 238 * Gets the "db-evictor-nodes-per-scan" property. 239 * <p> 240 * Specifies the number of Btree nodes that should be evicted from 241 * the cache in a single pass if it is determined that it is 242 * necessary to free existing data in order to make room for new 243 * information. 244 * <p> 245 * Changes to this property do not take effect until the backend is 246 * restarted. It is recommended that you also change this property 247 * when you set db-evictor-lru-only to false. This setting controls 248 * the number of Btree nodes that are considered, or sampled, each 249 * time a node is evicted. A setting of 100 often produces good 250 * results, but this may vary from application to application. The 251 * larger the nodes per scan, the more accurate the algorithm. 252 * However, setting it too high is detrimental; the need to consider 253 * larger numbers of nodes for each eviction may delay the completion 254 * of a given database operation, which will impact the response time 255 * of the application thread. 256 * 257 * @return Returns the value of the "db-evictor-nodes-per-scan" property. 258 */ 259 int getDBEvictorNodesPerScan(); 260 261 262 263 /** 264 * Gets the "db-log-file-max" property. 265 * <p> 266 * Specifies the maximum size for a database log file. 267 * 268 * @return Returns the value of the "db-log-file-max" property. 269 */ 270 long getDBLogFileMax(); 271 272 273 274 /** 275 * Gets the "db-logging-file-handler-on" property. 276 * <p> 277 * Indicates whether the database should maintain a je.info file in 278 * the same directory as the database log directory. 279 * <p> 280 * This file contains information about the internal processing 281 * performed by the underlying database. 282 * 283 * @return Returns the value of the "db-logging-file-handler-on" property. 284 */ 285 boolean isDBLoggingFileHandlerOn(); 286 287 288 289 /** 290 * Gets the "db-logging-level" property. 291 * <p> 292 * Specifies the log level that should be used by the database when 293 * it is writing information into the je.info file. 294 * <p> 295 * The database trace logging level is (in increasing order of 296 * verbosity) chosen from: OFF, SEVERE, WARNING, INFO, CONFIG, FINE, 297 * FINER, FINEST, ALL. 298 * 299 * @return Returns the value of the "db-logging-level" property. 300 */ 301 String getDBLoggingLevel(); 302 303 304 305 /** 306 * Gets the "db-num-cleaner-threads" property. 307 * <p> 308 * Specifies the number of threads that the backend should maintain 309 * to keep the database log files at or near the desired utilization. 310 * <p> 311 * In environments with high write throughput, multiple cleaner 312 * threads may be required to maintain the desired utilization. 313 * 314 * @return Returns the value of the "db-num-cleaner-threads" property. 315 */ 316 int getDBNumCleanerThreads(); 317 318 319 320 /** 321 * Gets the "db-num-lock-tables" property. 322 * <p> 323 * Specifies the number of lock tables that are used by the 324 * underlying database. 325 * <p> 326 * This can be particularly important to help improve scalability by 327 * avoiding contention on systems with large numbers of CPUs. The 328 * value of this configuration property should be set to a prime 329 * number that is less than or equal to the number of worker threads 330 * configured for use in the server. 331 * 332 * @return Returns the value of the "db-num-lock-tables" property. 333 */ 334 int getDBNumLockTables(); 335 336 337 338 /** 339 * Gets the "db-run-cleaner" property. 340 * <p> 341 * Indicates whether the database cleaner threads should be enabled. 342 * <p> 343 * The cleaner threads are used to periodically compact the database 344 * by identifying database files with a low (that is, less than the 345 * amount specified by the db-cleaner-min-utilization property) 346 * percentage of live data, moving the remaining live data to the end 347 * of the log and deleting that file. 348 * 349 * @return Returns the value of the "db-run-cleaner" property. 350 */ 351 boolean isDBRunCleaner(); 352 353 354 355 /** 356 * Gets the "db-txn-no-sync" property. 357 * <p> 358 * Indicates whether database writes should be primarily written to 359 * an internal buffer but not immediately written to disk. 360 * <p> 361 * Setting the value of this configuration attribute to "true" may 362 * improve write performance but could cause the most recent changes 363 * to be lost if the OpenDS Directory Server or the underlying JVM 364 * exits abnormally, or if an OS or hardware failure occurs (a 365 * behavior similar to running with transaction durability disabled 366 * in the Sun Java System Directory Server). 367 * 368 * @return Returns the value of the "db-txn-no-sync" property. 369 */ 370 boolean isDBTxnNoSync(); 371 372 373 374 /** 375 * Gets the "db-txn-write-no-sync" property. 376 * <p> 377 * Indicates whether the database should synchronously flush data as 378 * it is written to disk. 379 * <p> 380 * If this value is set to "false", then all data written to disk is 381 * synchronously flushed to persistent storage and thereby providing 382 * full durability. If it is set to "true", then data may be cached 383 * for a period of time by the underlying operating system before 384 * actually being written to disk. This may improve performance, but 385 * could cause the most recent changes to be lost in the event of an 386 * underlying OS or hardware failure (but not in the case that the 387 * OpenDS Directory Server or the JVM exits abnormally). 388 * 389 * @return Returns the value of the "db-txn-write-no-sync" property. 390 */ 391 boolean isDBTxnWriteNoSync(); 392 393 394 395 /** 396 * Gets the "deadlock-retry-limit" property. 397 * <p> 398 * Specifies the number of times that the server should retry an 399 * attempted operation in the backend if a deadlock results from two 400 * concurrent requests that interfere with each other in a 401 * conflicting manner. 402 * <p> 403 * A value of "0" indicates no limit. 404 * 405 * @return Returns the value of the "deadlock-retry-limit" property. 406 */ 407 int getDeadlockRetryLimit(); 408 409 410 411 /** 412 * Gets the "entries-compressed" property. 413 * <p> 414 * Indicates whether the backend should attempt to compress entries 415 * before storing them in the database. 416 * <p> 417 * Note that this property applies only to the entries themselves 418 * and does not impact the index data. Further, the effectiveness of 419 * the compression is based on the type of data contained in the 420 * entry. 421 * 422 * @return Returns the value of the "entries-compressed" property. 423 */ 424 boolean isEntriesCompressed(); 425 426 427 428 /** 429 * Gets the "import-queue-size" property. 430 * <p> 431 * Specifies the size (in number of entries) of the queue that is 432 * used to hold the entries read during an LDIF import. 433 * 434 * @return Returns the value of the "import-queue-size" property. 435 */ 436 int getImportQueueSize(); 437 438 439 440 /** 441 * Gets the "import-thread-count" property. 442 * <p> 443 * Specifies the number of threads that is used for concurrent 444 * processing during an LDIF import. 445 * <p> 446 * This should generally be a small multiple (for example, 2x) of 447 * the number of CPUs in the system for a traditional system, or 448 * equal to the number of CPU strands for a CMT system. 449 * 450 * @return Returns the value of the "import-thread-count" property. 451 */ 452 int getImportThreadCount(); 453 454 455 456 /** 457 * Gets the "index-entry-limit" property. 458 * <p> 459 * Specifies the maximum number of entries that is allowed to match 460 * a given index key before that particular index key is no longer 461 * maintained. 462 * <p> 463 * This property is analogous to the ALL IDs threshold in the Sun 464 * Java System Directory Server. Note that this is the default limit 465 * for the backend, and it may be overridden on a per-attribute 466 * basis.A value of 0 means there is no limit. 467 * 468 * @return Returns the value of the "index-entry-limit" property. 469 */ 470 int getIndexEntryLimit(); 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 OpenDS 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 505 506 /** 507 * Gets the "preload-time-limit" property. 508 * <p> 509 * Specifies the length of time that the backend is allowed to spend 510 * "pre-loading" data when it is initialized. 511 * <p> 512 * The pre-load process is used to pre-populate the database cache, 513 * so that it can be more quickly available when the server is 514 * processing requests. A duration of zero means there is no 515 * pre-load. 516 * 517 * @return Returns the value of the "preload-time-limit" property. 518 */ 519 long getPreloadTimeLimit(); 520 521 522 523 /** 524 * Gets the "subtree-delete-batch-size" property. 525 * <p> 526 * Specifies the maximum number of entries that may be deleted from 527 * the backend when using the subtree delete control within a single 528 * transaction. 529 * <p> 530 * If a subtree delete operation targets a subtree with more than 531 * this number of entries, then additional transactions are used to 532 * remove the remaining entries in that subtree. 533 * 534 * @return Returns the value of the "subtree-delete-batch-size" property. 535 */ 536 int getSubtreeDeleteBatchSize(); 537 538 539 540 /** 541 * Gets the "subtree-delete-size-limit" property. 542 * <p> 543 * Specifies the maximum number of entries that may be deleted from 544 * the backend when using the subtree delete control. 545 * <p> 546 * If a subtree delete operation targets a subtree with more than 547 * this number of entries, then multiple passes may be required to 548 * remove all entries in that subtree. 549 * 550 * @return Returns the value of the "subtree-delete-size-limit" property. 551 */ 552 int getSubtreeDeleteSizeLimit(); 553 554 555 556 /** 557 * Gets the "writability-mode" property. 558 * <p> 559 * Specifies the behavior that the backend should use when 560 * processing write operations. 561 * 562 * @return Returns the value of the "writability-mode" property. 563 */ 564 WritabilityMode getWritabilityMode(); 565 566 567 568 /** 569 * Lists the Local DB Indexes. 570 * 571 * @return Returns an array containing the names of the 572 * Local DB Indexes. 573 */ 574 String[] listLocalDBIndexes(); 575 576 577 578 /** 579 * Gets the named Local DB Index. 580 * 581 * @param name 582 * The name of the Local DB Index to retrieve. 583 * @return Returns the named Local DB Index. 584 * @throws ConfigException 585 * If the Local DB Index could not be found or it 586 * could not be successfully decoded. 587 */ 588 LocalDBIndexCfg getLocalDBIndex(String name) throws ConfigException; 589 590 591 592 /** 593 * Registers to be notified when new Local DB Indexes are added. 594 * 595 * @param listener 596 * The Local DB Index configuration add listener. 597 * @throws ConfigException 598 * If the add listener could not be registered. 599 */ 600 void addLocalDBIndexAddListener(ConfigurationAddListener<LocalDBIndexCfg> listener) throws ConfigException; 601 602 603 604 /** 605 * Deregisters an existing Local DB Index configuration add listener. 606 * 607 * @param listener 608 * The Local DB Index configuration add listener. 609 */ 610 void removeLocalDBIndexAddListener(ConfigurationAddListener<LocalDBIndexCfg> listener); 611 612 613 614 /** 615 * Registers to be notified when existing Local DB Indexes are deleted. 616 * 617 * @param listener 618 * The Local DB Index configuration delete listener. 619 * @throws ConfigException 620 * If the delete listener could not be registered. 621 */ 622 void addLocalDBIndexDeleteListener(ConfigurationDeleteListener<LocalDBIndexCfg> listener) throws ConfigException; 623 624 625 626 /** 627 * Deregisters an existing Local DB Index configuration delete listener. 628 * 629 * @param listener 630 * The Local DB Index configuration delete listener. 631 */ 632 void removeLocalDBIndexDeleteListener(ConfigurationDeleteListener<LocalDBIndexCfg> listener); 633 634 635 636 /** 637 * Lists the Local DB VLV Indexes. 638 * 639 * @return Returns an array containing the names of the 640 * Local DB VLV Indexes. 641 */ 642 String[] listLocalDBVLVIndexes(); 643 644 645 646 /** 647 * Gets the named Local DB VLV Index. 648 * 649 * @param name 650 * The name of the Local DB VLV Index to retrieve. 651 * @return Returns the named Local DB VLV Index. 652 * @throws ConfigException 653 * If the Local DB VLV Index could not be found or it 654 * could not be successfully decoded. 655 */ 656 LocalDBVLVIndexCfg getLocalDBVLVIndex(String name) throws ConfigException; 657 658 659 660 /** 661 * Registers to be notified when new Local DB VLV Indexes are added. 662 * 663 * @param listener 664 * The Local DB VLV Index configuration add listener. 665 * @throws ConfigException 666 * If the add listener could not be registered. 667 */ 668 void addLocalDBVLVIndexAddListener(ConfigurationAddListener<LocalDBVLVIndexCfg> listener) throws ConfigException; 669 670 671 672 /** 673 * Deregisters an existing Local DB VLV Index configuration add listener. 674 * 675 * @param listener 676 * The Local DB VLV Index configuration add listener. 677 */ 678 void removeLocalDBVLVIndexAddListener(ConfigurationAddListener<LocalDBVLVIndexCfg> listener); 679 680 681 682 /** 683 * Registers to be notified when existing Local DB VLV Indexes are deleted. 684 * 685 * @param listener 686 * The Local DB VLV Index configuration delete listener. 687 * @throws ConfigException 688 * If the delete listener could not be registered. 689 */ 690 void addLocalDBVLVIndexDeleteListener(ConfigurationDeleteListener<LocalDBVLVIndexCfg> listener) throws ConfigException; 691 692 693 694 /** 695 * Deregisters an existing Local DB VLV Index configuration delete listener. 696 * 697 * @param listener 698 * The Local DB VLV Index configuration delete listener. 699 */ 700 void removeLocalDBVLVIndexDeleteListener(ConfigurationDeleteListener<LocalDBVLVIndexCfg> listener); 701 702 }