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     * trunk/opends/resource/legal-notices/OpenDS.LICENSE
011     * or https://OpenDS.dev.java.net/OpenDS.LICENSE.
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     * trunk/opends/resource/legal-notices/OpenDS.LICENSE.  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 2006-2008 Sun Microsystems, Inc.
026     */
027    package org.opends.server.api;
028    import org.opends.messages.Message;
029    
030    
031    
032    import java.util.List;
033    
034    import org.opends.server.admin.std.server.SynchronizationProviderCfg;
035    import org.opends.server.config.ConfigException;
036    import org.opends.server.types.DirectoryException;
037    import org.opends.server.types.InitializationException;
038    import org.opends.server.types.Modification;
039    import org.opends.server.types.SynchronizationProviderResult;
040    import 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)
059    public 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<Message> 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       * deregistered 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