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 * Copyright 2010-2013 UnboundID Corp.
026 */
027 package com.unboundid.directory.sdk.ds.api;
028
029
030
031 import java.util.Collections;
032 import java.util.List;
033 import java.util.Map;
034
035 import com.unboundid.directory.sdk.common.internal.ExampleUsageProvider;
036 import com.unboundid.directory.sdk.common.internal.Reconfigurable;
037 import com.unboundid.directory.sdk.common.internal.UnboundIDExtension;
038 import com.unboundid.directory.sdk.common.types.Entry;
039 import com.unboundid.directory.sdk.ds.config.UncachedEntryCriteriaConfig;
040 import com.unboundid.directory.sdk.ds.types.DirectoryServerContext;
041 import com.unboundid.directory.sdk.ds.internal.DirectoryServerExtension;
042 import com.unboundid.ldap.sdk.LDAPException;
043 import com.unboundid.ldap.sdk.ResultCode;
044 import com.unboundid.util.Extensible;
045 import com.unboundid.util.ThreadSafety;
046 import com.unboundid.util.ThreadSafetyLevel;
047 import com.unboundid.util.args.ArgumentException;
048 import 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>{handler-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)
087 public 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 }