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 }