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    }