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