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    import java.util.concurrent.atomic.AtomicReference;
033    
034    import com.unboundid.directory.sdk.common.internal.Reconfigurable;
035    import com.unboundid.directory.sdk.sync.config.LDAPSyncSourcePluginConfig;
036    import com.unboundid.directory.sdk.sync.internal.SynchronizationServerExtension;
037    import com.unboundid.directory.sdk.sync.types.PostStepResult;
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.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     * that perform processing on synchronization operations within an LDAP Sync
055     * Source.  These extensions may be used to
056     * <ul>
057     *   <li>Filter out certain changes from being synchronized.</li>
058     *   <li>Change how an entry is fetched.</li>
059     * </ul>
060     * <BR>
061     * A note on exception handling: in general subclasses should not
062     * catch LDAPExceptions that are thrown when using the provided
063     * LDAPInterface unless there are specific exceptions that are
064     * expected.  The Synchronization Server will handle
065     * LDAPExceptions in an appropriate way based on the specific
066     * cause of the exception.  For example, some errors will result
067     * in the SyncOperation being retried, and others will trigger
068     * fail over to a different server.
069     * <BR>
070     * <H2>Configuring Groovy-Scripted LDAP Sync Source Plugins</H2>
071     * In order to configure a scripted LDAP sync source plugin based on this API
072     * and written in the Groovy scripting language, use a command like:
073     * <PRE>
074     *      dsconfig create-sync-source-plugin \
075     *           --plugin-name "<I>{plugin-name}</I>" \
076     *           --type groovy-scripted-ldap \
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 LDAP sync source
081     * plugin instance, "<I>{class-name}</I>" is the fully-qualified name of the
082     * Groovy class written using this API, and "<I>{name=value}</I>" represents
083     * name-value pairs for any arguments to provide to the LDAP sync source plugin.
084     * If multiple arguments should be provided to the LDAP sync source plugin, then
085     * the "<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.LDAPSyncSourcePlugin
089     */
090    @Extensible()
091    @SynchronizationServerExtension(appliesToLocalContent=false,
092         appliesToSynchronizedContent=true)
093    @ThreadSafety(level= ThreadSafetyLevel.INTERFACE_THREADSAFE)
094    public abstract class ScriptedLDAPSyncSourcePlugin
095           implements Reconfigurable<LDAPSyncSourcePluginConfig>
096    {
097      /**
098       * Creates a new instance of this LDAP sync source plugin.  All sync
099       * source implementations must include a default constructor, but any
100       * initialization should generally be done in the
101       * {@code initializeLDAPSyncSourcePlugin} method.
102       */
103      public ScriptedLDAPSyncSourcePlugin()
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 LDAP sync source 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 LDAP sync
127       *                        source plugin transformation.
128       * @param  parser         The argument parser which has been initialized from
129       *                        the configuration for this LDAP sync source plugin.
130       *
131       * @throws  LDAPException  If a problem occurs while initializing this LDAP
132       *                         sync source plugin.
133       */
134      public void initializeLDAPSyncSourcePlugin(
135                       final SyncServerContext serverContext,
136                       final LDAPSyncSourcePluginConfig 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 LDAP sync source
147       * plugin is to be taken out of service.
148       */
149      public void finalizeLDAPSyncSourcePlugin()
150      {
151        // No implementation is required.
152      }
153    
154    
155    
156      /**
157       * {@inheritDoc}
158       */
159      public boolean isConfigurationAcceptable(
160                          final LDAPSyncSourcePluginConfig config,
161                          final ArgumentParser parser,
162                          final List<String> unacceptableReasons)
163      {
164        // No extended validation will be performed.
165        return true;
166      }
167    
168    
169    
170      /**
171       * {@inheritDoc}
172       */
173      public ResultCode applyConfiguration(final LDAPSyncSourcePluginConfig config,
174                             final ArgumentParser parser,
175                             final List<String> adminActionsRequired,
176                             final List<String> messages)
177      {
178        // By default, no configuration changes will be applied.
179        return ResultCode.SUCCESS;
180      }
181    
182    
183    
184      /**
185       * This method is called after fetching a source entry.  A
186       * connection to the source server is provided.  This method is
187       * overridden by plugins that need to manipulate the search results that
188       * are returned to the Sync Pipe.  This can include filtering out certain
189       * entries, remove information from the entries, or adding additional
190       * information, possibly by doing a followup LDAP search.
191       *
192       * @param  sourceConnection       A connection to the source server.
193       * @param  fetchedEntryRef        A reference to the entry that was fetched.
194       *                                This entry can be edited in place, or the
195       *                                reference can be changed to point to a
196       *                                different entry that the plugin constructs.
197       * @param  operation              The synchronization operation for this
198       *                                change.
199       *
200       * @return  The result of the plugin processing.
201       *
202       * @throws  LDAPException  In general subclasses should not catch
203       *                         LDAPExceptions that are thrown when
204       *                         using the LDAPInterface unless there
205       *                         are specific exceptions that are
206       *                         expected.  The Synchronization Server
207       *                         will handle LDAPExceptions in an
208       *                         appropriate way based on the specific
209       *                         cause of the exception.  For example,
210       *                         some errors will result in the
211       *                         SyncOperation being retried, and others
212       *                         will trigger fail over to a different
213       *                         server.  Plugins should only throw
214       *                         LDAPException for errors related to
215       *                         communication with the LDAP server.
216       *                         Use the return code to indicate other
217       *                         types of errors, which might require
218       *                         retry.
219       */
220      public PostStepResult postFetch(final LDAPInterface sourceConnection,
221                                      final AtomicReference<Entry> fetchedEntryRef,
222                                      final SyncOperation operation)
223           throws LDAPException
224      {
225        return PostStepResult.CONTINUE;
226      }
227    }