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-2013 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 }