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