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 * docs/licenses/cddl.txt 011 * or http://www.opensource.org/licenses/cddl1.php. 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 * docs/licenses/cddl.txt. 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 2010-2014 UnboundID Corp. 026 */ 027 package com.unboundid.directory.sdk.sync.types; 028 029 import java.util.Collection; 030 import java.util.List; 031 032 import com.unboundid.ldap.sdk.ChangeLogEntry; 033 import com.unboundid.ldap.sdk.Entry; 034 import com.unboundid.ldap.sdk.unboundidds.UnboundIDChangeLogEntry; 035 036 /** 037 * This interface represents a single synchronized change from the Sync 038 * Source to the Sync Destination. It exists from when a change is detected 039 * all the way through when the change is applied at the destination. 040 */ 041 public interface SyncOperation 042 { 043 /** 044 * Return the type of this SynchronizationOperation. 045 * 046 * @return The type of this SynchronizationOperation. 047 */ 048 SyncOperationType getType(); 049 050 051 052 /** 053 * Return a String that can be used to correlate this change back to the 054 * source entry. For example, if the source endpoint is a directory server, 055 * this will be a DN. 056 * 057 * @return A String that can be used to correlate this change back to the 058 * source entry. 059 */ 060 String getIdentifiableInfo(); 061 062 063 064 /** 065 * Return a unique ID for this {@code SyncOperation}. This ID is used in 066 * log messages. 067 * 068 * @return A unique ID for this operation. 069 */ 070 String getUniqueId(); 071 072 073 074 /** 075 * Return the Entry that was fetched from the sync source. This may be null 076 * if the source entry no longer exists or has not yet been fetched. 077 * 078 * @return The entry entry that was fetched from the source server. 079 */ 080 Entry getSourceEntry(); 081 082 083 084 /** 085 * Sets the entry that was fetched from the sync source. If the entry was 086 * deleted, then sufficient information about the entry must be provided so 087 * that it can be correlated to a destination entry. 088 * 089 * @param sourceEntry The entry that was fetched from the source. 090 * @param isDeletedEntry {@code true} if and only if the entry was deleted 091 * at the source. 092 */ 093 void setSourceEntry(Entry sourceEntry, boolean isDeletedEntry); 094 095 096 097 /** 098 * Return the original changelog entry that was detected for this operation. 099 * This is only applicable when synchronizing from a data source that 100 * supplies an LDAP changelog as described in 101 * <i>draft-good-ldap-changelog</i>, such as the UnboundID Directory Server 102 * or Sun Directory Server. 103 * <p> 104 * Note that this is the raw changelog entry and does not have any mappings 105 * or filterings applied to it. 106 * 107 * @return a {@link ChangeLogEntry} instance, or null if the source endpoint 108 * does not use an LDAP changelog for change detection. 109 */ 110 ChangeLogEntry getChangeLogEntry(); 111 112 113 114 /** 115 * Return the original changelog entry that was detected for this operation. 116 * This is only applicable when synchronizing from an UnboundID Directory 117 * Server. The UnboundID LDAP Changelog provides additional functionality not 118 * present in other directory servers. 119 * <p> 120 * Note that this is the raw changelog entry and does not have any mappings 121 * or filterings applied to it. 122 * 123 * @return a {@link UnboundIDChangeLogEntry} instance, or null if the source 124 * endpoint is not an UnboundID Directory Server. 125 */ 126 UnboundIDChangeLogEntry getUnboundIDChangeLogEntry(); 127 128 129 130 /** 131 * Return the original change record that was detected for this operation. 132 * This is only applicable when synchronizing from a data source that 133 * is implemented by the <code>SyncSource</code> or 134 * <code>ScriptedSyncSource</code> extension type. 135 * 136 * @return a {@link ChangeRecord} instance, or null if the source endpoint 137 * is not an instance of <code>SyncSource</code> or 138 * <code>ScriptedSyncSource</code>. 139 */ 140 ChangeRecord getChangeRecord(); 141 142 143 144 /** 145 * Return the DatabaseChangeRecord that was detected from a RDBMS. This is 146 * only applicable when synchronizing from a database environment, and will 147 * be null otherwise. 148 * 149 * @return a DatabaseChangeRecord that was detected from a database, or null 150 * if the sync source is not a JDBC sync source. 151 */ 152 DatabaseChangeRecord getDatabaseChangeRecord(); 153 154 155 156 /** 157 * Determines whether this SyncOperation represents a modify DN operation on 158 * the source entry (if the source is an LDAP directory). The 159 * result of this method is undefined if the source is a relational database 160 * or some other type of endpoint. 161 * 162 * @return true if the entry has been renamed, false otherwise. 163 */ 164 boolean isModifyDN(); 165 166 167 168 /** 169 * Returns a representation of the target destination entry before it is 170 * modified or renamed. This can be used to obtain the before-values of any 171 * attributes. The returned entry cannot be modified. 172 * <p> 173 * This value is only defined after the SyncOperation has made it past the 174 * post-mapping stage in the SyncPipe. 175 * 176 * @return a {@link Entry} instance. 177 */ 178 Entry getDestinationEntryBeforeChange(); 179 180 181 182 /** 183 * Returns a representation of the target destination entry after it is 184 * modified or renamed. This can be used to obtain the after-values of any 185 * attributes. 186 * <p> 187 * This value is only defined after the SyncOperation has made it past the 188 * post-mapping stage in the SyncPipe. 189 * <p> 190 * The returned entry is modifiable and can be used to influence 191 * the final list of modifications to apply at the destination. The 192 * Synchronization Server computes a diff between this entry and the existing 193 * entry returned from the destination. Any modifications to this entry would 194 * have to take place in either {@code LDAPSyncDestinationPlugin.preFetch} or 195 * {@code LDAPSyncDestinationPlugin.postFetch}. 196 * 197 * @return a {@link Entry} instance. 198 */ 199 Entry getDestinationEntryAfterChange(); 200 201 202 203 /** 204 * Return the names of the attributes that were modified at the source. 205 * 206 * @return The names of the attributes that were modified at the source. 207 */ 208 Collection<String> getModifiedSourceAttributes(); 209 210 211 212 /** 213 * Add an additional source attribute that should be synchronized to the 214 * destination. 215 * 216 * @param attributeName The attribute to add to the set of attributes to 217 * synchronize. 218 */ 219 void addModifiedSourceAttribute(String attributeName); 220 221 222 223 /** 224 * Remove a source attribute that should not be synchronized to the 225 * destination. 226 * 227 * @param attributeName The attribute to remove from the set of attributes 228 * to synchronize. 229 */ 230 void removeModifiedSourceAttribute(String attributeName); 231 232 233 234 /** 235 * Add the name of a destination attribute that should be synchronized. 236 * 237 * @param attributeName The name of the destination attribute to 238 * synchronize. 239 */ 240 void addModifiedDestinationAttribute(String attributeName); 241 242 243 244 /** 245 * Return the name of the Sync Pipe for the operation being processed. 246 * 247 * @return The name of the Sync Pipe for the operation being processed. 248 */ 249 String getSyncPipeName(); 250 251 252 253 /** 254 * Return the name of the Sync Class for the operation being processed. 255 * 256 * @return The name of the Sync Class for the operation being processed. 257 */ 258 String getSyncClassName(); 259 260 261 262 /** 263 * Return the {@link SyncClass} for the operation being processed. This can 264 * be used to determine the correlation attributes and other properties 265 * configured for this type of change. 266 * 267 * @return The Sync Class that this operation falls into, or null if no 268 * Sync Class has been determined yet. 269 */ 270 SyncClass getSyncClass(); 271 272 273 274 /** 275 * Stores an attachment in the operation. This can be used by an extension 276 * to have information carried in the synchronization operation from one 277 * extension point to the next. 278 * 279 * @param key The key of the attachment. To avoid conflicts, the 280 * fully-qualified class name of the extension should be used 281 * as a prefix of the key. 282 * 283 * @param value The value of the attachment. 284 */ 285 void putAttachment(Object key, Object value); 286 287 288 289 /** 290 * Returns an attachment from the operation that was previously set with a 291 * call to {@link #putAttachment}. 292 * 293 * @param key The key of the attachment. 294 * 295 * @return The value of the attachment or {@code null} if no attachment was 296 * set for the specified key. 297 */ 298 Object getAttachment(Object key); 299 300 301 302 /** 303 * Returns a list of warning messages (if any) about this SyncOperation. For 304 * example, if a changelog entry omitted some data because an attribute had 305 * too many values, there will be a message in the returned list indicating 306 * so. Typically synchronization of this SyncOperation can continue despite 307 * these warnings. 308 * 309 * @return a list of warning messages; the list will be empty if there are no 310 * warnings. 311 */ 312 List<String> getWarnings(); 313 314 315 316 /** 317 * Logs an error message to the synchronization log for this change. Messages 318 * logged here should pertain to this specific change. For general logging 319 * capabilities, see {@link SyncServerContext} 320 * 321 * @param message The message to log. 322 */ 323 void logError(String message); 324 325 326 327 /** 328 * Logs an informational message to the synchronization log for this change. 329 * Messages logged here should pertain to this specific change. For general 330 * logging capabilities, see {@link SyncServerContext} 331 * 332 * @param message The message to log. 333 */ 334 void logInfo(String message); 335 }