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}