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 legal-notices/CDDLv1_0.txt
010 * or http://forgerock.org/license/CDDLv1.0.html.
011 * See the License for the specific language governing permissions
012 * and limitations under the License.
013 *
014 * When distributing Covered Code, include this CDDL HEADER in each
015 * file and include the License file at legal-notices/CDDLv1_0.txt.
016 * If applicable, add the following below this CDDL HEADER, with the
017 * fields enclosed by brackets "[]" replaced with your own identifying
018 * information:
019 *      Portions Copyright [yyyy] [name of copyright owner]
020 *
021 * CDDL HEADER END
022 *
023 *
024 *      Copyright 2006-2008 Sun Microsystems, Inc.
025 *      Portions Copyright 2014 ForgeRock AS
026 */
027package org.opends.server.api;
028import org.forgerock.i18n.LocalizableMessage;
029
030
031
032import java.util.List;
033
034import org.opends.server.admin.std.server.SynchronizationProviderCfg;
035import org.forgerock.opendj.config.server.ConfigException;
036import org.opends.server.types.DirectoryException;
037import org.opends.server.types.InitializationException;
038import org.opends.server.types.Modification;
039import org.opends.server.types.SynchronizationProviderResult;
040import org.opends.server.types.operation.*;
041
042
043
044/**
045 * This class defines the set of methods and structures that are
046 * available for use in a Directory Server synchronization provider.
047 * A synchronization provider ensures that changes in one instance of
048 * the Directory Server are properly communicated to other instances,
049 * and potentially to other kinds of applications, so that they can be
050 * updated accordingly.
051 *
052 * @param <T> the configuration for the synchronization provider.
053 */
054@org.opends.server.types.PublicAPI(
055     stability=org.opends.server.types.StabilityLevel.VOLATILE,
056     mayInstantiate=false,
057     mayExtend=true,
058     mayInvoke=false)
059public abstract class
060       SynchronizationProvider<T extends SynchronizationProviderCfg>
061{
062  /**
063   * Performs any initialization that might be necessary for this
064   * synchronization provider.
065   *
066   * @param  config  The configuration information for this
067   *                 synchronization provider.
068   *
069   * @throws  ConfigException  If the provided entry does not contain
070   *                           a valid configuration for this
071   *                           synchronization provider.
072   *
073   * @throws  InitializationException  If a problem occurs while
074   *                                   initializing the
075   *                                   synchronization provider that
076   *                                   is not related to the server
077   *                                   configuration.
078   */
079  public abstract void initializeSynchronizationProvider(T config)
080         throws ConfigException, InitializationException;
081
082
083
084  /**
085   * Indicates whether the provided configuration is acceptable for
086   * this synchronization provider.  It should be possible to call
087   * this method on an uninitialized synchronization provider instance
088   * in order to determine whether the synchronization provider would
089   * be able to use the provided configuration.
090   * <BR><BR>
091   * Note that implementations which use a subclass of the provided
092   * configuration class will likely need to cast the configuration
093   * to the appropriate subclass type.
094   *
095   * @param  configuration        The synchronization provider
096   *                              configuration for which to make the
097   *                              the determination.
098   * @param  unacceptableReasons  A list that may be used to hold the
099   *                              reasons that the provided
100   *                              configuration is not acceptable.
101   *
102   * @return  {@code true} if the provided configuration is acceptable
103   *          for this synchronization provider, or {@code false} if
104   *          not.
105   */
106  public boolean isConfigurationAcceptable(
107                      SynchronizationProviderCfg configuration,
108                      List<LocalizableMessage> unacceptableReasons)
109  {
110    // This default implementation does not perform any special
111    // validation.  It should be overridden by synchronization
112    // provider implementations that wish to perform more detailed
113    // validation.
114    return true;
115  }
116
117
118
119  /**
120   * Performs any necessary final initialization processing for this
121   * synchronization provider.
122   * This will be called just after the provider has been
123   * registered with the server but before it has been unloaded.
124   */
125  public void completeSynchronizationProvider()
126  {
127    // No implementation is required by default.
128  }
129
130  /**
131   * Performs any necessary finalization for this synchronization
132   * provider.  This will be called just after the provider has been
133   * unregistered with the server but before it has been unloaded.
134   */
135  public void finalizeSynchronizationProvider()
136  {
137    // No implementation is required by default.
138  }
139
140
141
142  /**
143   * Performs any necessary synchronization processing for the
144   * operation that may be needed early on to deal with any potential
145   * conflict resolution or updates to historical data.  This method
146   * will be invoked immediately after a lock is acquired on the
147   * target entry.
148   *
149   * @param  addOperation  The add operation to be processed.
150   *
151   * @return  Information about the result of the synchronization
152   *          provider processing.  Note that if the provider
153   *          indicates that processing should end for the operation,
154   *          it must set the result code for the operation and should
155   *          also set the response message.
156   *
157   * @throws  DirectoryException  If a problem occurs during
158   *                              synchronization processing.
159   */
160  public SynchronizationProviderResult handleConflictResolution(
161         PreOperationAddOperation addOperation)
162         throws DirectoryException
163  {
164    // No processing is required by default.
165    return new SynchronizationProviderResult.ContinueProcessing();
166  }
167
168
169
170  /**
171   * Performs any necessary synchronization processing that may be
172   * needed before the provided add operation is performed.  This
173   * method will be invoked immediately before processing the add
174   * operation in the backend.
175   *
176   * @param  addOperation  The add operation to be processed.
177   *
178   * @return  Information about the result of the synchronization
179   *          provider processing.  Note that if the provider
180   *          indicates that processing should end for the operation,
181   *          it must set the result code for the operation and should
182   *          also set the response message.
183   *
184   * @throws  DirectoryException  If a problem occurs during
185   *                              synchronization processing.
186   */
187  public abstract SynchronizationProviderResult doPreOperation(
188         PreOperationAddOperation addOperation)
189         throws DirectoryException;
190
191
192
193  /**
194   * Performs any necessary synchronization processing that may be
195   * needed after the provided add operation is performed.  This
196   * method will be invoked immediately after processing the add
197   * operation in the backend and releasing the lock on the target
198   * entry.
199   *
200   * @param  addOperation  The add operation to be processed.
201   *
202   * @throws  DirectoryException  If a problem occurs during
203   *                              synchronization processing.
204   */
205  public abstract void doPostOperation(
206         PostOperationAddOperation addOperation)
207         throws DirectoryException;
208
209
210
211  /**
212   * Performs any necessary synchronization processing for the
213   * operation that may be needed early on to deal with any potential
214   * conflict resolution or updates to historical data.  This method
215   * will be invoked immediately after a lock is acquired on the
216   * target entry.
217   *
218   * @param  deleteOperation  The delete operation to be processed.
219   *
220   * @return  Information about the result of the synchronization
221   *          provider processing.  Note that if the provider
222   *          indicates that processing should end for the operation,
223   *          it must set the result code for the operation and should
224   *          also set the response message.
225   *
226   * @throws  DirectoryException  If a problem occurs during
227   *                              synchronization processing.
228   */
229  public SynchronizationProviderResult
230         handleConflictResolution(
231         PreOperationDeleteOperation deleteOperation)
232         throws DirectoryException
233  {
234    // No processing is required by default.
235    return new SynchronizationProviderResult.ContinueProcessing();
236  }
237
238
239
240  /**
241   * Performs any necessary synchronization processing that may be
242   * needed before the provided delete operation is performed.  This
243   * method will be invoked immediately before processing the delete
244   * operation in the backend.
245   *
246   * @param  deleteOperation  The delete operation to be processed.
247   *
248   * @return  Information about the result of the synchronization
249   *          provider processing.  Note that if the provider
250   *          indicates that processing should end for the operation,
251   *          it must set the result code for the operation and should
252   *          also set the response message.
253   *
254   * @throws  DirectoryException  If a problem occurs during
255   *                              synchronization processing.
256   */
257  public abstract SynchronizationProviderResult
258         doPreOperation(PreOperationDeleteOperation deleteOperation)
259         throws DirectoryException;
260
261
262
263  /**
264   * Performs any necessary synchronization processing that may be
265   * needed after the provided delete operation is performed.  This
266   * method will be invoked immediately after processing the delete
267   * operation in the backend and releasing the lock on the target
268   * entry.
269   *
270   * @param  deleteOperation  The delete operation to be processed.
271   *
272   * @throws  DirectoryException  If a problem occurs during
273   *                              synchronization processing.
274   */
275  public abstract void doPostOperation(
276         PostOperationDeleteOperation deleteOperation)
277         throws DirectoryException;
278
279
280
281  /**
282   * Performs any necessary synchronization processing for the
283   * operation that may be needed early on to deal with any potential
284   * conflict resolution or updates to historical data.  This method
285   * will be invoked immediately after a lock is acquired on the
286   * target entry.
287   *
288   * @param  modifyOperation  The modify operation to be processed.
289   *
290   * @return  Information about the result of the synchronization
291   *          provider processing.  Note that if the provider
292   *          indicates that processing should end for the operation,
293   *          it must set the result code for the operation and should
294   *          also set the response message.
295   *
296   * @throws  DirectoryException  If a problem occurs during
297   *                              synchronization processing.
298   */
299  public SynchronizationProviderResult
300         handleConflictResolution(
301         PreOperationModifyOperation modifyOperation)
302         throws DirectoryException
303  {
304    // No processing is required by default.
305    return new SynchronizationProviderResult.ContinueProcessing();
306  }
307
308
309
310  /**
311   * Performs any necessary synchronization processing that may be
312   * needed before the provided modify operation is performed.  This
313   * method will be invoked immediately before processing the modify
314   * operation in the backend.
315   *
316   * @param  modifyOperation  The modify operation to be processed.
317   *
318   * @return  Information about the result of the synchronization
319   *          provider processing.  Note that if the provider
320   *          indicates that processing should end for the operation,
321   *          it must set the result code for the operation and should
322   *          also set the response message.
323   *
324   * @throws  DirectoryException  If a problem occurs during
325   *                              synchronization processing.
326   */
327  public abstract SynchronizationProviderResult
328         doPreOperation(PreOperationModifyOperation modifyOperation)
329         throws DirectoryException;
330
331
332
333  /**
334   * Performs any necessary synchronization processing that may be
335   * needed after the provided modify operation is performed.  This
336   * method will be invoked immediately after processing the modify
337   * operation in the backend and releasing the lock on the target
338   * entry.
339   *
340   * @param  modifyOperation  The modify operation to be processed.
341   *
342   * @throws  DirectoryException  If a problem occurs during
343   *                              synchronization processing.
344   */
345  public abstract void doPostOperation(
346         PostOperationModifyOperation modifyOperation)
347         throws DirectoryException;
348
349
350
351  /**
352   * Performs any necessary synchronization processing for the
353   * operation that may be needed early on to deal with any potential
354   * conflict resolution or updates to historical data.  This method
355   * will be invoked immediately after a lock is acquired on the
356   * target entry.
357   *
358   * @param  modifyDNOperation  The modify DN operation to be
359   *                            processed.
360   *
361   * @return  Information about the result of the synchronization
362   *          provider processing.  Note that if the provider
363   *          indicates that processing should end for the operation,
364   *          it must set the result code for the operation and should
365   *          also set the response message.
366   *
367   * @throws  DirectoryException  If a problem occurs during
368   *                              synchronization processing.
369   */
370  public SynchronizationProviderResult handleConflictResolution(
371         PreOperationModifyDNOperation modifyDNOperation)
372         throws DirectoryException
373  {
374    // No processing is required by default.
375    return new SynchronizationProviderResult.ContinueProcessing();
376  }
377
378
379
380  /**
381   * Performs any necessary synchronization processing that may be
382   * needed before the provided modify DN operation is performed.
383   * This method will be invoked immediately before processing the
384   * modify DN operation in the backend.
385   *
386   * @param  modifyDNOperation  The modify DN operation to be
387   *                            processed.
388   *
389   * @return  Information about the result of the synchronization
390   *          provider processing.  Note that if the provider
391   *          indicates that processing should end for the operation,
392   *          it must set the result code for the operation and should
393   *          also set the response message.
394   *
395   * @throws  DirectoryException  If a problem occurs during
396   *                              synchronization processing.
397   */
398  public abstract SynchronizationProviderResult doPreOperation(
399         PreOperationModifyDNOperation modifyDNOperation)
400         throws DirectoryException;
401
402
403
404  /**
405   * Performs any necessary synchronization processing that may be
406   * needed after the provided modify DN operation is performed.  This
407   * method will be invoked immediately after processing the modify DN
408   * operation in the backend and releasing the lock on the target
409   * entry.
410   *
411   * @param  modifyDNOperation  The modify DN operation to be
412   *                            processed.
413   *
414   * @throws  DirectoryException  If a problem occurs during
415   *                              synchronization processing.
416   */
417  public abstract void doPostOperation(
418         PostOperationModifyDNOperation modifyDNOperation)
419         throws DirectoryException;
420
421  /**
422   * Performs any processing that may be required whenever the server
423   * schema has been updated.  This may be invoked for schema
424   * modifications made with the server online, and it may also be
425   * called if the server detects that there were any scheam changes
426   * made with the server offline (e.g., by directly editing the
427   * schema configuration files).
428   * <BR><BR>
429   * At the time this method is called, the schema changes will have
430   * already been applied to the server.  As such, this method must
431   * make a best effort attempt to process the associated schema
432   * changes, and is not allowed to throw any exceptions.
433   *
434   * @param  modifications  The set of modifications that have been
435   *                        made to the server schema.
436   */
437  public abstract void processSchemaChange(List<Modification>
438                                                modifications);
439}
440