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