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.sync.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.sync.config.SyncPipePluginConfig; 035 import com.unboundid.directory.sdk.sync.internal.SynchronizationServerExtension; 036 import com.unboundid.directory.sdk.sync.types.PostStepResult; 037 import com.unboundid.directory.sdk.sync.types.PreStepResult; 038 import com.unboundid.directory.sdk.sync.types.SyncOperation; 039 import com.unboundid.directory.sdk.sync.types.SyncServerContext; 040 import com.unboundid.ldap.sdk.Entry; 041 import com.unboundid.ldap.sdk.LDAPException; 042 import com.unboundid.ldap.sdk.ResultCode; 043 import com.unboundid.util.Extensible; 044 import com.unboundid.util.ThreadSafety; 045 import com.unboundid.util.ThreadSafetyLevel; 046 import com.unboundid.util.args.ArgumentException; 047 import com.unboundid.util.args.ArgumentParser; 048 049 050 051 /** 052 * This class defines an API that must be implemented by scripted extensions 053 * that perform processing on synchronization operations within the Sync Pipe. 054 * These extensions may be used to 055 * <ul> 056 * <li>Filter out certain changes from being synchronized.</li> 057 * <li>Add and remove attributes that should be synchronized with the 058 * destination independent of whether they changed at the source or 059 * not.</li> 060 * <li>Manipulate the changes that are synchronized to ignore certain 061 * modified attributes or change the representation of modified 062 * attributes.</li> 063 * <li>Skip certain steps in Sync Pipe processing, e.g. attribute 064 * and DN mapping.</li> 065 * </ul> 066 * Most plugins will need to override the {@code postMapping} method but not 067 * the {@code preMapping} method. These extensions do not have access to the 068 * Sync Source or Sync Destination. 069 * <BR> 070 * <H2>Configuring Groovy-Scripted Sync Pipe Plugins</H2> 071 * In order to configure a scripted sync pipe plugin based on this API and 072 * written in the Groovy scripting language, use a command like: 073 * <PRE> 074 * dsconfig create-sync-pipe-plugin \ 075 * --plugin-name "<I>{plugin-name}</I>" \ 076 * --type groovy-scripted \ 077 * --set "script-class:<I>{class-name}</I>" \ 078 * --set "script-argument:<I>{name=value}</I>" 079 * </PRE> 080 * where "<I>{plugin-name}</I>" is the name to use for the sync pipe plugin 081 * instance, "<I>{class-name}</I>" is the fully-qualified name of the Groovy 082 * class written using this API, and "<I>{name=value}</I>" represents name-value 083 * pairs for any arguments to provide to the sync pipe plugin. If multiple 084 * arguments should be provided to the sync pipe plugin, then the 085 * "<CODE>--set script-argument:<I>{name=value}</I></CODE>" option should be 086 * provided multiple times. 087 * 088 * @see com.unboundid.directory.sdk.sync.api.SyncPipePlugin 089 */ 090 @Extensible() 091 @SynchronizationServerExtension(appliesToLocalContent=false, 092 appliesToSynchronizedContent=true) 093 @ThreadSafety(level= ThreadSafetyLevel.INTERFACE_THREADSAFE) 094 public abstract class ScriptedSyncPipePlugin 095 implements Reconfigurable<SyncPipePluginConfig> 096 { 097 /** 098 * Creates a new instance of this sync pipe plugin. All sync pipe 099 * plugin implementations must include a default constructor, but any 100 * initialization should generally be done in the 101 * {@code initializeSyncPipePlugin} method. 102 */ 103 public ScriptedSyncPipePlugin() 104 { 105 // No implementation is required. 106 } 107 108 109 110 /** 111 * {@inheritDoc} 112 */ 113 public void defineConfigArguments(final ArgumentParser parser) 114 throws ArgumentException 115 { 116 // No arguments will be allowed by default. 117 } 118 119 120 121 /** 122 * Initializes this sync pipe plugin. 123 * 124 * @param serverContext A handle to the server context for the server in 125 * which this extension is running. 126 * @param config The general configuration for this sync pipe plugin 127 * transformation. 128 * @param parser The argument parser which has been initialized from 129 * the configuration for this sync pipe plugin. 130 * 131 * @throws LDAPException If a problem occurs while initializing this sync 132 * pipe plugin. 133 */ 134 public void initializeSyncPipePlugin( 135 final SyncServerContext serverContext, 136 final SyncPipePluginConfig config, 137 final ArgumentParser parser) 138 throws LDAPException 139 { 140 // No initialization will be performed by default. 141 } 142 143 144 145 /** 146 * Performs any cleanup which may be necessary when this sync pipe plugin 147 * is to be taken out of service. 148 */ 149 public void finalizeSyncPipePlugin() 150 { 151 // No implementation is required. 152 } 153 154 155 156 /** 157 * {@inheritDoc} 158 */ 159 public boolean isConfigurationAcceptable(final SyncPipePluginConfig config, 160 final ArgumentParser parser, 161 final List<String> unacceptableReasons) 162 { 163 // No extended validation will be performed. 164 return true; 165 } 166 167 168 169 /** 170 * {@inheritDoc} 171 */ 172 public ResultCode applyConfiguration(final SyncPipePluginConfig 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. 178 return ResultCode.SUCCESS; 179 } 180 181 182 183 /** 184 * This method is called immediately before the attributes and DN in 185 * the source entry are mapped into the equivalent destination entry. 186 * This equivalent destination entry is then compared to the actual 187 * destination entry to determine which of the modified attributes need 188 * to be updated. 189 * <p> 190 * This method is typically used to either filter out certain changes 191 * (by returning {@link PreStepResult#ABORT_OPERATION}) or to manipulate the 192 * source entry before it is converted into an equivalent destination entry. 193 * Attributes that will not otherwise be affected by attribute mapping 194 * can be set in {@code equivalentDestinationEntry}. Although, due to the 195 * possibility of being overwritten in the mapping phase, manipulation of 196 * {@code equivalentDestinationEntry} is typically reserved for the 197 * {@link #postMapping} method. 198 * <p> 199 * The set of source attributes that should be synchronized at the destination 200 * can be manipulated by calling 201 * {@link SyncOperation#addModifiedSourceAttribute} and 202 * {@link SyncOperation#removeModifiedSourceAttribute} on 203 * {@code operation}. 204 * <p> 205 * Additional steps must be taken if this plugin adds destination attributes 206 * in {@code equivalentDestinationEntry} that need to be modified at the 207 * destination. For operations with an operation type of 208 * {@link com.unboundid.directory.sdk.sync.types.SyncOperationType#CREATE}, 209 * any updates made to 210 * {@code equivalentDestinationEntry} will be included in the 211 * entry created at the destination. However, for operations with an 212 * operation type of 213 * {@link com.unboundid.directory.sdk.sync.types.SyncOperationType#MODIFY}, 214 * destination attributes 215 * added by this plugin that need to be modified must be updated 216 * explicitly by calling 217 * {@link SyncOperation#addModifiedDestinationAttribute}. 218 * <p> 219 * With the exception of aborting changes or skipping the mapping step 220 * completely, most plugins will not need to override this method since 221 * the {@link #postMapping} method has access to the fully mapped destination 222 * entry. 223 * 224 * @param sourceEntry The entry that was fetched from the 225 * source. 226 * @param equivalentDestinationEntry The destination entry that is 227 * equivalent to the source. This entry 228 * will be empty except for any 229 * modifications that have been performed 230 * by other sync pipe plugins. 231 * @param operation The operation that is being 232 * synchronized. 233 * 234 * @return The result of the plugin processing. Note: 235 * {@code PreStepResult#SKIP_CURRENT_STEP} should only be returned 236 * if this plugin takes responsibility for fully constructing the 237 * equivalent destination entry. 238 */ 239 public PreStepResult preMapping(final Entry sourceEntry, 240 final Entry equivalentDestinationEntry, 241 final SyncOperation operation) 242 { 243 return PreStepResult.CONTINUE; 244 } 245 246 247 248 /** 249 * This method is called immediately after the attributes and DN in 250 * the source entry are mapped into the equivalent destination entry. 251 * Once this mapping is complete, this equivalent destination entry is then 252 * compared to the actual destination entry to determine which of the modified 253 * attributes need to be updated. 254 * <p> 255 * This method is typically used to manipulate the equivalent destination 256 * entry before these necessary changes are calculated. It can also be used 257 * to filter out certain changes (by returning 258 * {@link PostStepResult#ABORT_OPERATION}), but this is typically done in 259 * the {@link #preMapping method}. 260 * <p> 261 * The set of source attributes that should be synchronized at the destination 262 * can be manipulated by calling 263 * {@link SyncOperation#addModifiedSourceAttribute} and 264 * {@link SyncOperation#removeModifiedSourceAttribute} on 265 * {@code operation}. 266 * <p> 267 * Additional steps must be taken if this plugin adds destination attributes 268 * in {@code equivalentDestinationEntry} that need to be modified at the 269 * destination. For operations with an operation type of 270 * {@link com.unboundid.directory.sdk.sync.types.SyncOperationType#CREATE}, 271 * any updates made to 272 * {@code equivalentDestinationEntry} will be included in the 273 * entry created at the destination. However, for operations with an 274 * operation type of 275 * {@link com.unboundid.directory.sdk.sync.types.SyncOperationType#MODIFY}, 276 * destination attributes 277 * added by this plugin that need to be modified must be updated 278 * explicitly by calling 279 * {@link SyncOperation#addModifiedDestinationAttribute}. 280 * <p> 281 * With the exception of aborting changes or skipping the mapping step 282 * completely, most plugins will override this method instead of 283 * {@link #preMapping} because this method has access to the fully mapped 284 * destination entry. 285 * 286 * @param sourceEntry The entry that was fetched from the 287 * source. 288 * @param equivalentDestinationEntry The destination entry that is 289 * equivalent to the source. This entry 290 * will include all attributes mapped 291 * from the source entry. 292 * @param operation The operation that is being 293 * synchronized. 294 * 295 * @return The result of the plugin processing. 296 */ 297 public PostStepResult postMapping(final Entry sourceEntry, 298 final Entry equivalentDestinationEntry, 299 final SyncOperation operation) 300 { 301 return PostStepResult.CONTINUE; 302 } 303 }