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.OperationContext;
039 import com.unboundid.directory.sdk.common.types.Entry;
040 import com.unboundid.directory.sdk.ds.config.VirtualAttributeProviderConfig;
041 import com.unboundid.directory.sdk.ds.internal.DirectoryServerExtension;
042 import com.unboundid.directory.sdk.ds.scripting.
043 ScriptedVirtualAttributeProvider;
044 import com.unboundid.directory.sdk.ds.types.DirectoryServerContext;
045 import com.unboundid.directory.sdk.proxy.internal.DirectoryProxyServerExtension;
046 import com.unboundid.directory.sdk.sync.internal.SynchronizationServerExtension;
047 import com.unboundid.ldap.sdk.Attribute;
048 import com.unboundid.ldap.sdk.LDAPException;
049 import com.unboundid.ldap.sdk.ResultCode;
050 import com.unboundid.util.Extensible;
051 import com.unboundid.util.ThreadSafety;
052 import com.unboundid.util.ThreadSafetyLevel;
053 import com.unboundid.util.args.ArgumentException;
054 import com.unboundid.util.args.ArgumentParser;
055
056
057
058 /**
059 * This class defines an API that must be implemented by extensions which
060 * construct attribute values which may be included in entries instead of or
061 * in addition to real values which are actually stored in the backend. The
062 * other attributes in the entry will be available for use in the process of
063 * generating the entry, and internal or external operations may also be
064 * performed if the generated values should incorporate data from other
065 * locations.
066 * <BR><BR>
067 * Each virtual attribute provider may be configured to indicate whether the
068 * associated virtual attribute should be included in a given entry. This
069 * criteria may include the entry's location in the DIT, whether it matches a
070 * given filter, whether it is a member of a specified group, and whether the
071 * requesting client has been assigned a given client connection policy. This
072 * is handled automatically by the server, so individual virtual attribute
073 * provider implementations do not need to attempt to perform that filtering on
074 * their own. However, they may perform additional processing if desired to
075 * further narrow the set of entries for which the virtual attribute should be
076 * generated.
077 * <BR><BR>
078 * In addition, virtual attribute providers may be configured to indicate the
079 * behavior that should be exhibited in the event that the target attribute
080 * already exists in the entry with one or more real values. In this case, the
081 * real values may be used instead of generating virtual values, the virtual
082 * values may be used in place of the real values, or both the real and virtual
083 * values may be merged and presented together. This work is also automatically
084 * performed by the server, so virtual attribute providers do not need to do any
085 * processing to determine whether to generate a value based on whether the
086 * target attribute already exists in the entry.
087 * <BR><BR>
088 * The server supports multiple virtual attribute providers targeting the same
089 * attribute applying to the same entry. Evaluation order and value selection is
090 * determined by the server based on configuration of the virtual attribute
091 * providers.
092 * <BR>
093 * <H2>Configuring Virtual Attribute Providers</H2>
094 * In order to configure a virtual attribute provider created using this API,
095 * use a command like:
096 * <PRE>
097 * dsconfig create-virtual-attribute \
098 * --name "<I>{name}</I>" \
099 * --type third-party \
100 * --set enabled:true \
101 * --set attribute-type:{attribute} \
102 * --set "extension-class:<I>{class-name}</I>" \
103 * --set "extension-argument:<I>{name=value}</I>"
104 * </PRE>
105 * where "<I>{name}</I>" is the name to use for the virtual attribute provider
106 * instance, "<I>{attribute}</I>" is the name of the attribute for which the
107 * virtual attribute provider should be used to generate values,
108 * "<I>{class-name}</I>" is the fully-qualified name of the Java class that
109 * extends {@code com.unboundid.directory.sdk.ds.api.VirtualAttributeProvider},
110 * and "<I>{name=value}</I>" represents name-value pairs for any arguments to
111 * provide to the virtual attribute provider. If multiple arguments should be
112 * provided to the virtual attribute provider, then the
113 * "<CODE>--set extension-argument:<I>{name=value}</I></CODE>" option should be
114 * provided multiple times.
115 *
116 * @see ScriptedVirtualAttributeProvider
117 */
118 @Extensible()
119 @DirectoryServerExtension()
120 @DirectoryProxyServerExtension(appliesToLocalContent=true,
121 appliesToRemoteContent=false)
122 @SynchronizationServerExtension(appliesToLocalContent=true,
123 appliesToSynchronizedContent=false)
124 @ThreadSafety(level=ThreadSafetyLevel.INTERFACE_THREADSAFE)
125 public abstract class VirtualAttributeProvider
126 implements UnboundIDExtension,
127 Reconfigurable<VirtualAttributeProviderConfig>,
128 ExampleUsageProvider
129 {
130 /**
131 * Creates a new instance of this virtual attribute provider. All virtual
132 * attribute provider implementations must include a default constructor, but
133 * any initialization should generally be done in the
134 * {@code initializeVirtualAttributeProvider} method.
135 */
136 public VirtualAttributeProvider()
137 {
138 // No implementation is required. However, we need to reference the
139 // scripted virtual attribute provider so that checkstyle is satisfied with
140 // the import.
141 final ScriptedVirtualAttributeProvider scriptedProvider = null;
142 }
143
144
145
146 /**
147 * {@inheritDoc}
148 */
149 public abstract String getExtensionName();
150
151
152
153 /**
154 * {@inheritDoc}
155 */
156 public abstract String[] getExtensionDescription();
157
158
159
160 /**
161 * {@inheritDoc}
162 */
163 public void defineConfigArguments(final ArgumentParser parser)
164 throws ArgumentException
165 {
166 // No arguments will be allowed by default.
167 }
168
169
170
171 /**
172 * Initializes this virtual attribute provider.
173 *
174 * @param serverContext A handle to the server context for the server in
175 * which this extension is running.
176 * @param config The general configuration for this virtual attribute
177 * provider.
178 * @param parser The argument parser which has been initialized from
179 * the configuration for this virtual attribute
180 * provider.
181 *
182 * @throws LDAPException If a problem occurs while initializing this virtual
183 * attribute provider.
184 */
185 public void initializeVirtualAttributeProvider(
186 final DirectoryServerContext serverContext,
187 final VirtualAttributeProviderConfig config,
188 final ArgumentParser parser)
189 throws LDAPException
190 {
191 // No initialization will be performed by default.
192 }
193
194
195
196 /**
197 * {@inheritDoc}
198 */
199 public boolean isConfigurationAcceptable(
200 final VirtualAttributeProviderConfig config,
201 final ArgumentParser parser,
202 final List<String> unacceptableReasons)
203 {
204 // No extended validation will be performed by default.
205 return true;
206 }
207
208
209
210 /**
211 * {@inheritDoc}
212 */
213 public ResultCode applyConfiguration(
214 final VirtualAttributeProviderConfig config,
215 final ArgumentParser parser,
216 final List<String> adminActionsRequired,
217 final List<String> messages)
218 {
219 // By default, no configuration changes will be applied. If there are any
220 // arguments, then add an admin action message indicating that the extension
221 // needs to be restarted for any changes to take effect.
222 if (! parser.getNamedArguments().isEmpty())
223 {
224 adminActionsRequired.add(
225 "No configuration change has actually been applied. The new " +
226 "configuration will not take effect until this virtual " +
227 "attribute provider is disabled and re-enabled or until the " +
228 "server is restarted.");
229 }
230
231 return ResultCode.SUCCESS;
232 }
233
234
235
236 /**
237 * Performs any cleanup which may be necessary when this virtual attribute
238 * provider is to be taken out of service.
239 */
240 public void finalizeVirtualAttributeProvider()
241 {
242 // No implementation is required.
243 }
244
245
246
247 /**
248 * Indicates whether the server may cache values generated by this virtual
249 * attribute provider for reuse against the same entry in the course of
250 * processing the same operation.
251 *
252 * @return {@code true} if the server may cache the value generated by this
253 * virtual attribute provider for reuse with the same entry in the
254 * same operation, or {@code false} if not.
255 */
256 public boolean mayCacheInOperation()
257 {
258 return false;
259 }
260
261
262
263 /**
264 * Indicates whether this virtual attribute provider may generate attributes
265 * with multiple values.
266 *
267 * @return {@code true} if this virtual attribute provider may generate
268 * attributes with multiple values, or {@code false} if it will only
269 * generate single-valued attributes.
270 */
271 public abstract boolean isMultiValued();
272
273
274
275 /**
276 * Generates an attribute for inclusion in the provided entry.
277 *
278 * @param operationContext The operation context for the operation in
279 * progress, if any. It may be {@code null} if no
280 * operation is available.
281 * @param entry The entry for which the attribute is to be
282 * generated.
283 * @param attributeName The name of the attribute to be generated.
284 *
285 * @return The generated attribute, or {@code null} if no attribute should be
286 * generated.
287 */
288 public abstract Attribute generateAttribute(
289 final OperationContext operationContext,
290 final Entry entry, final String attributeName);
291
292
293
294 /**
295 * {@inheritDoc}
296 */
297 public Map<List<String>,String> getExamplesArgumentSets()
298 {
299 return Collections.emptyMap();
300 }
301 }