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