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 legal-notices/CDDLv1_0.txt 010 * or http://forgerock.org/license/CDDLv1.0.html. 011 * See the License for the specific language governing permissions 012 * and limitations under the License. 013 * 014 * When distributing Covered Code, include this CDDL HEADER in each 015 * file and include the License file at legal-notices/CDDLv1_0.txt. 016 * If applicable, add the following below this CDDL HEADER, with the 017 * fields enclosed by brackets "[]" replaced with your own identifying 018 * information: 019 * Portions Copyright [yyyy] [name of copyright owner] 020 * 021 * CDDL HEADER END 022 * 023 * 024 * Copyright 2008 Sun Microsystems, Inc. 025 */ 026package org.forgerock.opendj.server.config.client; 027 028 029 030import java.util.Collection; 031import org.forgerock.opendj.config.client.ConcurrentModificationException; 032import org.forgerock.opendj.config.client.IllegalManagedObjectNameException; 033import org.forgerock.opendj.config.client.ManagedObjectDecodingException; 034import org.forgerock.opendj.config.client.OperationRejectedException; 035import org.forgerock.opendj.config.DefinitionDecodingException; 036import org.forgerock.opendj.config.ManagedObjectDefinition; 037import org.forgerock.opendj.config.ManagedObjectNotFoundException; 038import org.forgerock.opendj.config.PropertyException; 039import org.forgerock.opendj.ldap.LdapException; 040import org.forgerock.opendj.server.config.meta.BackendCfgDefn.WritabilityMode; 041import org.forgerock.opendj.server.config.server.BackendIndexCfg; 042import org.forgerock.opendj.server.config.server.BackendVLVIndexCfg; 043import org.forgerock.opendj.server.config.server.PluggableBackendCfg; 044 045 046 047/** 048 * A client-side interface for reading and modifying Pluggable Backend 049 * settings. 050 * <p> 051 * A Pluggable Backend stores application data in a pluggable 052 * database. 053 */ 054public interface PluggableBackendCfgClient extends BackendCfgClient { 055 056 /** 057 * Get the configuration definition associated with this Pluggable Backend. 058 * 059 * @return Returns the configuration definition associated with this Pluggable Backend. 060 */ 061 ManagedObjectDefinition<? extends PluggableBackendCfgClient, ? extends PluggableBackendCfg> definition(); 062 063 064 065 /** 066 * Gets the "compact-encoding" property. 067 * <p> 068 * Indicates whether the backend should use a compact form when 069 * encoding entries by compressing the attribute descriptions and 070 * object class sets. 071 * <p> 072 * Note that this property applies only to the entries themselves 073 * and does not impact the index data. 074 * 075 * @return Returns the value of the "compact-encoding" property. 076 */ 077 boolean isCompactEncoding(); 078 079 080 081 /** 082 * Sets the "compact-encoding" property. 083 * <p> 084 * Indicates whether the backend should use a compact form when 085 * encoding entries by compressing the attribute descriptions and 086 * object class sets. 087 * <p> 088 * Note that this property applies only to the entries themselves 089 * and does not impact the index data. 090 * 091 * @param value The value of the "compact-encoding" property. 092 * @throws PropertyException 093 * If the new value is invalid. 094 */ 095 void setCompactEncoding(Boolean value) throws PropertyException; 096 097 098 099 /** 100 * Gets the "entries-compressed" property. 101 * <p> 102 * Indicates whether the backend should attempt to compress entries 103 * before storing them in the database. 104 * <p> 105 * Note that this property applies only to the entries themselves 106 * and does not impact the index data. Further, the effectiveness of 107 * the compression is based on the type of data contained in the 108 * entry. 109 * 110 * @return Returns the value of the "entries-compressed" property. 111 */ 112 boolean isEntriesCompressed(); 113 114 115 116 /** 117 * Sets the "entries-compressed" property. 118 * <p> 119 * Indicates whether the backend should attempt to compress entries 120 * before storing them in the database. 121 * <p> 122 * Note that this property applies only to the entries themselves 123 * and does not impact the index data. Further, the effectiveness of 124 * the compression is based on the type of data contained in the 125 * entry. 126 * 127 * @param value The value of the "entries-compressed" property. 128 * @throws PropertyException 129 * If the new value is invalid. 130 */ 131 void setEntriesCompressed(Boolean value) throws PropertyException; 132 133 134 135 /** 136 * Gets the "index-entry-limit" property. 137 * <p> 138 * Specifies the maximum number of entries that is allowed to match 139 * a given index key before that particular index key is no longer 140 * maintained. 141 * <p> 142 * This property is analogous to the ALL IDs threshold in the Sun 143 * Java System Directory Server. Note that this is the default limit 144 * for the backend, and it may be overridden on a per-attribute 145 * basis.A value of 0 means there is no limit. 146 * 147 * @return Returns the value of the "index-entry-limit" property. 148 */ 149 int getIndexEntryLimit(); 150 151 152 153 /** 154 * Sets the "index-entry-limit" property. 155 * <p> 156 * Specifies the maximum number of entries that is allowed to match 157 * a given index key before that particular index key is no longer 158 * maintained. 159 * <p> 160 * This property is analogous to the ALL IDs threshold in the Sun 161 * Java System Directory Server. Note that this is the default limit 162 * for the backend, and it may be overridden on a per-attribute 163 * basis.A value of 0 means there is no limit. 164 * 165 * @param value The value of the "index-entry-limit" property. 166 * @throws PropertyException 167 * If the new value is invalid. 168 */ 169 void setIndexEntryLimit(Integer value) throws PropertyException; 170 171 172 173 /** 174 * Gets the "index-filter-analyzer-enabled" property. 175 * <p> 176 * Indicates whether to gather statistical information about the 177 * search filters processed by the directory server while evaluating 178 * the usage of indexes. 179 * <p> 180 * Analyzing indexes requires gathering search filter usage patterns 181 * from user requests, especially for values as specified in the 182 * filters and subsequently looking the status of those values into 183 * the index files. When a search requests is processed, internal or 184 * user generated, a first phase uses indexes to find potential 185 * entries to be returned. Depending on the search filter, if the 186 * index of one of the specified attributes matches too many entries 187 * (exceeds the index entry limit), the search becomes non-indexed. 188 * In any case, all entries thus gathered (or the entire DIT) are 189 * matched against the filter for actually returning the search 190 * result. 191 * 192 * @return Returns the value of the "index-filter-analyzer-enabled" property. 193 */ 194 boolean isIndexFilterAnalyzerEnabled(); 195 196 197 198 /** 199 * Sets the "index-filter-analyzer-enabled" property. 200 * <p> 201 * Indicates whether to gather statistical information about the 202 * search filters processed by the directory server while evaluating 203 * the usage of indexes. 204 * <p> 205 * Analyzing indexes requires gathering search filter usage patterns 206 * from user requests, especially for values as specified in the 207 * filters and subsequently looking the status of those values into 208 * the index files. When a search requests is processed, internal or 209 * user generated, a first phase uses indexes to find potential 210 * entries to be returned. Depending on the search filter, if the 211 * index of one of the specified attributes matches too many entries 212 * (exceeds the index entry limit), the search becomes non-indexed. 213 * In any case, all entries thus gathered (or the entire DIT) are 214 * matched against the filter for actually returning the search 215 * result. 216 * 217 * @param value The value of the "index-filter-analyzer-enabled" property. 218 * @throws PropertyException 219 * If the new value is invalid. 220 */ 221 void setIndexFilterAnalyzerEnabled(Boolean value) throws PropertyException; 222 223 224 225 /** 226 * Gets the "index-filter-analyzer-max-filters" property. 227 * <p> 228 * The maximum number of search filter statistics to keep. 229 * <p> 230 * When the maximum number of search filter is reached, the least 231 * used one will be deleted. 232 * 233 * @return Returns the value of the "index-filter-analyzer-max-filters" property. 234 */ 235 int getIndexFilterAnalyzerMaxFilters(); 236 237 238 239 /** 240 * Sets the "index-filter-analyzer-max-filters" property. 241 * <p> 242 * The maximum number of search filter statistics to keep. 243 * <p> 244 * When the maximum number of search filter is reached, the least 245 * used one will be deleted. 246 * 247 * @param value The value of the "index-filter-analyzer-max-filters" property. 248 * @throws PropertyException 249 * If the new value is invalid. 250 */ 251 void setIndexFilterAnalyzerMaxFilters(Integer value) throws PropertyException; 252 253 254 255 /** 256 * Gets the "preload-time-limit" property. 257 * <p> 258 * Specifies the length of time that the backend is allowed to spend 259 * "pre-loading" data when it is initialized. 260 * <p> 261 * The pre-load process is used to pre-populate the database cache, 262 * so that it can be more quickly available when the server is 263 * processing requests. A duration of zero means there is no 264 * pre-load. 265 * 266 * @return Returns the value of the "preload-time-limit" property. 267 */ 268 long getPreloadTimeLimit(); 269 270 271 272 /** 273 * Sets the "preload-time-limit" property. 274 * <p> 275 * Specifies the length of time that the backend is allowed to spend 276 * "pre-loading" data when it is initialized. 277 * <p> 278 * The pre-load process is used to pre-populate the database cache, 279 * so that it can be more quickly available when the server is 280 * processing requests. A duration of zero means there is no 281 * pre-load. 282 * 283 * @param value The value of the "preload-time-limit" property. 284 * @throws PropertyException 285 * If the new value is invalid. 286 */ 287 void setPreloadTimeLimit(Long value) throws PropertyException; 288 289 290 291 /** 292 * Gets the "writability-mode" property. 293 * <p> 294 * Specifies the behavior that the backend should use when 295 * processing write operations. 296 * 297 * @return Returns the value of the "writability-mode" property. 298 */ 299 WritabilityMode getWritabilityMode(); 300 301 302 303 /** 304 * Sets the "writability-mode" property. 305 * <p> 306 * Specifies the behavior that the backend should use when 307 * processing write operations. 308 * 309 * @param value The value of the "writability-mode" property. 310 * @throws PropertyException 311 * If the new value is invalid. 312 */ 313 void setWritabilityMode(WritabilityMode value) throws PropertyException; 314 315 316 317 /** 318 * Lists the Backend Indexes. 319 * 320 * @return Returns an array containing the names of the Backend 321 * Indexes. 322 * @throws ConcurrentModificationException 323 * If this Pluggable Backend has been removed from the 324 * server by another client. 325 * @throws LdapException 326 * If any other error occurs. 327 */ 328 String[] listBackendIndexes() throws ConcurrentModificationException, 329 LdapException; 330 331 332 333 /** 334 * Gets the named Backend Index. 335 * 336 * @param name 337 * The name of the Backend Index to retrieve. 338 * @return Returns the named Backend Index. 339 * @throws DefinitionDecodingException 340 * If the named Backend Index was found but its type could 341 * not be determined. 342 * @throws ManagedObjectDecodingException 343 * If the named Backend Index was found but one or more of 344 * its properties could not be decoded. 345 * @throws ManagedObjectNotFoundException 346 * If the named Backend Index was not found on the server. 347 * @throws ConcurrentModificationException 348 * If this Pluggable Backend has been removed from the 349 * server by another client. 350 * @throws LdapException 351 * If any other error occurs. 352 */ 353 BackendIndexCfgClient getBackendIndex(String name) 354 throws DefinitionDecodingException, ManagedObjectDecodingException, 355 ManagedObjectNotFoundException, ConcurrentModificationException, 356 LdapException; 357 358 359 360 /** 361 * Creates a new Backend Index. The new Backend Index will initially 362 * not contain any property values (including mandatory properties). 363 * Once the Backend Index has been configured it can be added to the 364 * server using the {@link #commit()} method. 365 * 366 * @param <C> 367 * The type of the Backend Index being created. 368 * @param d 369 * The definition of the Backend Index to be created. 370 * @param name 371 * The name of the new Backend Index. 372 * @param exceptions 373 * An optional collection in which to place any {@link 374 * PropertyException}s that occurred whilst attempting to 375 * determine the default values of the Backend Index. This 376 * argument can be <code>null<code>. 377 * @return Returns a new Backend Index configuration instance. 378 * @throws IllegalManagedObjectNameException 379 * If the name of the new Backend Index is invalid. 380 */ 381 <C extends BackendIndexCfgClient> C createBackendIndex( 382 ManagedObjectDefinition<C, ? extends BackendIndexCfg> d, String name, Collection<PropertyException> exceptions) throws IllegalManagedObjectNameException; 383 384 385 386 /** 387 * Removes the named Backend Index. 388 * 389 * @param name 390 * The name of the Backend Index to remove. 391 * @throws ManagedObjectNotFoundException 392 * If the Backend Index does not exist. 393 * @throws OperationRejectedException 394 * If the server refuses to remove the Backend Index due 395 * to some server-side constraint which cannot be satisfied 396 * (for example, if it is referenced by another managed 397 * object). 398 * @throws ConcurrentModificationException 399 * If this Pluggable Backend has been removed from the 400 * server by another client. 401 * @throws LdapException 402 * If any other error occurs. 403 */ 404 void removeBackendIndex(String name) 405 throws ManagedObjectNotFoundException, OperationRejectedException, 406 ConcurrentModificationException, LdapException; 407 408 409 410 /** 411 * Lists the Backend VLV Indexes. 412 * 413 * @return Returns an array containing the names of the Backend VLV 414 * Indexes. 415 * @throws ConcurrentModificationException 416 * If this Pluggable Backend has been removed from the 417 * server by another client. 418 * @throws LdapException 419 * If any other error occurs. 420 */ 421 String[] listBackendVLVIndexes() throws ConcurrentModificationException, 422 LdapException; 423 424 425 426 /** 427 * Gets the named Backend VLV Index. 428 * 429 * @param name 430 * The name of the Backend VLV Index to retrieve. 431 * @return Returns the named Backend VLV Index. 432 * @throws DefinitionDecodingException 433 * If the named Backend VLV Index was found but its type 434 * could not be determined. 435 * @throws ManagedObjectDecodingException 436 * If the named Backend VLV Index was found but one or 437 * more of its properties could not be decoded. 438 * @throws ManagedObjectNotFoundException 439 * If the named Backend VLV Index was not found on the 440 * server. 441 * @throws ConcurrentModificationException 442 * If this Pluggable Backend has been removed from the 443 * server by another client. 444 * @throws LdapException 445 * If any other error occurs. 446 */ 447 BackendVLVIndexCfgClient getBackendVLVIndex(String name) 448 throws DefinitionDecodingException, ManagedObjectDecodingException, 449 ManagedObjectNotFoundException, ConcurrentModificationException, 450 LdapException; 451 452 453 454 /** 455 * Creates a new Backend VLV Index. The new Backend VLV Index will 456 * initially not contain any property values (including mandatory 457 * properties). Once the Backend VLV Index has been configured it can 458 * be added to the server using the {@link #commit()} method. 459 * 460 * @param <C> 461 * The type of the Backend VLV Index being created. 462 * @param d 463 * The definition of the Backend VLV Index to be created. 464 * @param name 465 * The name of the new Backend VLV Index. 466 * @param exceptions 467 * An optional collection in which to place any {@link 468 * PropertyException}s that occurred whilst attempting to 469 * determine the default values of the Backend VLV Index. 470 * This argument can be <code>null<code>. 471 * @return Returns a new Backend VLV Index configuration instance. 472 * @throws IllegalManagedObjectNameException 473 * If the name of the new Backend VLV Index is invalid. 474 */ 475 <C extends BackendVLVIndexCfgClient> C createBackendVLVIndex( 476 ManagedObjectDefinition<C, ? extends BackendVLVIndexCfg> d, String name, Collection<PropertyException> exceptions) throws IllegalManagedObjectNameException; 477 478 479 480 /** 481 * Removes the named Backend VLV Index. 482 * 483 * @param name 484 * The name of the Backend VLV Index to remove. 485 * @throws ManagedObjectNotFoundException 486 * If the Backend VLV Index does not exist. 487 * @throws OperationRejectedException 488 * If the server refuses to remove the Backend VLV Index 489 * due to some server-side constraint which cannot be 490 * satisfied (for example, if it is referenced by another 491 * managed object). 492 * @throws ConcurrentModificationException 493 * If this Pluggable Backend has been removed from the 494 * server by another client. 495 * @throws LdapException 496 * If any other error occurs. 497 */ 498 void removeBackendVLVIndex(String name) 499 throws ManagedObjectNotFoundException, OperationRejectedException, 500 ConcurrentModificationException, LdapException; 501 502}