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.client; 017 018 019 020import java.util.Collection; 021import org.forgerock.opendj.config.client.ConcurrentModificationException; 022import org.forgerock.opendj.config.client.IllegalManagedObjectNameException; 023import org.forgerock.opendj.config.client.ManagedObjectDecodingException; 024import org.forgerock.opendj.config.client.OperationRejectedException; 025import org.forgerock.opendj.config.DefinitionDecodingException; 026import org.forgerock.opendj.config.ManagedObjectDefinition; 027import org.forgerock.opendj.config.ManagedObjectNotFoundException; 028import org.forgerock.opendj.config.PropertyException; 029import org.forgerock.opendj.ldap.LdapException; 030import org.forgerock.opendj.server.config.meta.BackendCfgDefn.WritabilityMode; 031import org.forgerock.opendj.server.config.server.BackendIndexCfg; 032import org.forgerock.opendj.server.config.server.BackendVLVIndexCfg; 033import org.forgerock.opendj.server.config.server.PluggableBackendCfg; 034 035 036 037/** 038 * A client-side interface for reading and modifying Pluggable Backend 039 * settings. 040 * <p> 041 * A Pluggable Backend stores application data in a pluggable 042 * database. 043 */ 044public interface PluggableBackendCfgClient extends BackendCfgClient { 045 046 /** 047 * Get the configuration definition associated with this Pluggable Backend. 048 * 049 * @return Returns the configuration definition associated with this Pluggable Backend. 050 */ 051 ManagedObjectDefinition<? extends PluggableBackendCfgClient, ? extends PluggableBackendCfg> definition(); 052 053 054 055 /** 056 * Gets the "cipher-key-length" property. 057 * <p> 058 * Specifies the key length in bits for the preferred cipher. 059 * 060 * @return Returns the value of the "cipher-key-length" property. 061 */ 062 int getCipherKeyLength(); 063 064 065 066 /** 067 * Sets the "cipher-key-length" property. 068 * <p> 069 * Specifies the key length in bits for the preferred cipher. 070 * 071 * @param value The value of the "cipher-key-length" property. 072 * @throws PropertyException 073 * If the new value is invalid. 074 */ 075 void setCipherKeyLength(Integer value) throws PropertyException; 076 077 078 079 /** 080 * Gets the "cipher-transformation" property. 081 * <p> 082 * Specifies the cipher for the directory server. The syntax is 083 * "algorithm/mode/padding". 084 * <p> 085 * The full transformation is required: specifying only an algorithm 086 * and allowing the cipher provider to supply the default mode and 087 * padding is not supported, because there is no guarantee these 088 * default values are the same among different implementations. Some 089 * cipher algorithms, including RC4 and ARCFOUR, do not have a mode 090 * or padding, and hence must be specified using NONE for the mode 091 * field and NoPadding for the padding field. For example, 092 * RC4/NONE/NoPadding. 093 * 094 * @return Returns the value of the "cipher-transformation" property. 095 */ 096 String getCipherTransformation(); 097 098 099 100 /** 101 * Sets the "cipher-transformation" property. 102 * <p> 103 * Specifies the cipher for the directory server. The syntax is 104 * "algorithm/mode/padding". 105 * <p> 106 * The full transformation is required: specifying only an algorithm 107 * and allowing the cipher provider to supply the default mode and 108 * padding is not supported, because there is no guarantee these 109 * default values are the same among different implementations. Some 110 * cipher algorithms, including RC4 and ARCFOUR, do not have a mode 111 * or padding, and hence must be specified using NONE for the mode 112 * field and NoPadding for the padding field. For example, 113 * RC4/NONE/NoPadding. 114 * 115 * @param value The value of the "cipher-transformation" property. 116 * @throws PropertyException 117 * If the new value is invalid. 118 */ 119 void setCipherTransformation(String value) throws PropertyException; 120 121 122 123 /** 124 * Gets the "compact-encoding" property. 125 * <p> 126 * Indicates whether the backend should use a compact form when 127 * encoding entries by compressing the attribute descriptions and 128 * object class sets. 129 * <p> 130 * Note that this property applies only to the entries themselves 131 * and does not impact the index data. 132 * 133 * @return Returns the value of the "compact-encoding" property. 134 */ 135 boolean isCompactEncoding(); 136 137 138 139 /** 140 * Sets the "compact-encoding" property. 141 * <p> 142 * Indicates whether the backend should use a compact form when 143 * encoding entries by compressing the attribute descriptions and 144 * object class sets. 145 * <p> 146 * Note that this property applies only to the entries themselves 147 * and does not impact the index data. 148 * 149 * @param value The value of the "compact-encoding" property. 150 * @throws PropertyException 151 * If the new value is invalid. 152 */ 153 void setCompactEncoding(Boolean value) throws PropertyException; 154 155 156 157 /** 158 * Gets the "confidentiality-enabled" property. 159 * <p> 160 * Indicates whether the backend should make entries in database 161 * files readable only by Directory Server. 162 * <p> 163 * Confidentiality is achieved by enrypting entries before writing 164 * them to the underlying storage. Entry encryption will protect data 165 * on disk from unauthorised parties reading the files; for complete 166 * protection, also set confidentiality for sensitive attributes 167 * indexes. The property cannot be set to false if some of the 168 * indexes have confidentiality set to true. 169 * 170 * @return Returns the value of the "confidentiality-enabled" property. 171 */ 172 boolean isConfidentialityEnabled(); 173 174 175 176 /** 177 * Sets the "confidentiality-enabled" property. 178 * <p> 179 * Indicates whether the backend should make entries in database 180 * files readable only by Directory Server. 181 * <p> 182 * Confidentiality is achieved by enrypting entries before writing 183 * them to the underlying storage. Entry encryption will protect data 184 * on disk from unauthorised parties reading the files; for complete 185 * protection, also set confidentiality for sensitive attributes 186 * indexes. The property cannot be set to false if some of the 187 * indexes have confidentiality set to true. 188 * 189 * @param value The value of the "confidentiality-enabled" property. 190 * @throws PropertyException 191 * If the new value is invalid. 192 */ 193 void setConfidentialityEnabled(Boolean value) throws PropertyException; 194 195 196 197 /** 198 * Gets the "entries-compressed" property. 199 * <p> 200 * Indicates whether the backend should attempt to compress entries 201 * before storing them in the database. 202 * <p> 203 * Note that this property applies only to the entries themselves 204 * and does not impact the index data. Further, the effectiveness of 205 * the compression is based on the type of data contained in the 206 * entry. 207 * 208 * @return Returns the value of the "entries-compressed" property. 209 */ 210 boolean isEntriesCompressed(); 211 212 213 214 /** 215 * Sets the "entries-compressed" property. 216 * <p> 217 * Indicates whether the backend should attempt to compress entries 218 * before storing them in the database. 219 * <p> 220 * Note that this property applies only to the entries themselves 221 * and does not impact the index data. Further, the effectiveness of 222 * the compression is based on the type of data contained in the 223 * entry. 224 * 225 * @param value The value of the "entries-compressed" property. 226 * @throws PropertyException 227 * If the new value is invalid. 228 */ 229 void setEntriesCompressed(Boolean value) throws PropertyException; 230 231 232 233 /** 234 * Gets the "import-offheap-memory-size" property. 235 * <p> 236 * Specifies the amount of off-heap memory dedicated to the online 237 * operation (import-ldif, rebuild-index). 238 * 239 * @return Returns the value of the "import-offheap-memory-size" property. 240 */ 241 Long getImportOffheapMemorySize(); 242 243 244 245 /** 246 * Sets the "import-offheap-memory-size" property. 247 * <p> 248 * Specifies the amount of off-heap memory dedicated to the online 249 * operation (import-ldif, rebuild-index). 250 * 251 * @param value The value of the "import-offheap-memory-size" property. 252 * @throws PropertyException 253 * If the new value is invalid. 254 */ 255 void setImportOffheapMemorySize(Long value) throws PropertyException; 256 257 258 259 /** 260 * Gets the "index-entry-limit" property. 261 * <p> 262 * Specifies the maximum number of entries that is allowed to match 263 * a given index key before that particular index key is no longer 264 * maintained. 265 * <p> 266 * This property is analogous to the ALL IDs threshold in the Sun 267 * Java System Directory Server. Note that this is the default limit 268 * for the backend, and it may be overridden on a per-attribute 269 * basis.A value of 0 means there is no limit. 270 * 271 * @return Returns the value of the "index-entry-limit" property. 272 */ 273 int getIndexEntryLimit(); 274 275 276 277 /** 278 * Sets the "index-entry-limit" property. 279 * <p> 280 * Specifies the maximum number of entries that is allowed to match 281 * a given index key before that particular index key is no longer 282 * maintained. 283 * <p> 284 * This property is analogous to the ALL IDs threshold in the Sun 285 * Java System Directory Server. Note that this is the default limit 286 * for the backend, and it may be overridden on a per-attribute 287 * basis.A value of 0 means there is no limit. 288 * 289 * @param value The value of the "index-entry-limit" property. 290 * @throws PropertyException 291 * If the new value is invalid. 292 */ 293 void setIndexEntryLimit(Integer value) throws PropertyException; 294 295 296 297 /** 298 * Gets the "index-filter-analyzer-enabled" property. 299 * <p> 300 * Indicates whether to gather statistical information about the 301 * search filters processed by the directory server while evaluating 302 * the usage of indexes. 303 * <p> 304 * Analyzing indexes requires gathering search filter usage patterns 305 * from user requests, especially for values as specified in the 306 * filters and subsequently looking the status of those values into 307 * the index files. When a search requests is processed, internal or 308 * user generated, a first phase uses indexes to find potential 309 * entries to be returned. Depending on the search filter, if the 310 * index of one of the specified attributes matches too many entries 311 * (exceeds the index entry limit), the search becomes non-indexed. 312 * In any case, all entries thus gathered (or the entire DIT) are 313 * matched against the filter for actually returning the search 314 * result. 315 * 316 * @return Returns the value of the "index-filter-analyzer-enabled" property. 317 */ 318 boolean isIndexFilterAnalyzerEnabled(); 319 320 321 322 /** 323 * Sets the "index-filter-analyzer-enabled" property. 324 * <p> 325 * Indicates whether to gather statistical information about the 326 * search filters processed by the directory server while evaluating 327 * the usage of indexes. 328 * <p> 329 * Analyzing indexes requires gathering search filter usage patterns 330 * from user requests, especially for values as specified in the 331 * filters and subsequently looking the status of those values into 332 * the index files. When a search requests is processed, internal or 333 * user generated, a first phase uses indexes to find potential 334 * entries to be returned. Depending on the search filter, if the 335 * index of one of the specified attributes matches too many entries 336 * (exceeds the index entry limit), the search becomes non-indexed. 337 * In any case, all entries thus gathered (or the entire DIT) are 338 * matched against the filter for actually returning the search 339 * result. 340 * 341 * @param value The value of the "index-filter-analyzer-enabled" property. 342 * @throws PropertyException 343 * If the new value is invalid. 344 */ 345 void setIndexFilterAnalyzerEnabled(Boolean value) throws PropertyException; 346 347 348 349 /** 350 * Gets the "index-filter-analyzer-max-filters" property. 351 * <p> 352 * The maximum number of search filter statistics to keep. 353 * <p> 354 * When the maximum number of search filter is reached, the least 355 * used one will be deleted. 356 * 357 * @return Returns the value of the "index-filter-analyzer-max-filters" property. 358 */ 359 int getIndexFilterAnalyzerMaxFilters(); 360 361 362 363 /** 364 * Sets the "index-filter-analyzer-max-filters" property. 365 * <p> 366 * The maximum number of search filter statistics to keep. 367 * <p> 368 * When the maximum number of search filter is reached, the least 369 * used one will be deleted. 370 * 371 * @param value The value of the "index-filter-analyzer-max-filters" property. 372 * @throws PropertyException 373 * If the new value is invalid. 374 */ 375 void setIndexFilterAnalyzerMaxFilters(Integer value) throws PropertyException; 376 377 378 379 /** 380 * Gets the "preload-time-limit" property. 381 * <p> 382 * Specifies the length of time that the backend is allowed to spend 383 * "pre-loading" data when it is initialized. 384 * <p> 385 * The pre-load process is used to pre-populate the database cache, 386 * so that it can be more quickly available when the server is 387 * processing requests. A duration of zero means there is no 388 * pre-load. 389 * 390 * @return Returns the value of the "preload-time-limit" property. 391 */ 392 long getPreloadTimeLimit(); 393 394 395 396 /** 397 * Sets the "preload-time-limit" property. 398 * <p> 399 * Specifies the length of time that the backend is allowed to spend 400 * "pre-loading" data when it is initialized. 401 * <p> 402 * The pre-load process is used to pre-populate the database cache, 403 * so that it can be more quickly available when the server is 404 * processing requests. A duration of zero means there is no 405 * pre-load. 406 * 407 * @param value The value of the "preload-time-limit" property. 408 * @throws PropertyException 409 * If the new value is invalid. 410 */ 411 void setPreloadTimeLimit(Long value) throws PropertyException; 412 413 414 415 /** 416 * Gets the "writability-mode" property. 417 * <p> 418 * Specifies the behavior that the backend should use when 419 * processing write operations. 420 * 421 * @return Returns the value of the "writability-mode" property. 422 */ 423 WritabilityMode getWritabilityMode(); 424 425 426 427 /** 428 * Sets the "writability-mode" property. 429 * <p> 430 * Specifies the behavior that the backend should use when 431 * processing write operations. 432 * 433 * @param value The value of the "writability-mode" property. 434 * @throws PropertyException 435 * If the new value is invalid. 436 */ 437 void setWritabilityMode(WritabilityMode value) throws PropertyException; 438 439 440 441 /** 442 * Lists the Backend Indexes. 443 * 444 * @return Returns an array containing the names of the Backend 445 * Indexes. 446 * @throws ConcurrentModificationException 447 * If this Pluggable Backend has been removed from the 448 * server by another client. 449 * @throws LdapException 450 * If any other error occurs. 451 */ 452 String[] listBackendIndexes() throws ConcurrentModificationException, 453 LdapException; 454 455 456 457 /** 458 * Gets the named Backend Index. 459 * 460 * @param name 461 * The name of the Backend Index to retrieve. 462 * @return Returns the named Backend Index. 463 * @throws DefinitionDecodingException 464 * If the named Backend Index was found but its type could 465 * not be determined. 466 * @throws ManagedObjectDecodingException 467 * If the named Backend Index was found but one or more of 468 * its properties could not be decoded. 469 * @throws ManagedObjectNotFoundException 470 * If the named Backend Index was not found on the server. 471 * @throws ConcurrentModificationException 472 * If this Pluggable Backend has been removed from the 473 * server by another client. 474 * @throws LdapException 475 * If any other error occurs. 476 */ 477 BackendIndexCfgClient getBackendIndex(String name) 478 throws DefinitionDecodingException, ManagedObjectDecodingException, 479 ManagedObjectNotFoundException, ConcurrentModificationException, 480 LdapException; 481 482 483 484 /** 485 * Creates a new Backend Index. The new Backend Index will initially 486 * not contain any property values (including mandatory properties). 487 * Once the Backend Index has been configured it can be added to the 488 * server using the {@link #commit()} method. 489 * 490 * @param <C> 491 * The type of the Backend Index being created. 492 * @param d 493 * The definition of the Backend Index to be created. 494 * @param name 495 * The name of the new Backend Index. 496 * @param exceptions 497 * An optional collection in which to place any {@link 498 * PropertyException}s that occurred whilst attempting to 499 * determine the default values of the Backend Index. This 500 * argument can be <code>null<code>. 501 * @return Returns a new Backend Index configuration instance. 502 * @throws IllegalManagedObjectNameException 503 * If the name of the new Backend Index is invalid. 504 */ 505 <C extends BackendIndexCfgClient> C createBackendIndex( 506 ManagedObjectDefinition<C, ? extends BackendIndexCfg> d, String name, Collection<PropertyException> exceptions) throws IllegalManagedObjectNameException; 507 508 509 510 /** 511 * Removes the named Backend Index. 512 * 513 * @param name 514 * The name of the Backend Index to remove. 515 * @throws ManagedObjectNotFoundException 516 * If the Backend Index does not exist. 517 * @throws OperationRejectedException 518 * If the server refuses to remove the Backend Index due 519 * to some server-side constraint which cannot be satisfied 520 * (for example, if it is referenced by another managed 521 * object). 522 * @throws ConcurrentModificationException 523 * If this Pluggable Backend has been removed from the 524 * server by another client. 525 * @throws LdapException 526 * If any other error occurs. 527 */ 528 void removeBackendIndex(String name) 529 throws ManagedObjectNotFoundException, OperationRejectedException, 530 ConcurrentModificationException, LdapException; 531 532 533 534 /** 535 * Lists the Backend VLV Indexes. 536 * 537 * @return Returns an array containing the names of the Backend VLV 538 * Indexes. 539 * @throws ConcurrentModificationException 540 * If this Pluggable Backend has been removed from the 541 * server by another client. 542 * @throws LdapException 543 * If any other error occurs. 544 */ 545 String[] listBackendVLVIndexes() throws ConcurrentModificationException, 546 LdapException; 547 548 549 550 /** 551 * Gets the named Backend VLV Index. 552 * 553 * @param name 554 * The name of the Backend VLV Index to retrieve. 555 * @return Returns the named Backend VLV Index. 556 * @throws DefinitionDecodingException 557 * If the named Backend VLV Index was found but its type 558 * could not be determined. 559 * @throws ManagedObjectDecodingException 560 * If the named Backend VLV Index was found but one or 561 * more of its properties could not be decoded. 562 * @throws ManagedObjectNotFoundException 563 * If the named Backend VLV Index was not found on the 564 * server. 565 * @throws ConcurrentModificationException 566 * If this Pluggable Backend has been removed from the 567 * server by another client. 568 * @throws LdapException 569 * If any other error occurs. 570 */ 571 BackendVLVIndexCfgClient getBackendVLVIndex(String name) 572 throws DefinitionDecodingException, ManagedObjectDecodingException, 573 ManagedObjectNotFoundException, ConcurrentModificationException, 574 LdapException; 575 576 577 578 /** 579 * Creates a new Backend VLV Index. The new Backend VLV Index will 580 * initially not contain any property values (including mandatory 581 * properties). Once the Backend VLV Index has been configured it can 582 * be added to the server using the {@link #commit()} method. 583 * 584 * @param <C> 585 * The type of the Backend VLV Index being created. 586 * @param d 587 * The definition of the Backend VLV Index to be created. 588 * @param name 589 * The name of the new Backend VLV Index. 590 * @param exceptions 591 * An optional collection in which to place any {@link 592 * PropertyException}s that occurred whilst attempting to 593 * determine the default values of the Backend VLV Index. 594 * This argument can be <code>null<code>. 595 * @return Returns a new Backend VLV Index configuration instance. 596 * @throws IllegalManagedObjectNameException 597 * If the name of the new Backend VLV Index is invalid. 598 */ 599 <C extends BackendVLVIndexCfgClient> C createBackendVLVIndex( 600 ManagedObjectDefinition<C, ? extends BackendVLVIndexCfg> d, String name, Collection<PropertyException> exceptions) throws IllegalManagedObjectNameException; 601 602 603 604 /** 605 * Removes the named Backend VLV Index. 606 * 607 * @param name 608 * The name of the Backend VLV Index to remove. 609 * @throws ManagedObjectNotFoundException 610 * If the Backend VLV Index does not exist. 611 * @throws OperationRejectedException 612 * If the server refuses to remove the Backend VLV Index 613 * due to some server-side constraint which cannot be 614 * satisfied (for example, if it is referenced by another 615 * managed object). 616 * @throws ConcurrentModificationException 617 * If this Pluggable Backend has been removed from the 618 * server by another client. 619 * @throws LdapException 620 * If any other error occurs. 621 */ 622 void removeBackendVLVIndex(String name) 623 throws ManagedObjectNotFoundException, OperationRejectedException, 624 ConcurrentModificationException, LdapException; 625 626}