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}