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