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}