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-2012 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.LDAPSyncDestinationPluginConfig;
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.LDAPInterface;
043    import com.unboundid.ldap.sdk.Modification;
044    import com.unboundid.ldap.sdk.ResultCode;
045    import com.unboundid.ldap.sdk.SearchRequest;
046    import com.unboundid.util.Extensible;
047    import com.unboundid.util.ThreadSafety;
048    import com.unboundid.util.ThreadSafetyLevel;
049    import com.unboundid.util.args.ArgumentException;
050    import com.unboundid.util.args.ArgumentParser;
051    
052    
053    
054    /**
055     * This class defines an API that must be implemented by scripted extensions
056     * that perform processing on synchronization operations within an LDAP Sync
057     * Destination.  These extensions may be used to
058     * <ul>
059     *   <li>Filter out certain changes from being synchronized.</li>
060     *   <li>Change how an entry is fetched.</li>
061     *   <li>Change how an entry is modified or created.</li>
062     * </ul>
063     * <BR>
064     * A note on exception handling: in general subclasses should not
065     * catch LDAPExceptions that are thrown when using the provided
066     * LDAPInterface unless there are specific exceptions that are
067     * expected.  The Synchronization Server will handle
068     * LDAPExceptions in an appropriate way based on the specific
069     * cause of the exception.  For example, some errors will result
070     * in the SyncOperation being retried, and others will trigger
071     * fail over to a different server.
072     * <BR>
073     * <H2>Configuring Groovy-Scripted LDAP Sync Destination Plugins</H2>
074     * In order to configure a scripted LDAP sync destination plugin based on this
075     * API and written in the Groovy scripting language, use a command like:
076     * <PRE>
077     *      dsconfig create-sync-destination-plugin \
078     *           --plugin-name "<I>{plugin-name}</I>" \
079     *           --type groovy-scripted-ldap \
080     *           --set "script-class:<I>{class-name}</I>" \
081     *           --set "script-argument:<I>{name=value}</I>"
082     * </PRE>
083     * where "<I>{plugin-name}</I>" is the name to use for the LDAP sync destination
084     * plugin instance, "<I>{class-name}</I>" is the fully-qualified name of the
085     * Groovy class written using this API, and "<I>{name=value}</I>" represents
086     * name-value pairs for any arguments to provide to the LDAP sync destination
087     * plugin.  If multiple arguments should be provided to the LDAP sync
088     * destination plugin, then the
089     * "<CODE>--set script-argument:<I>{name=value}</I></CODE>" option should be
090     * provided multiple times.
091     *
092     * @see  com.unboundid.directory.sdk.sync.api.LDAPSyncDestinationPlugin
093     */
094    @Extensible()
095    @SynchronizationServerExtension(appliesToLocalContent=false,
096         appliesToSynchronizedContent=true)
097    @ThreadSafety(level= ThreadSafetyLevel.INTERFACE_THREADSAFE)
098    public abstract class ScriptedLDAPSyncDestinationPlugin
099           implements Reconfigurable<LDAPSyncDestinationPluginConfig>
100    {
101      /**
102       * Creates a new instance of this LDAP sync destination plugin.  All sync
103       * destination implementations must include a default constructor, but any
104       * initialization should generally be done in the
105       * {@code initializeLDAPSyncDestinationPlugin} method.
106       */
107      public ScriptedLDAPSyncDestinationPlugin()
108      {
109        // No implementation is required.
110      }
111    
112    
113    
114      /**
115       * {@inheritDoc}
116       */
117      public void defineConfigArguments(final ArgumentParser parser)
118             throws ArgumentException
119      {
120        // No arguments will be allowed by default.
121      }
122    
123    
124    
125      /**
126       * Initializes this LDAP sync destination plugin.
127       *
128       * @param  serverContext  A handle to the server context for the server in
129       *                        which this extension is running.
130       * @param  config         The general configuration for this LDAP sync
131       *                        destination plugin transformation.
132       * @param  parser         The argument parser which has been initialized from
133       *                        the configuration for this LDAP sync destination
134       *                        plugin.
135       *
136       * @throws  LDAPException  If a problem occurs while initializing this LDAP
137       *                         sync destination plugin.
138       */
139      public void initializeLDAPSyncDestinationPlugin(
140                       final SyncServerContext serverContext,
141                       final LDAPSyncDestinationPluginConfig config,
142                       final ArgumentParser parser)
143             throws LDAPException
144      {
145        // No initialization will be performed by default.
146      }
147    
148    
149    
150      /**
151       * Performs any cleanup which may be necessary when this LDAP sync destination
152       * plugin is to be taken out of service.
153       */
154      public void finalizeLDAPSyncDestinationPlugin()
155      {
156        // No implementation is required.
157      }
158    
159    
160    
161      /**
162       * {@inheritDoc}
163       */
164      public boolean isConfigurationAcceptable(
165                          final LDAPSyncDestinationPluginConfig config,
166                          final ArgumentParser parser,
167                          final List<String> unacceptableReasons)
168      {
169        // No extended validation will be performed.
170        return true;
171      }
172    
173    
174    
175      /**
176       * {@inheritDoc}
177       */
178      public ResultCode applyConfiguration(
179                             final LDAPSyncDestinationPluginConfig config,
180                             final ArgumentParser parser,
181                             final List<String> adminActionsRequired,
182                             final List<String> messages)
183      {
184        // By default, no configuration changes will be applied.
185        return ResultCode.SUCCESS;
186      }
187    
188    
189    
190      /**
191       * This method is called before a destination entry is fetched.  A
192       * connection to the destination server is provided along with the
193       * {@code SearchRequest} that will be sent to the server.  This method is
194       * overridden by plugins that need to have access to the search request
195       * before it is sent to the destination server.  This includes updating the
196       * search request as well as performing the search instead of the core server,
197       * including doing additional searches.  For plugins that need to manipulate
198       * the entries that the core LDAP Sync Destination code retrieves from the
199       * destination, implementing the {@link #postFetch} method is more natural.
200       * <p>
201       * This method might be called multiple times for a single synchronization
202       * operation, specifically when there are multiple search criteria or
203       * multiple base DNs defined for the Sync Destination.
204       *
205       * @param  destinationConnection  A connection to the destination server.
206       * @param  searchRequest          The search request that the LDAP Sync
207       *                                Destination will use to fetch the entry.
208       * @param  fetchedEntries         A list of entries that have been fetched.
209       *                                When the search criteria matches multiple
210       *                                entries, they should all be returned.  A
211       *                                plugin that wishes to implement the fetch
212       *                                should put the fetched entries here and
213       *                                return
214       *                                {@code PreStepResult#SKIP_CURRENT_STEP}.
215       * @param  operation              The synchronization operation for this
216       *                                change.
217       *
218       * @return  The result of the plugin processing.  Note:
219       *          {@code PreStepResult#SKIP_CURRENT_STEP} should only be returned
220       *          if this plugin takes responsibility for fully fetching the entry
221       *          according to the search request and for populating the
222       *          fetched entry list.
223       *
224       * @throws  LDAPException  In general subclasses should not catch
225       *                         LDAPExceptions that are thrown when
226       *                         using the LDAPInterface unless there
227       *                         are specific exceptions that are
228       *                         expected.  The Synchronization Server
229       *                         will handle LDAPExceptions in an
230       *                         appropriate way based on the specific
231       *                         cause of the exception.  For example,
232       *                         some errors will result in the
233       *                         SyncOperation being retried, and others
234       *                         will trigger fail over to a different
235       *                         server.  Plugins should only throw
236       *                         LDAPException for errors related to
237       *                         communication with the LDAP server.
238       *                         Use the return code to indicate other
239       *                         types of errors, which might require
240       *                         retry.
241       */
242      public PreStepResult preFetch(final LDAPInterface destinationConnection,
243                                    final SearchRequest searchRequest,
244                                    final List<Entry> fetchedEntries,
245                                    final SyncOperation operation)
246           throws LDAPException
247      {
248        return PreStepResult.CONTINUE;
249      }
250    
251    
252    
253      /**
254       * This method is called after an attempt to fetch a destination entry.  An
255       * connection to the destination server is provided along with the
256       * {@code SearchRequest} that was sent to the server.  This method is
257       * overridden by plugins that need to manipulate the search results that
258       * are returned to the Sync Pipe.  This can include filtering out certain
259       * entries, remove information from the entries, or adding additional
260       * information, possibly by doing a followup LDAP search.
261       * <p>
262       * This method might be called multiple times for a single synchronization
263       * operation, specifically when there are multiple search criteria or
264       * multiple base DNs defined for the Sync Destination.
265       * <p>
266       * This method will not be called if the search fails, for instance, if
267       * the base DN of the search does not exist.
268       *
269       * @param  destinationConnection  A connection to the destination server.
270       * @param  searchRequest          The search request that the LDAP Sync
271       *                                Destination used to fetch the entry.
272       * @param  fetchedEntries         A list of entries that have been fetched.
273       *                                When the search criteria matches multiple
274       *                                entries, they will all be returned.  Entries
275       *                                in this list can be edited directly, and the
276       *                                list can be edited as well.
277       * @param  operation              The synchronization operation for this
278       *                                change.
279       *
280       * @return  The result of the plugin processing.
281       *
282       * @throws  LDAPException  In general subclasses should not catch
283       *                         LDAPExceptions that are thrown when
284       *                         using the LDAPInterface unless there
285       *                         are specific exceptions that are
286       *                         expected.  The Synchronization Server
287       *                         will handle LDAPExceptions in an
288       *                         appropriate way based on the specific
289       *                         cause of the exception.  For example,
290       *                         some errors will result in the
291       *                         SyncOperation being retried, and others
292       *                         will trigger fail over to a different
293       *                         server.  Plugins should only throw
294       *                         LDAPException for errors related to
295       *                         communication with the LDAP server.
296       *                         Use the return code to indicate other
297       *                         types of errors, which might require
298       *                         retry.
299       */
300      public PostStepResult postFetch(final LDAPInterface destinationConnection,
301                                      final SearchRequest searchRequest,
302                                      final List<Entry> fetchedEntries,
303                                      final SyncOperation operation)
304           throws LDAPException
305      {
306        return PostStepResult.CONTINUE;
307      }
308    
309    
310    
311      /**
312       * This method is called before a destination entry is created.  A
313       * connection to the destination server is provided along with the
314       * {@code Entry} that will be sent to the server.  This method is
315       * overridden by plugins that need to alter the entry before it is created
316       * at the server.
317       *
318       * @param  destinationConnection  A connection to the destination server.
319       * @param  entryToCreate          The entry that will be created at the
320       *                                destination.  A plugin that wishes to
321       *                                create the entry should be sure to return
322       *                                {@code PreStepResult#SKIP_CURRENT_STEP}.
323       * @param  operation              The synchronization operation for this
324       *                                change.
325       *
326       * @return  The result of the plugin processing.
327       *
328       * @throws  LDAPException  In general subclasses should not catch
329       *                         LDAPExceptions that are thrown when
330       *                         using the LDAPInterface unless there
331       *                         are specific exceptions that are
332       *                         expected.  The Synchronization Server
333       *                         will handle LDAPExceptions in an
334       *                         appropriate way based on the specific
335       *                         cause of the exception.  For example,
336       *                         some errors will result in the
337       *                         SyncOperation being retried, and others
338       *                         will trigger fail over to a different
339       *                         server.  Plugins should only throw
340       *                         LDAPException for errors related to
341       *                         communication with the LDAP server.
342       *                         Use the return code to indicate other
343       *                         types of errors, which might require
344       *                         retry.
345       */
346      public PreStepResult preCreate(final LDAPInterface destinationConnection,
347                                     final Entry entryToCreate,
348                                     final SyncOperation operation)
349           throws LDAPException
350      {
351        return PreStepResult.CONTINUE;
352      }
353    
354    
355    
356      /**
357       * This method is called before a destination entry is modified.  A
358       * connection to the destination server is provided along with the
359       * {@code Entry} that will be sent to the server.  This method is
360       * overridden by plugins that need to perform some processing on an entry
361       * before it is modified.
362       *
363       * @param  destinationConnection  A connection to the destination server.
364       * @param  entryToModify          The entry that will be modified at the
365       *                                destination.  A plugin that wishes to
366       *                                modify the entry should be sure to return
367       *                                {@code PreStepResult#SKIP_CURRENT_STEP}.
368       * @param  modsToApply            A modifiable list of the modifications to
369       *                                apply at the server.
370       * @param  operation              The synchronization operation for this
371       *                                change.
372       *
373       * @return  The result of the plugin processing.
374       *
375       * @throws  LDAPException  In general subclasses should not catch
376       *                         LDAPExceptions that are thrown when
377       *                         using the LDAPInterface unless there
378       *                         are specific exceptions that are
379       *                         expected.  The Synchronization Server
380       *                         will handle LDAPExceptions in an
381       *                         appropriate way based on the specific
382       *                         cause of the exception.  For example,
383       *                         some errors will result in the
384       *                         SyncOperation being retried, and others
385       *                         will trigger fail over to a different
386       *                         server.  Plugins should only throw
387       *                         LDAPException for errors related to
388       *                         communication with the LDAP server.
389       *                         Use the return code to indicate other
390       *                         types of errors, which might require
391       *                         retry.
392       */
393      public PreStepResult preModify(final LDAPInterface destinationConnection,
394                                     final Entry entryToModify,
395                                     final List<Modification> modsToApply,
396                                     final SyncOperation operation)
397           throws LDAPException
398      {
399        return PreStepResult.CONTINUE;
400      }
401    
402    
403    
404      /**
405       * This method is called before a destination entry is deleted.  A
406       * connection to the destination server is provided along with the
407       * {@code Entry} that will be sent to the server.  This method is
408       * overridden by plugins that need to perform some processing on an entry
409       * before it is deleted.  A plugin could choose to mark an entry as disabled
410       * instead of deleting it for instance, or move the entry to a different
411       * part of the directory hierarchy.
412       *
413       * @param  destinationConnection  A connection to the destination server.
414       * @param  entryToDelete          The entry that will be deleted at the
415       *                                destination.  A plugin that wishes to
416       *                                delete the entry should be sure to return
417       *                                {@code PreStepResult#SKIP_CURRENT_STEP}.
418       * @param  operation              The synchronization operation for this
419       *                                change.
420       *
421       * @return  The result of the plugin processing.
422       *
423       * @throws  LDAPException  In general subclasses should not catch
424       *                         LDAPExceptions that are thrown when
425       *                         using the LDAPInterface unless there
426       *                         are specific exceptions that are
427       *                         expected.  The Synchronization Server
428       *                         will handle LDAPExceptions in an
429       *                         appropriate way based on the specific
430       *                         cause of the exception.  For example,
431       *                         some errors will result in the
432       *                         SyncOperation being retried, and others
433       *                         will trigger fail over to a different
434       *                         server.  Plugins should only throw
435       *                         LDAPException for errors related to
436       *                         communication with the LDAP server.
437       *                         Use the return code to indicate other
438       *                         types of errors, which might require
439       *                         retry.
440       */
441      public PreStepResult preDelete(final LDAPInterface destinationConnection,
442                                     final Entry entryToDelete,
443                                     final SyncOperation operation)
444           throws LDAPException
445      {
446        return PreStepResult.CONTINUE;
447      }
448    }