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 * docs/licenses/cddl.txt
011 * or http://www.opensource.org/licenses/cddl1.php.
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 * docs/licenses/cddl.txt.  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 *      Portions Copyright 2010-2024 Ping Identity Corporation
026 */
027package com.unboundid.directory.sdk.ds.api;
028
029
030
031import java.util.Collections;
032import java.util.List;
033import java.util.Map;
034
035import com.unboundid.directory.sdk.common.internal.ExampleUsageProvider;
036import com.unboundid.directory.sdk.common.internal.Reconfigurable;
037import com.unboundid.directory.sdk.common.internal.UnboundIDExtension;
038import com.unboundid.directory.sdk.common.types.Entry;
039import com.unboundid.directory.sdk.ds.config.UncachedEntryCriteriaConfig;
040import com.unboundid.directory.sdk.ds.types.DirectoryServerContext;
041import com.unboundid.directory.sdk.ds.internal.DirectoryServerExtension;
042import com.unboundid.ldap.sdk.LDAPException;
043import com.unboundid.ldap.sdk.ResultCode;
044import com.unboundid.util.Extensible;
045import com.unboundid.util.ThreadSafety;
046import com.unboundid.util.ThreadSafetyLevel;
047import com.unboundid.util.args.ArgumentException;
048import com.unboundid.util.args.ArgumentParser;
049
050
051
052/**
053 * This class defines an API that must be implemented by extensions which have
054 * the ability to determine which entries should be stored in the
055 * uncached-id2entry database of a local DB backend, rather than in the id2entry
056 * database.  In environments with data sets too large to fit in available
057 * memory, this can help the server better use the memory it does have for
058 * entries that are more likely to be accessed.
059 * <BR>
060 * <H2>Configuring Uncached Entry Criteria</H2>
061 * In order to configure an uncached entry criteria object created using this
062 * API, use a command like:
063 * <PRE>
064 *      dsconfig create-uncached-entry-criteria \
065 *           --criteria-name "<I>{criteria-name}</I>" \
066 *           --type third-party \
067 *           --set enabled:true \
068 *           --set "extension-class:<I>{class-name}</I>" \
069 *           --set "extension-argument:<I>{name=value}</I>"
070 * </PRE>
071 * where "<I>{criteria-name}</I>" is the name to use for the uncached entry
072 * criteria instance, "<I>{class-name}</I>" is the fully-qualified name of the
073 * Java class that extends
074 * {@code com.unboundid.directory.sdk.ds.api.UncachedEntryCriteria},
075 * and "<I>{name=value}</I>" represents name-value pairs for any arguments to
076 * provide to the uncached entry criteria.  If multiple arguments
077 * should be provided to the criteria, then the
078 * "<CODE>--set extension-argument:<I>{name=value}</I></CODE>" option should be
079 * provided multiple times.
080 *
081 *
082 * @see com.unboundid.directory.sdk.ds.scripting.ScriptedUncachedEntryCriteria
083 */
084@Extensible()
085@DirectoryServerExtension()
086@ThreadSafety(level=ThreadSafetyLevel.INTERFACE_THREADSAFE)
087public abstract class UncachedEntryCriteria
088       implements UnboundIDExtension,
089                  Reconfigurable<UncachedEntryCriteriaConfig>,
090                  ExampleUsageProvider
091{
092  /**
093   * Creates a new instance of this uncached entry criteria.  All uncached entry
094   * criteria implementations must include a default constructor, but any
095   * initialization should generally be done in the
096   * {@code initializeUncachedEntryCriteria} method.
097   */
098  public UncachedEntryCriteria()
099  {
100    // No implementation is required.
101  }
102
103
104
105  /**
106   * {@inheritDoc}
107   */
108  public abstract String getExtensionName();
109
110
111
112  /**
113   * {@inheritDoc}
114   */
115  public abstract String[] getExtensionDescription();
116
117
118
119  /**
120   * {@inheritDoc}
121   */
122  public void defineConfigArguments(final ArgumentParser parser)
123         throws ArgumentException
124  {
125    // No arguments will be allowed by default.
126  }
127
128
129
130  /**
131   * Initializes this uncached entry criteria.
132   *
133   * @param  serverContext  A handle to the server context for the server in
134   *                        which this extension is running.
135   * @param  config         The general configuration for this uncached entry
136   *                        criteria.
137   * @param  parser         The argument parser which has been initialized from
138   *                        the configuration for this uncached entry criteria.
139   *
140   * @throws  LDAPException  If a problem occurs while initializing this
141   *                         uncached entry criteria.
142   */
143  public void initializeUncachedEntryCriteria(
144                   final DirectoryServerContext serverContext,
145                   final UncachedEntryCriteriaConfig config,
146                   final ArgumentParser parser)
147         throws LDAPException
148  {
149    // No initialization will be performed by default.
150  }
151
152
153
154  /**
155   * {@inheritDoc}
156   */
157  public boolean isConfigurationAcceptable(
158                      final UncachedEntryCriteriaConfig config,
159                      final ArgumentParser parser,
160                      final List<String> unacceptableReasons)
161  {
162    // No extended validation will be performed by default.
163    return true;
164  }
165
166
167
168  /**
169   * {@inheritDoc}
170   */
171  public ResultCode applyConfiguration(
172                         final UncachedEntryCriteriaConfig config,
173                         final ArgumentParser parser,
174                         final List<String> adminActionsRequired,
175                         final List<String> messages)
176  {
177    // By default, no configuration changes will be applied.  If there are any
178    // arguments, then add an admin action message indicating that the extension
179    // needs to be restarted for any changes to take effect.
180    if (! parser.getNamedArguments().isEmpty())
181    {
182      adminActionsRequired.add(
183           "No configuration change has actually been applied.  The new " +
184                "configuration will not take effect until this uncached " +
185                "entry criteria is disabled and re-enabled or until the " +
186                "server is restarted.");
187    }
188
189    return ResultCode.SUCCESS;
190  }
191
192
193
194  /**
195   * Performs any cleanup which may be necessary when this uncached entry
196   * criteria instance is to be taken out of service.
197   */
198  public void finalizeUncachedEntryCriteria()
199  {
200    // No implementation is required.
201  }
202
203
204
205  /**
206   * Indicates whether the provided entry should be written into the
207   * uncached-id2entry database rather than into id2entry.  This method may be
208   * used both for new entries (e.g., from add operations or LDIF imports) or
209   * existing entries (e.g., from modify, modify DN, or soft delete operations,
210   * or from re-encode processing).
211   *
212   * @param  previousEntry  A read-only representation of the entry as it
213   *                        existed before the update.  If the entry is
214   *                        unchanged or did not previously exist, then this
215   *                        will be the same as {@code updatedEntry}.
216   * @param  updatedEntry   A read-only representation of the entry as it will
217   *                        be written into either the id2entry or
218   *                        uncached-id2entry database.
219   *
220   * @return  {@code true} if the entry should be written into the
221   *          uncached-id2entry database, or {@code false} if it should be
222   *          written into the id2entry database.
223   */
224  public abstract boolean shouldBeUncached(final Entry previousEntry,
225                                           final Entry updatedEntry);
226
227
228
229  /**
230   * {@inheritDoc}
231   */
232  public Map<List<String>,String> getExamplesArgumentSets()
233  {
234    return Collections.emptyMap();
235  }
236}