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