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 }