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