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.client;
028
029
030
031 import java.util.Collection;
032 import java.util.SortedSet;
033 import org.opends.server.admin.client.AuthorizationException;
034 import org.opends.server.admin.client.CommunicationException;
035 import org.opends.server.admin.client.ConcurrentModificationException;
036 import org.opends.server.admin.client.IllegalManagedObjectNameException;
037 import org.opends.server.admin.client.ManagedObjectDecodingException;
038 import org.opends.server.admin.client.OperationRejectedException;
039 import org.opends.server.admin.DefaultBehaviorException;
040 import org.opends.server.admin.DefinitionDecodingException;
041 import org.opends.server.admin.IllegalPropertyValueException;
042 import org.opends.server.admin.ManagedObjectDefinition;
043 import org.opends.server.admin.ManagedObjectNotFoundException;
044 import org.opends.server.admin.std.meta.BackendCfgDefn.WritabilityMode;
045 import org.opends.server.admin.std.server.LocalDBBackendCfg;
046 import org.opends.server.admin.std.server.LocalDBIndexCfg;
047 import org.opends.server.admin.std.server.LocalDBVLVIndexCfg;
048
049
050
051 /**
052 * A client-side interface for reading and modifying Local DB Backend
053 * settings.
054 * <p>
055 * The Local DB Backend uses the Berkeley DB Java Edition to store
056 * user-provided data in a local repository.
057 */
058 public interface LocalDBBackendCfgClient extends BackendCfgClient {
059
060 /**
061 * Get the configuration definition associated with this Local DB Backend.
062 *
063 * @return Returns the configuration definition associated with this Local DB Backend.
064 */
065 ManagedObjectDefinition<? extends LocalDBBackendCfgClient, ? extends LocalDBBackendCfg> definition();
066
067
068
069 /**
070 * Gets the "compact-encoding" property.
071 * <p>
072 * Indicates whether the backend should use a compact form when
073 * encoding entries by compressing the attribute descriptions and
074 * object class sets.
075 * <p>
076 * Note that this property applies only to the entries themselves
077 * and does not impact the index data.
078 *
079 * @return Returns the value of the "compact-encoding" property.
080 */
081 boolean isCompactEncoding();
082
083
084
085 /**
086 * Sets the "compact-encoding" property.
087 * <p>
088 * Indicates whether the backend should use a compact form when
089 * encoding entries by compressing the attribute descriptions and
090 * object class sets.
091 * <p>
092 * Note that this property applies only to the entries themselves
093 * and does not impact the index data.
094 *
095 * @param value The value of the "compact-encoding" property.
096 * @throws IllegalPropertyValueException
097 * If the new value is invalid.
098 */
099 void setCompactEncoding(Boolean value) throws IllegalPropertyValueException;
100
101
102
103 /**
104 * Gets the "db-cache-percent" property.
105 * <p>
106 * Specifies the percentage of JVM memory to allocate to the
107 * database cache.
108 * <p>
109 * Specifies the percentage of memory available to the JVM that
110 * should be used for caching database contents. Note that this is
111 * only used if the value of the db-cache-size property is set to "0
112 * MB". Otherwise, the value of that property is used instead to
113 * control the cache size configuration.
114 *
115 * @return Returns the value of the "db-cache-percent" property.
116 */
117 int getDBCachePercent();
118
119
120
121 /**
122 * Sets the "db-cache-percent" property.
123 * <p>
124 * Specifies the percentage of JVM memory to allocate to the
125 * database cache.
126 * <p>
127 * Specifies the percentage of memory available to the JVM that
128 * should be used for caching database contents. Note that this is
129 * only used if the value of the db-cache-size property is set to "0
130 * MB". Otherwise, the value of that property is used instead to
131 * control the cache size configuration.
132 *
133 * @param value The value of the "db-cache-percent" property.
134 * @throws IllegalPropertyValueException
135 * If the new value is invalid.
136 */
137 void setDBCachePercent(Integer value) throws IllegalPropertyValueException;
138
139
140
141 /**
142 * Gets the "db-cache-size" property.
143 * <p>
144 * The amount of JVM memory to allocate to the database cache.
145 * <p>
146 * Specifies the amount of memory that should be used for caching
147 * database contents. A value of "0 MB" indicates that the
148 * db-cache-percent property should be used instead to specify the
149 * cache size.
150 *
151 * @return Returns the value of the "db-cache-size" property.
152 */
153 long getDBCacheSize();
154
155
156
157 /**
158 * Sets the "db-cache-size" property.
159 * <p>
160 * The amount of JVM memory to allocate to the database cache.
161 * <p>
162 * Specifies the amount of memory that should be used for caching
163 * database contents. A value of "0 MB" indicates that the
164 * db-cache-percent property should be used instead to specify the
165 * cache size.
166 *
167 * @param value The value of the "db-cache-size" property.
168 * @throws IllegalPropertyValueException
169 * If the new value is invalid.
170 */
171 void setDBCacheSize(Long value) throws IllegalPropertyValueException;
172
173
174
175 /**
176 * Gets the "db-checkpointer-bytes-interval" property.
177 * <p>
178 * Specifies the maximum number of bytes that may be written to the
179 * database before it is forced to perform a checkpoint.
180 * <p>
181 * This can be used to bound the recovery time that may be required
182 * if the database environment is opened without having been properly
183 * closed. If this property is set to a non-zero value, the
184 * checkpointer wakeup interval is not used. To use time-based
185 * checkpointing, set this property to zero.
186 *
187 * @return Returns the value of the "db-checkpointer-bytes-interval" property.
188 */
189 long getDBCheckpointerBytesInterval();
190
191
192
193 /**
194 * Sets the "db-checkpointer-bytes-interval" property.
195 * <p>
196 * Specifies the maximum number of bytes that may be written to the
197 * database before it is forced to perform a checkpoint.
198 * <p>
199 * This can be used to bound the recovery time that may be required
200 * if the database environment is opened without having been properly
201 * closed. If this property is set to a non-zero value, the
202 * checkpointer wakeup interval is not used. To use time-based
203 * checkpointing, set this property to zero.
204 *
205 * @param value The value of the "db-checkpointer-bytes-interval" property.
206 * @throws IllegalPropertyValueException
207 * If the new value is invalid.
208 */
209 void setDBCheckpointerBytesInterval(Long value) throws IllegalPropertyValueException;
210
211
212
213 /**
214 * Gets the "db-checkpointer-wakeup-interval" property.
215 * <p>
216 * Specifies the maximum length of time that may pass between
217 * checkpoints.
218 * <p>
219 * Note that this is only used if the value of the checkpointer
220 * bytes interval is zero.
221 *
222 * @return Returns the value of the "db-checkpointer-wakeup-interval" property.
223 */
224 long getDBCheckpointerWakeupInterval();
225
226
227
228 /**
229 * Sets the "db-checkpointer-wakeup-interval" property.
230 * <p>
231 * Specifies the maximum length of time that may pass between
232 * checkpoints.
233 * <p>
234 * Note that this is only used if the value of the checkpointer
235 * bytes interval is zero.
236 *
237 * @param value The value of the "db-checkpointer-wakeup-interval" property.
238 * @throws IllegalPropertyValueException
239 * If the new value is invalid.
240 */
241 void setDBCheckpointerWakeupInterval(Long value) throws IllegalPropertyValueException;
242
243
244
245 /**
246 * Gets the "db-cleaner-min-utilization" property.
247 * <p>
248 * Specifies the minimum percentage of "live" data that the database
249 * cleaner attempts to keep in database log files.
250 * <p>
251 * If the amount of live data in any database log file drops below
252 * this percentage, then the cleaner moves the remaining live data in
253 * that file to the end of the database and deletes the original file
254 * in order to keep the database relatively compact.
255 *
256 * @return Returns the value of the "db-cleaner-min-utilization" property.
257 */
258 int getDBCleanerMinUtilization();
259
260
261
262 /**
263 * Sets the "db-cleaner-min-utilization" property.
264 * <p>
265 * Specifies the minimum percentage of "live" data that the database
266 * cleaner attempts to keep in database log files.
267 * <p>
268 * If the amount of live data in any database log file drops below
269 * this percentage, then the cleaner moves the remaining live data in
270 * that file to the end of the database and deletes the original file
271 * in order to keep the database relatively compact.
272 *
273 * @param value The value of the "db-cleaner-min-utilization" property.
274 * @throws IllegalPropertyValueException
275 * If the new value is invalid.
276 */
277 void setDBCleanerMinUtilization(Integer value) throws IllegalPropertyValueException;
278
279
280
281 /**
282 * Gets the "db-directory" property.
283 * <p>
284 * Specifies the path to the filesystem directory that is used to
285 * hold the Berkeley DB Java Edition database files containing the
286 * data for this backend.
287 * <p>
288 * The path may be either an absolute path or a path relative to the
289 * directory containing the base of the OpenDS Directory Server
290 * installation. The path may be any valid directory path in which
291 * the server has appropriate permissions to read and write files and
292 * has sufficient space to hold the database contents.
293 *
294 * @return Returns the value of the "db-directory" property.
295 */
296 String getDBDirectory();
297
298
299
300 /**
301 * Sets the "db-directory" property.
302 * <p>
303 * Specifies the path to the filesystem directory that is used to
304 * hold the Berkeley DB Java Edition database files containing the
305 * data for this backend.
306 * <p>
307 * The path may be either an absolute path or a path relative to the
308 * directory containing the base of the OpenDS Directory Server
309 * installation. The path may be any valid directory path in which
310 * the server has appropriate permissions to read and write files and
311 * has sufficient space to hold the database contents.
312 *
313 * @param value The value of the "db-directory" property.
314 * @throws IllegalPropertyValueException
315 * If the new value is invalid.
316 */
317 void setDBDirectory(String value) throws IllegalPropertyValueException;
318
319
320
321 /**
322 * Gets the "db-directory-permissions" property.
323 * <p>
324 * Specifies the permissions that should be applied to the directory
325 * containing the server database files.
326 * <p>
327 * They should be expressed as three-digit octal values, which is
328 * the traditional representation for UNIX file permissions. The
329 * three digits represent the permissions that are available for the
330 * directory's owner, group members, and other users (in that order),
331 * and each digit is the octal representation of the read, write, and
332 * execute bits. Note that this only impacts permissions on the
333 * database directory and not on the files written into that
334 * directory. On UNIX systems, the user's umask controls permissions
335 * given to the database files.
336 *
337 * @return Returns the value of the "db-directory-permissions" property.
338 */
339 String getDBDirectoryPermissions();
340
341
342
343 /**
344 * Sets the "db-directory-permissions" property.
345 * <p>
346 * Specifies the permissions that should be applied to the directory
347 * containing the server database files.
348 * <p>
349 * They should be expressed as three-digit octal values, which is
350 * the traditional representation for UNIX file permissions. The
351 * three digits represent the permissions that are available for the
352 * directory's owner, group members, and other users (in that order),
353 * and each digit is the octal representation of the read, write, and
354 * execute bits. Note that this only impacts permissions on the
355 * database directory and not on the files written into that
356 * directory. On UNIX systems, the user's umask controls permissions
357 * given to the database files.
358 *
359 * @param value The value of the "db-directory-permissions" property.
360 * @throws IllegalPropertyValueException
361 * If the new value is invalid.
362 */
363 void setDBDirectoryPermissions(String value) throws IllegalPropertyValueException;
364
365
366
367 /**
368 * Gets the "db-evictor-lru-only" property.
369 * <p>
370 * Indicates whether the database should evict existing data from
371 * the cache based on an LRU policy (where the least recently used
372 * information will be evicted first).
373 * <p>
374 * If set to "false", then the eviction keeps internal nodes of the
375 * underlying Btree in the cache over leaf notes, even if the leaf
376 * nodes have been accessed more recently. This may be a better
377 * configuration for databases in which only a very small portion of
378 * the data is cached.
379 *
380 * @return Returns the value of the "db-evictor-lru-only" property.
381 */
382 boolean isDBEvictorLruOnly();
383
384
385
386 /**
387 * Sets the "db-evictor-lru-only" property.
388 * <p>
389 * Indicates whether the database should evict existing data from
390 * the cache based on an LRU policy (where the least recently used
391 * information will be evicted first).
392 * <p>
393 * If set to "false", then the eviction keeps internal nodes of the
394 * underlying Btree in the cache over leaf notes, even if the leaf
395 * nodes have been accessed more recently. This may be a better
396 * configuration for databases in which only a very small portion of
397 * the data is cached.
398 *
399 * @param value The value of the "db-evictor-lru-only" property.
400 * @throws IllegalPropertyValueException
401 * If the new value is invalid.
402 */
403 void setDBEvictorLruOnly(Boolean value) throws IllegalPropertyValueException;
404
405
406
407 /**
408 * Gets the "db-evictor-nodes-per-scan" property.
409 * <p>
410 * Specifies the number of Btree nodes that should be evicted from
411 * the cache in a single pass if it is determined that it is
412 * necessary to free existing data in order to make room for new
413 * information.
414 * <p>
415 * Changes to this property do not take effect until the backend is
416 * restarted. It is recommended that you also change this property
417 * when you set db-evictor-lru-only to false. This setting controls
418 * the number of Btree nodes that are considered, or sampled, each
419 * time a node is evicted. A setting of 100 often produces good
420 * results, but this may vary from application to application. The
421 * larger the nodes per scan, the more accurate the algorithm.
422 * However, setting it too high is detrimental; the need to consider
423 * larger numbers of nodes for each eviction may delay the completion
424 * of a given database operation, which will impact the response time
425 * of the application thread.
426 *
427 * @return Returns the value of the "db-evictor-nodes-per-scan" property.
428 */
429 int getDBEvictorNodesPerScan();
430
431
432
433 /**
434 * Sets the "db-evictor-nodes-per-scan" property.
435 * <p>
436 * Specifies the number of Btree nodes that should be evicted from
437 * the cache in a single pass if it is determined that it is
438 * necessary to free existing data in order to make room for new
439 * information.
440 * <p>
441 * Changes to this property do not take effect until the backend is
442 * restarted. It is recommended that you also change this property
443 * when you set db-evictor-lru-only to false. This setting controls
444 * the number of Btree nodes that are considered, or sampled, each
445 * time a node is evicted. A setting of 100 often produces good
446 * results, but this may vary from application to application. The
447 * larger the nodes per scan, the more accurate the algorithm.
448 * However, setting it too high is detrimental; the need to consider
449 * larger numbers of nodes for each eviction may delay the completion
450 * of a given database operation, which will impact the response time
451 * of the application thread.
452 *
453 * @param value The value of the "db-evictor-nodes-per-scan" property.
454 * @throws IllegalPropertyValueException
455 * If the new value is invalid.
456 */
457 void setDBEvictorNodesPerScan(Integer value) throws IllegalPropertyValueException;
458
459
460
461 /**
462 * Gets the "db-log-file-max" property.
463 * <p>
464 * Specifies the maximum size for a database log file.
465 *
466 * @return Returns the value of the "db-log-file-max" property.
467 */
468 long getDBLogFileMax();
469
470
471
472 /**
473 * Sets the "db-log-file-max" property.
474 * <p>
475 * Specifies the maximum size for a database log file.
476 *
477 * @param value The value of the "db-log-file-max" property.
478 * @throws IllegalPropertyValueException
479 * If the new value is invalid.
480 */
481 void setDBLogFileMax(Long value) throws IllegalPropertyValueException;
482
483
484
485 /**
486 * Gets the "db-logging-file-handler-on" property.
487 * <p>
488 * Indicates whether the database should maintain a je.info file in
489 * the same directory as the database log directory.
490 * <p>
491 * This file contains information about the internal processing
492 * performed by the underlying database.
493 *
494 * @return Returns the value of the "db-logging-file-handler-on" property.
495 */
496 boolean isDBLoggingFileHandlerOn();
497
498
499
500 /**
501 * Sets the "db-logging-file-handler-on" property.
502 * <p>
503 * Indicates whether the database should maintain a je.info file in
504 * the same directory as the database log directory.
505 * <p>
506 * This file contains information about the internal processing
507 * performed by the underlying database.
508 *
509 * @param value The value of the "db-logging-file-handler-on" property.
510 * @throws IllegalPropertyValueException
511 * If the new value is invalid.
512 */
513 void setDBLoggingFileHandlerOn(Boolean value) throws IllegalPropertyValueException;
514
515
516
517 /**
518 * Gets the "db-logging-level" property.
519 * <p>
520 * Specifies the log level that should be used by the database when
521 * it is writing information into the je.info file.
522 * <p>
523 * The database trace logging level is (in increasing order of
524 * verbosity) chosen from: OFF, SEVERE, WARNING, INFO, CONFIG, FINE,
525 * FINER, FINEST, ALL.
526 *
527 * @return Returns the value of the "db-logging-level" property.
528 */
529 String getDBLoggingLevel();
530
531
532
533 /**
534 * Sets the "db-logging-level" property.
535 * <p>
536 * Specifies the log level that should be used by the database when
537 * it is writing information into the je.info file.
538 * <p>
539 * The database trace logging level is (in increasing order of
540 * verbosity) chosen from: OFF, SEVERE, WARNING, INFO, CONFIG, FINE,
541 * FINER, FINEST, ALL.
542 *
543 * @param value The value of the "db-logging-level" property.
544 * @throws IllegalPropertyValueException
545 * If the new value is invalid.
546 */
547 void setDBLoggingLevel(String value) throws IllegalPropertyValueException;
548
549
550
551 /**
552 * Gets the "db-num-cleaner-threads" property.
553 * <p>
554 * Specifies the number of threads that the backend should maintain
555 * to keep the database log files at or near the desired utilization.
556 * <p>
557 * In environments with high write throughput, multiple cleaner
558 * threads may be required to maintain the desired utilization.
559 *
560 * @return Returns the value of the "db-num-cleaner-threads" property.
561 */
562 int getDBNumCleanerThreads();
563
564
565
566 /**
567 * Sets the "db-num-cleaner-threads" property.
568 * <p>
569 * Specifies the number of threads that the backend should maintain
570 * to keep the database log files at or near the desired utilization.
571 * <p>
572 * In environments with high write throughput, multiple cleaner
573 * threads may be required to maintain the desired utilization.
574 *
575 * @param value The value of the "db-num-cleaner-threads" property.
576 * @throws IllegalPropertyValueException
577 * If the new value is invalid.
578 */
579 void setDBNumCleanerThreads(Integer value) throws IllegalPropertyValueException;
580
581
582
583 /**
584 * Gets the "db-num-lock-tables" property.
585 * <p>
586 * Specifies the number of lock tables that are used by the
587 * underlying database.
588 * <p>
589 * This can be particularly important to help improve scalability by
590 * avoiding contention on systems with large numbers of CPUs. The
591 * value of this configuration property should be set to a prime
592 * number that is less than or equal to the number of worker threads
593 * configured for use in the server.
594 *
595 * @return Returns the value of the "db-num-lock-tables" property.
596 */
597 int getDBNumLockTables();
598
599
600
601 /**
602 * Sets the "db-num-lock-tables" property.
603 * <p>
604 * Specifies the number of lock tables that are used by the
605 * underlying database.
606 * <p>
607 * This can be particularly important to help improve scalability by
608 * avoiding contention on systems with large numbers of CPUs. The
609 * value of this configuration property should be set to a prime
610 * number that is less than or equal to the number of worker threads
611 * configured for use in the server.
612 *
613 * @param value The value of the "db-num-lock-tables" property.
614 * @throws IllegalPropertyValueException
615 * If the new value is invalid.
616 */
617 void setDBNumLockTables(Integer value) throws IllegalPropertyValueException;
618
619
620
621 /**
622 * Gets the "db-run-cleaner" property.
623 * <p>
624 * Indicates whether the database cleaner threads should be enabled.
625 * <p>
626 * The cleaner threads are used to periodically compact the database
627 * by identifying database files with a low (that is, less than the
628 * amount specified by the db-cleaner-min-utilization property)
629 * percentage of live data, moving the remaining live data to the end
630 * of the log and deleting that file.
631 *
632 * @return Returns the value of the "db-run-cleaner" property.
633 */
634 boolean isDBRunCleaner();
635
636
637
638 /**
639 * Sets the "db-run-cleaner" property.
640 * <p>
641 * Indicates whether the database cleaner threads should be enabled.
642 * <p>
643 * The cleaner threads are used to periodically compact the database
644 * by identifying database files with a low (that is, less than the
645 * amount specified by the db-cleaner-min-utilization property)
646 * percentage of live data, moving the remaining live data to the end
647 * of the log and deleting that file.
648 *
649 * @param value The value of the "db-run-cleaner" property.
650 * @throws IllegalPropertyValueException
651 * If the new value is invalid.
652 */
653 void setDBRunCleaner(Boolean value) throws IllegalPropertyValueException;
654
655
656
657 /**
658 * Gets the "db-txn-no-sync" property.
659 * <p>
660 * Indicates whether database writes should be primarily written to
661 * an internal buffer but not immediately written to disk.
662 * <p>
663 * Setting the value of this configuration attribute to "true" may
664 * improve write performance but could cause the most recent changes
665 * to be lost if the OpenDS Directory Server or the underlying JVM
666 * exits abnormally, or if an OS or hardware failure occurs (a
667 * behavior similar to running with transaction durability disabled
668 * in the Sun Java System Directory Server).
669 *
670 * @return Returns the value of the "db-txn-no-sync" property.
671 */
672 boolean isDBTxnNoSync();
673
674
675
676 /**
677 * Sets the "db-txn-no-sync" property.
678 * <p>
679 * Indicates whether database writes should be primarily written to
680 * an internal buffer but not immediately written to disk.
681 * <p>
682 * Setting the value of this configuration attribute to "true" may
683 * improve write performance but could cause the most recent changes
684 * to be lost if the OpenDS Directory Server or the underlying JVM
685 * exits abnormally, or if an OS or hardware failure occurs (a
686 * behavior similar to running with transaction durability disabled
687 * in the Sun Java System Directory Server).
688 *
689 * @param value The value of the "db-txn-no-sync" property.
690 * @throws IllegalPropertyValueException
691 * If the new value is invalid.
692 */
693 void setDBTxnNoSync(Boolean value) throws IllegalPropertyValueException;
694
695
696
697 /**
698 * Gets the "db-txn-write-no-sync" property.
699 * <p>
700 * Indicates whether the database should synchronously flush data as
701 * it is written to disk.
702 * <p>
703 * If this value is set to "false", then all data written to disk is
704 * synchronously flushed to persistent storage and thereby providing
705 * full durability. If it is set to "true", then data may be cached
706 * for a period of time by the underlying operating system before
707 * actually being written to disk. This may improve performance, but
708 * could cause the most recent changes to be lost in the event of an
709 * underlying OS or hardware failure (but not in the case that the
710 * OpenDS Directory Server or the JVM exits abnormally).
711 *
712 * @return Returns the value of the "db-txn-write-no-sync" property.
713 */
714 boolean isDBTxnWriteNoSync();
715
716
717
718 /**
719 * Sets the "db-txn-write-no-sync" property.
720 * <p>
721 * Indicates whether the database should synchronously flush data as
722 * it is written to disk.
723 * <p>
724 * If this value is set to "false", then all data written to disk is
725 * synchronously flushed to persistent storage and thereby providing
726 * full durability. If it is set to "true", then data may be cached
727 * for a period of time by the underlying operating system before
728 * actually being written to disk. This may improve performance, but
729 * could cause the most recent changes to be lost in the event of an
730 * underlying OS or hardware failure (but not in the case that the
731 * OpenDS Directory Server or the JVM exits abnormally).
732 *
733 * @param value The value of the "db-txn-write-no-sync" property.
734 * @throws IllegalPropertyValueException
735 * If the new value is invalid.
736 */
737 void setDBTxnWriteNoSync(Boolean value) throws IllegalPropertyValueException;
738
739
740
741 /**
742 * Gets the "deadlock-retry-limit" property.
743 * <p>
744 * Specifies the number of times that the server should retry an
745 * attempted operation in the backend if a deadlock results from two
746 * concurrent requests that interfere with each other in a
747 * conflicting manner.
748 * <p>
749 * A value of "0" indicates no limit.
750 *
751 * @return Returns the value of the "deadlock-retry-limit" property.
752 */
753 int getDeadlockRetryLimit();
754
755
756
757 /**
758 * Sets the "deadlock-retry-limit" property.
759 * <p>
760 * Specifies the number of times that the server should retry an
761 * attempted operation in the backend if a deadlock results from two
762 * concurrent requests that interfere with each other in a
763 * conflicting manner.
764 * <p>
765 * A value of "0" indicates no limit.
766 *
767 * @param value The value of the "deadlock-retry-limit" property.
768 * @throws IllegalPropertyValueException
769 * If the new value is invalid.
770 */
771 void setDeadlockRetryLimit(Integer value) throws IllegalPropertyValueException;
772
773
774
775 /**
776 * Gets the "entries-compressed" property.
777 * <p>
778 * Indicates whether the backend should attempt to compress entries
779 * before storing them in the database.
780 * <p>
781 * Note that this property applies only to the entries themselves
782 * and does not impact the index data. Further, the effectiveness of
783 * the compression is based on the type of data contained in the
784 * entry.
785 *
786 * @return Returns the value of the "entries-compressed" property.
787 */
788 boolean isEntriesCompressed();
789
790
791
792 /**
793 * Sets the "entries-compressed" property.
794 * <p>
795 * Indicates whether the backend should attempt to compress entries
796 * before storing them in the database.
797 * <p>
798 * Note that this property applies only to the entries themselves
799 * and does not impact the index data. Further, the effectiveness of
800 * the compression is based on the type of data contained in the
801 * entry.
802 *
803 * @param value The value of the "entries-compressed" property.
804 * @throws IllegalPropertyValueException
805 * If the new value is invalid.
806 */
807 void setEntriesCompressed(Boolean value) throws IllegalPropertyValueException;
808
809
810
811 /**
812 * Gets the "import-queue-size" property.
813 * <p>
814 * Specifies the size (in number of entries) of the queue that is
815 * used to hold the entries read during an LDIF import.
816 *
817 * @return Returns the value of the "import-queue-size" property.
818 */
819 int getImportQueueSize();
820
821
822
823 /**
824 * Sets the "import-queue-size" property.
825 * <p>
826 * Specifies the size (in number of entries) of the queue that is
827 * used to hold the entries read during an LDIF import.
828 *
829 * @param value The value of the "import-queue-size" property.
830 * @throws IllegalPropertyValueException
831 * If the new value is invalid.
832 */
833 void setImportQueueSize(Integer value) throws IllegalPropertyValueException;
834
835
836
837 /**
838 * Gets the "import-thread-count" property.
839 * <p>
840 * Specifies the number of threads that is used for concurrent
841 * processing during an LDIF import.
842 * <p>
843 * This should generally be a small multiple (for example, 2x) of
844 * the number of CPUs in the system for a traditional system, or
845 * equal to the number of CPU strands for a CMT system.
846 *
847 * @return Returns the value of the "import-thread-count" property.
848 */
849 int getImportThreadCount();
850
851
852
853 /**
854 * Sets the "import-thread-count" property.
855 * <p>
856 * Specifies the number of threads that is used for concurrent
857 * processing during an LDIF import.
858 * <p>
859 * This should generally be a small multiple (for example, 2x) of
860 * the number of CPUs in the system for a traditional system, or
861 * equal to the number of CPU strands for a CMT system.
862 *
863 * @param value The value of the "import-thread-count" property.
864 * @throws IllegalPropertyValueException
865 * If the new value is invalid.
866 */
867 void setImportThreadCount(Integer value) throws IllegalPropertyValueException;
868
869
870
871 /**
872 * Gets the "index-entry-limit" property.
873 * <p>
874 * Specifies the maximum number of entries that is allowed to match
875 * a given index key before that particular index key is no longer
876 * maintained.
877 * <p>
878 * This property is analogous to the ALL IDs threshold in the Sun
879 * Java System Directory Server. Note that this is the default limit
880 * for the backend, and it may be overridden on a per-attribute
881 * basis.A value of 0 means there is no limit.
882 *
883 * @return Returns the value of the "index-entry-limit" property.
884 */
885 int getIndexEntryLimit();
886
887
888
889 /**
890 * Sets the "index-entry-limit" property.
891 * <p>
892 * Specifies the maximum number of entries that is allowed to match
893 * a given index key before that particular index key is no longer
894 * maintained.
895 * <p>
896 * This property is analogous to the ALL IDs threshold in the Sun
897 * Java System Directory Server. Note that this is the default limit
898 * for the backend, and it may be overridden on a per-attribute
899 * basis.A value of 0 means there is no limit.
900 *
901 * @param value The value of the "index-entry-limit" property.
902 * @throws IllegalPropertyValueException
903 * If the new value is invalid.
904 */
905 void setIndexEntryLimit(Integer value) throws IllegalPropertyValueException;
906
907
908
909 /**
910 * Gets the "java-class" property.
911 * <p>
912 * Specifies the fully-qualified name of the Java class that
913 * provides the backend implementation.
914 *
915 * @return Returns the value of the "java-class" property.
916 */
917 String getJavaClass();
918
919
920
921 /**
922 * Sets the "java-class" property.
923 * <p>
924 * Specifies the fully-qualified name of the Java class that
925 * provides the backend implementation.
926 *
927 * @param value The value of the "java-class" property.
928 * @throws IllegalPropertyValueException
929 * If the new value is invalid.
930 */
931 void setJavaClass(String value) throws IllegalPropertyValueException;
932
933
934
935 /**
936 * Gets the "je-property" property.
937 * <p>
938 * Specifies the database and environment properties for the
939 * Berkeley DB Java Edition database serving the data for this
940 * backend.
941 * <p>
942 * Any Berkeley DB Java Edition property can be specified using the
943 * following form: property-name=property-value. Refer to OpenDS
944 * documentation for further information on related properties, their
945 * implications, and range values. The definitive identification of
946 * all the property parameters is available in the example.properties
947 * file of Berkeley DB Java Edition distribution.
948 *
949 * @return Returns the values of the "je-property" property.
950 */
951 SortedSet<String> getJEProperty();
952
953
954
955 /**
956 * Sets the "je-property" property.
957 * <p>
958 * Specifies the database and environment properties for the
959 * Berkeley DB Java Edition database serving the data for this
960 * backend.
961 * <p>
962 * Any Berkeley DB Java Edition property can be specified using the
963 * following form: property-name=property-value. Refer to OpenDS
964 * documentation for further information on related properties, their
965 * implications, and range values. The definitive identification of
966 * all the property parameters is available in the example.properties
967 * file of Berkeley DB Java Edition distribution.
968 *
969 * @param values The values of the "je-property" property.
970 * @throws IllegalPropertyValueException
971 * If one or more of the new values are invalid.
972 */
973 void setJEProperty(Collection<String> values) throws IllegalPropertyValueException;
974
975
976
977 /**
978 * Gets the "preload-time-limit" property.
979 * <p>
980 * Specifies the length of time that the backend is allowed to spend
981 * "pre-loading" data when it is initialized.
982 * <p>
983 * The pre-load process is used to pre-populate the database cache,
984 * so that it can be more quickly available when the server is
985 * processing requests. A duration of zero means there is no
986 * pre-load.
987 *
988 * @return Returns the value of the "preload-time-limit" property.
989 */
990 long getPreloadTimeLimit();
991
992
993
994 /**
995 * Sets the "preload-time-limit" property.
996 * <p>
997 * Specifies the length of time that the backend is allowed to spend
998 * "pre-loading" data when it is initialized.
999 * <p>
1000 * The pre-load process is used to pre-populate the database cache,
1001 * so that it can be more quickly available when the server is
1002 * processing requests. A duration of zero means there is no
1003 * pre-load.
1004 *
1005 * @param value The value of the "preload-time-limit" property.
1006 * @throws IllegalPropertyValueException
1007 * If the new value is invalid.
1008 */
1009 void setPreloadTimeLimit(Long value) throws IllegalPropertyValueException;
1010
1011
1012
1013 /**
1014 * Gets the "subtree-delete-batch-size" property.
1015 * <p>
1016 * Specifies the maximum number of entries that may be deleted from
1017 * the backend when using the subtree delete control within a single
1018 * transaction.
1019 * <p>
1020 * If a subtree delete operation targets a subtree with more than
1021 * this number of entries, then additional transactions are used to
1022 * remove the remaining entries in that subtree.
1023 *
1024 * @return Returns the value of the "subtree-delete-batch-size" property.
1025 */
1026 int getSubtreeDeleteBatchSize();
1027
1028
1029
1030 /**
1031 * Sets the "subtree-delete-batch-size" property.
1032 * <p>
1033 * Specifies the maximum number of entries that may be deleted from
1034 * the backend when using the subtree delete control within a single
1035 * transaction.
1036 * <p>
1037 * If a subtree delete operation targets a subtree with more than
1038 * this number of entries, then additional transactions are used to
1039 * remove the remaining entries in that subtree.
1040 *
1041 * @param value The value of the "subtree-delete-batch-size" property.
1042 * @throws IllegalPropertyValueException
1043 * If the new value is invalid.
1044 */
1045 void setSubtreeDeleteBatchSize(Integer value) throws IllegalPropertyValueException;
1046
1047
1048
1049 /**
1050 * Gets the "subtree-delete-size-limit" property.
1051 * <p>
1052 * Specifies the maximum number of entries that may be deleted from
1053 * the backend when using the subtree delete control.
1054 * <p>
1055 * If a subtree delete operation targets a subtree with more than
1056 * this number of entries, then multiple passes may be required to
1057 * remove all entries in that subtree.
1058 *
1059 * @return Returns the value of the "subtree-delete-size-limit" property.
1060 */
1061 int getSubtreeDeleteSizeLimit();
1062
1063
1064
1065 /**
1066 * Sets the "subtree-delete-size-limit" property.
1067 * <p>
1068 * Specifies the maximum number of entries that may be deleted from
1069 * the backend when using the subtree delete control.
1070 * <p>
1071 * If a subtree delete operation targets a subtree with more than
1072 * this number of entries, then multiple passes may be required to
1073 * remove all entries in that subtree.
1074 *
1075 * @param value The value of the "subtree-delete-size-limit" property.
1076 * @throws IllegalPropertyValueException
1077 * If the new value is invalid.
1078 */
1079 void setSubtreeDeleteSizeLimit(Integer value) throws IllegalPropertyValueException;
1080
1081
1082
1083 /**
1084 * Gets the "writability-mode" property.
1085 * <p>
1086 * Specifies the behavior that the backend should use when
1087 * processing write operations.
1088 *
1089 * @return Returns the value of the "writability-mode" property.
1090 */
1091 WritabilityMode getWritabilityMode();
1092
1093
1094
1095 /**
1096 * Sets the "writability-mode" property.
1097 * <p>
1098 * Specifies the behavior that the backend should use when
1099 * processing write operations.
1100 *
1101 * @param value The value of the "writability-mode" property.
1102 * @throws IllegalPropertyValueException
1103 * If the new value is invalid.
1104 */
1105 void setWritabilityMode(WritabilityMode value) throws IllegalPropertyValueException;
1106
1107
1108
1109 /**
1110 * Lists the Local DB Indexes.
1111 *
1112 * @return Returns an array containing the names of the Local DB
1113 * Indexes.
1114 * @throws ConcurrentModificationException
1115 * If this Local DB Backend has been removed from the
1116 * server by another client.
1117 * @throws AuthorizationException
1118 * If the server refuses to list the Local DB Indexes
1119 * because the client does not have the correct privileges.
1120 * @throws CommunicationException
1121 * If the client cannot contact the server due to an
1122 * underlying communication problem.
1123 */
1124 String[] listLocalDBIndexes() throws ConcurrentModificationException,
1125 AuthorizationException, CommunicationException;
1126
1127
1128
1129 /**
1130 * Gets the named Local DB Index.
1131 *
1132 * @param name
1133 * The name of the Local DB Index to retrieve.
1134 * @return Returns the named Local DB Index.
1135 * @throws DefinitionDecodingException
1136 * If the named Local DB Index was found but its type
1137 * could not be determined.
1138 * @throws ManagedObjectDecodingException
1139 * If the named Local DB Index was found but one or more
1140 * of its properties could not be decoded.
1141 * @throws ManagedObjectNotFoundException
1142 * If the named Local DB Index was not found on the
1143 * server.
1144 * @throws ConcurrentModificationException
1145 * If this Local DB Backend has been removed from the
1146 * server by another client.
1147 * @throws AuthorizationException
1148 * If the server refuses to retrieve the named Local DB
1149 * Index because the client does not have the correct
1150 * privileges.
1151 * @throws CommunicationException
1152 * If the client cannot contact the server due to an
1153 * underlying communication problem.
1154 */
1155 LocalDBIndexCfgClient getLocalDBIndex(String name)
1156 throws DefinitionDecodingException, ManagedObjectDecodingException,
1157 ManagedObjectNotFoundException, ConcurrentModificationException,
1158 AuthorizationException, CommunicationException;
1159
1160
1161
1162 /**
1163 * Creates a new Local DB Index. The new Local DB Index will
1164 * initially not contain any property values (including mandatory
1165 * properties). Once the Local DB Index has been configured it can be
1166 * added to the server using the {@link #commit()} method.
1167 *
1168 * @param <C>
1169 * The type of the Local DB Index being created.
1170 * @param d
1171 * The definition of the Local DB Index to be created.
1172 * @param name
1173 * The name of the new Local DB Index.
1174 * @param exceptions
1175 * An optional collection in which to place any {@link
1176 * DefaultBehaviorException}s that occurred whilst
1177 * attempting to determine the default values of the Local
1178 * DB Index. This argument can be <code>null<code>.
1179 * @return Returns a new Local DB Index configuration instance.
1180 * @throws IllegalManagedObjectNameException
1181 * If the name of the new Local DB Index is invalid.
1182 */
1183 <C extends LocalDBIndexCfgClient> C createLocalDBIndex(
1184 ManagedObjectDefinition<C, ? extends LocalDBIndexCfg> d, String name, Collection<DefaultBehaviorException> exceptions) throws IllegalManagedObjectNameException;
1185
1186
1187
1188 /**
1189 * Removes the named Local DB Index.
1190 *
1191 * @param name
1192 * The name of the Local DB Index to remove.
1193 * @throws ManagedObjectNotFoundException
1194 * If the Local DB Index does not exist.
1195 * @throws OperationRejectedException
1196 * If the server refuses to remove the Local DB Index due
1197 * to some server-side constraint which cannot be satisfied
1198 * (for example, if it is referenced by another managed
1199 * object).
1200 * @throws ConcurrentModificationException
1201 * If this Local DB Backend has been removed from the
1202 * server by another client.
1203 * @throws AuthorizationException
1204 * If the server refuses to remove the Local DB Index
1205 * because the client does not have the correct privileges.
1206 * @throws CommunicationException
1207 * If the client cannot contact the server due to an
1208 * underlying communication problem.
1209 */
1210 void removeLocalDBIndex(String name)
1211 throws ManagedObjectNotFoundException, OperationRejectedException,
1212 ConcurrentModificationException, AuthorizationException,
1213 CommunicationException;
1214
1215
1216
1217 /**
1218 * Lists the Local DB VLV Indexes.
1219 *
1220 * @return Returns an array containing the names of the Local DB VLV
1221 * Indexes.
1222 * @throws ConcurrentModificationException
1223 * If this Local DB Backend has been removed from the
1224 * server by another client.
1225 * @throws AuthorizationException
1226 * If the server refuses to list the Local DB VLV Indexes
1227 * because the client does not have the correct privileges.
1228 * @throws CommunicationException
1229 * If the client cannot contact the server due to an
1230 * underlying communication problem.
1231 */
1232 String[] listLocalDBVLVIndexes() throws ConcurrentModificationException,
1233 AuthorizationException, CommunicationException;
1234
1235
1236
1237 /**
1238 * Gets the named Local DB VLV Index.
1239 *
1240 * @param name
1241 * The name of the Local DB VLV Index to retrieve.
1242 * @return Returns the named Local DB VLV Index.
1243 * @throws DefinitionDecodingException
1244 * If the named Local DB VLV Index was found but its type
1245 * could not be determined.
1246 * @throws ManagedObjectDecodingException
1247 * If the named Local DB VLV Index was found but one or
1248 * more of its properties could not be decoded.
1249 * @throws ManagedObjectNotFoundException
1250 * If the named Local DB VLV Index was not found on the
1251 * server.
1252 * @throws ConcurrentModificationException
1253 * If this Local DB Backend has been removed from the
1254 * server by another client.
1255 * @throws AuthorizationException
1256 * If the server refuses to retrieve the named Local DB
1257 * VLV Index because the client does not have the correct
1258 * privileges.
1259 * @throws CommunicationException
1260 * If the client cannot contact the server due to an
1261 * underlying communication problem.
1262 */
1263 LocalDBVLVIndexCfgClient getLocalDBVLVIndex(String name)
1264 throws DefinitionDecodingException, ManagedObjectDecodingException,
1265 ManagedObjectNotFoundException, ConcurrentModificationException,
1266 AuthorizationException, CommunicationException;
1267
1268
1269
1270 /**
1271 * Creates a new Local DB VLV Index. The new Local DB VLV Index will
1272 * initially not contain any property values (including mandatory
1273 * properties). Once the Local DB VLV Index has been configured it
1274 * can be added to the server using the {@link #commit()} method.
1275 *
1276 * @param <C>
1277 * The type of the Local DB VLV Index being created.
1278 * @param d
1279 * The definition of the Local DB VLV Index to be created.
1280 * @param name
1281 * The name of the new Local DB VLV Index.
1282 * @param exceptions
1283 * An optional collection in which to place any {@link
1284 * DefaultBehaviorException}s that occurred whilst
1285 * attempting to determine the default values of the Local
1286 * DB VLV Index. This argument can be <code>null<code>.
1287 * @return Returns a new Local DB VLV Index configuration instance.
1288 * @throws IllegalManagedObjectNameException
1289 * If the name of the new Local DB VLV Index is invalid.
1290 */
1291 <C extends LocalDBVLVIndexCfgClient> C createLocalDBVLVIndex(
1292 ManagedObjectDefinition<C, ? extends LocalDBVLVIndexCfg> d, String name, Collection<DefaultBehaviorException> exceptions) throws IllegalManagedObjectNameException;
1293
1294
1295
1296 /**
1297 * Removes the named Local DB VLV Index.
1298 *
1299 * @param name
1300 * The name of the Local DB VLV Index to remove.
1301 * @throws ManagedObjectNotFoundException
1302 * If the Local DB VLV Index does not exist.
1303 * @throws OperationRejectedException
1304 * If the server refuses to remove the Local DB VLV Index
1305 * due to some server-side constraint which cannot be
1306 * satisfied (for example, if it is referenced by another
1307 * managed object).
1308 * @throws ConcurrentModificationException
1309 * If this Local DB Backend has been removed from the
1310 * server by another client.
1311 * @throws AuthorizationException
1312 * If the server refuses to remove the Local DB VLV Index
1313 * because the client does not have the correct privileges.
1314 * @throws CommunicationException
1315 * If the client cannot contact the server due to an
1316 * underlying communication problem.
1317 */
1318 void removeLocalDBVLVIndex(String name)
1319 throws ManagedObjectNotFoundException, OperationRejectedException,
1320 ConcurrentModificationException, AuthorizationException,
1321 CommunicationException;
1322
1323 }