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