public class ChangeEvent extends IdentityData
This class is the essential object used to represent data in a synchronization pipeline. In a synchronization
pipeline, the following capture-transform-apply process occurs:
1. An event is detected on a source backend by a capture connector. This is represented as a ChangeEvent object.
2. In the transform phase, the ChangeEvent produced in step 1 is transformed into a new ChangeEvent object that
is then sent to the apply connector.
3. The apply connector applies the ChangeEvent object produced in step 2. This results in an operation that is
executed on a target backend.
As has been previously described, this class is re-used for 2 different purposes.
- In the context of a capture connector, it represents a single change event captured on a backend by a capture connector. In this scenario, users of this class will mostly be calling the getter methods to fetch existing values from the change event.
- In the context of an apply connector, it is used to represent a change or modification to be applied on a backend, for example to insert, update, or delete an entry on a target naming context. In this scenario, users of this class will mostly be calling the setter methods to build up the set of changes (setting the event ID, attribute values, and the change event type) that will then be applied on the backend.
Key components of a ChangeEvent object:getEventId method.
The event ID must contain the distinguished name (DN) for the entry that was changed or that you want to change.
EventType which indicates the type of change
detected (in the capture scenario), or the type of change to be applied on the backend (in the apply scenario).
IdentityData class.
getPatchOperations() method.
If this list is not empty, it will contain the granular updates (which attributes were changed, and for each of
those attributes which specific values were added or removed or replaced) that were captured on the backend.
Note: most connectors do not support granular change detection, see product documentation to find out which
capture connectors provide this level of detail.
// Assume that this change event has been produced by a capture connector.
ChangeEvent ce;
// This contains the type of change that was detected: INSERT/UPDATE/DELETE/MOVE
EventType eventType = ce.getEventType();
// This contains the event identifier, which is the distinguished name (DN) of the entry that was changed.
String eventId = ce.getEventId();
// The set of all the attribute names that have a value.
Set<String> attributeNames = ce.getAttributeNames();
// Use this method to check if a change event contains a specific attribute.
boolean containsTitleAttr = ce.containsAttribute("title");
// Get the first value of the givenName attribute. Use this method if you know that your attribute is single-valued.
String valueForGivenName = ce.getFirstValueAsString("givenName");
// Get the list of values for the mail attribute. Use this method to retrieve all values for a multi-valued attribute.
List<String> valuesForMail = ce.getValuesAsString("mail");
// Use this method if you know that your attribute is a single-valued complex attribute.
ComplexValue complexValueForName = ce.getFirstComplexValue("name");
// Use this method if you know that your attribute is a multi-valued complex attribute.
List<ComplexValue> complexValuesForPhoneNumber = ce.getComplexValues("phoneNumbers");
Example #2: Extracting the granular changes (patch operations) from an existing ChangeEvent object
// Assume that this change event has been produced by a capture connector.
ChangeEvent ce;
// This method retrieves the list of patch operations (granular changes) that were captured.
List<IdentityPatchOperation> patchOperations = ce.getPatchOperations();
// Note: for most capture connector types, this list will be empty. This is because most connectors don't have
// the ability to capture the granular changes. Check the product documentation to see which connector types
// support granular change detection.
if (!patchOperations.isEmpty()) {
for (IdentityPatchOperation patchOperation : patchOperations) {
// This tells you the name of the attribute that was modified.
// Note: this can be a simple attribute like givenName or a complex attribute like name.lastName
IdentityAttributePath attributePath = patchOperation.getAttributePath();
// This tells you the type of operation (value added, replaced, or removed) that was detected.
PatchOpType operationType = patchOperation.getOpType();
if (patchOperation.isValueComplex()) {
// This returns the actual data for the complex attribute values that were added/replaced/removed
List<ComplexValue> complexValues = patchOperation.getComplexValues();
} else {
// This returns the actual data for the attribute values that were added/replaced/removed
List<String> values = patchOperation.getValuesAsString();
}
}
}
"Apply" Examples:
ChangeEvent createEntryOperation = new ChangeEvent(EventType.INSERT);
// Important: Always set the Event ID, which should be the distinguished name (DN) of the entry you want to insert/update/delete.
createEntryOperation.setEventId("cn=John Smith,ou=People,o=SuperCorp");
createEntryOperation.addAttribute("cn", "John Smith");
createEntryOperation.addAttribute("sn", "Smith");
createEntryOperation.addAttribute("givenName", "John");
createEntryOperation.addAttribute("mail", "jsmith@radiantlogic.com", "jsmith@gmail.com");
createEntryOperation.addAttribute("objectclass", "top", "person", "organizationalPerson", "inetOrgPerson");
Example #2: Generating a ChangeEvent object to update an existing entry on a target naming context or backend
ChangeEvent updateEntryOperation = new ChangeEvent(EventType.UPDATE);
// Important: Always set the Event ID, which should be the distinguished name of the entry you want to insert/update/delete.
updateEntryOperation.setEventId("cn=John Smith,ou=People,o=SuperCorp");
updateEntryOperation.addAttribute("title", "CEO", "Chairman");
updateEntryOperation.addAttribute("carLicense", "RADIANT");
Example #3: Generating a ChangeEvent object to delete an existing entry on a target naming context or backend
ChangeEvent deleteEntryOperation = new ChangeEvent(EventType.DELETE);
// Important: Always set the Event ID, which should be the distinguished name of the entry you want to insert/update/delete.
deleteEntryOperation.setEventId("cn=John Smith,ou=People,o=SuperCorp");
Example #4: Generating a ChangeEvent object to perform an LDAP move operation on a target naming context or backend
ChangeEvent moveEntryOp = new ChangeEvent(EventType.MOVE);
// The "old dn" should be set to the current distinguished name (DN) of the entry.
moveEntryOp.setOldDn("cn=jack smith,ou=Sales,o=SuperCorp");
// Event ID should be set to the new distinguished name (DN) of the entry.
moveEntryOp.setEventId("uid=jsmith,ou=Marketing,o=SuperCorp");
Example #5: Generate a ChangeEvent object to perform granular updates on an existing entry on a target naming context or backend
ChangeEvent granularUpdateForEntry = new ChangeEvent(EventType.UPDATE);
granularUpdateForEntry.setEventId("cn=Sales,ou=Groups,o=SuperCorp");
// Add 2 new members to the group
granularUpdateForEntry.addPatchOperation(IdentityPatchOperation.add("member", Arrays.asList("cn=Jane Smith,ou=People,o=SuperCorp",
"cn=John Smith,ou=People,o=SuperCorp")));
// Remove 2 specific members from the group
granularUpdateForEntry.addPatchOperation(IdentityPatchOperation.remove("member", Arrays.asList("cn=Mike Patterson,ou=People,o=SuperCorp",
"cn=Stephanie Patterson,ou=People,o=SuperCorp")));
// Replace the description of the group
granularUpdateForEntry.addPatchOperation(IdentityPatchOperation.replace("description", "What a fun group."));
| Modifier and Type | Class and Description |
|---|---|
static class |
ChangeEvent.ChangeEventDeserializer
Implementation of a JsonDeserializer (com.fasterxml.jackson.databind) for ChangeEvent objects.
|
static class |
ChangeEvent.ChangeEventSerializer
Implementation of a JsonSerializer (com.fasterxml.jackson.databind) for ChangeEvent objects.
|
| Modifier and Type | Field and Description |
|---|---|
static java.lang.String |
APPROVAL_CONFIG_KEY |
static java.lang.String |
APPROVALS_ATTRIBUTE_APPROVERS_LIST |
static java.lang.String |
APPROVALS_ATTRIBUTE_STATUS_REJECTED |
static java.lang.String |
CHANGE_MODE_KEY
The JSON attribute name for the field which contains the change mode for the ChangeEvent when the
ChangeEvent is serialized as a JSON object.
|
static java.lang.String |
CHG_OPS_KEY
The JSON attribute name for the field which contains all the ChangeEvent patch operations when the ChangeEvent
is serialized as a JSON object.
|
static java.lang.String |
CONNECTOR_CURSOR_KEY
The JSON attribute name for the field which contains the connector cursor for the ChangeEvent when the
ChangeEvent is serialized as a JSON object.
|
static java.lang.String |
CONNECTOR_NAME_KEY
The JSON attribute name for the field which contains the connector identifier for the ChangeEvent when the
ChangeEvent is serialized as a JSON object.
|
static java.lang.String |
EVENT_ID_ATTR_KEY
The JSON attribute name for the field which contains the event identifier for the ChangeEvent when the
ChangeEvent is serialized as a JSON object.
|
static java.lang.String |
EVENT_TYPE_KEY
The JSON attribute name for the field which contains the event type for the ChangeEvent when the ChangeEvent
is serialized as a JSON object.
|
static java.lang.String |
IS_FROM_UPLOAD_KEY
The JSON attribute name for the field which indicates if this ChangeEvent was created during an Upload
operation.
|
static java.lang.String |
MESSAGE_ATTRS_KEY
The JSON attribute name for the field which contains all the ChangeEvent attributes and their values when the ChangeEvent
is serialized as a JSON object.
|
static java.lang.String |
OLD_DN
The name of the special attribute used for LDAP "move" operations to represent the previous value of the DN
(before the move operation is applied).
|
static java.lang.String |
SYNC_EVENT_PIPELINE_ID |
mapper| Constructor and Description |
|---|
ChangeEvent()
Creates an empty change event object.
|
ChangeEvent(EventType eventType)
Creates an empty change event object, initialized with the specified event type.
|
| Modifier and Type | Method and Description |
|---|---|
void |
addPatchOperation(IdentityPatchOperation patchOperation)
Adds the specified patch operation to the current list of patch operations for this ChangeEvent.
|
void |
addPatchOperations(java.util.List<IdentityPatchOperation> patchOperations)
Adds the specified patch operations to the current list of patch operations for this ChangeEvent.
|
void |
clearPatchOperations()
Removes all patch operations for this ChangeEvent.
|
ApprovalConfiguration |
getApprovalConfiguration() |
ChangeMode |
getChangeMode()
Returns the change mode for this ChangeEvent.
|
Cursor |
getConnectorCursor()
Returns the cursor associated with this ChangeEvent.
|
java.lang.String |
getConnectorNameId()
Returns the identifier for the connector that produced this ChangeEvent.
|
java.lang.String |
getEventId()
Returns the event ID for this ChangeEvent.
|
EventType |
getEventType()
Returns the type of event for this ChangeEvent.
|
protected java.lang.Object |
getExtraAttributeValue(java.lang.String attributeName) |
java.lang.String |
getOldDn()
Returns the value of the "old_dn" attribute.
|
java.util.List<IdentityPatchOperation> |
getPatchOperations()
Returns the list of patch operations for this ChangeEvent.
|
java.util.Map<java.lang.String,java.util.Map<PatchOpType,IdentityPatchOperation>> |
getPatchOperationsByAttributeMap()
Returns a map, organized by attribute name, representing the current patch operations for this ChangeEvent.
|
java.lang.String |
getSystemExpirationDate() |
boolean |
isEmptyPatchOperations()
Indicates whether the list of patch operations for this ChangeEvent is empty.
|
boolean |
isFromUpload()
Represents if this ChangeEvent was created as part of an Upload operation.
|
void |
removePatchOperation(IdentityPatchOperation patchOpToRemove)
Removes the specified patch operation from the current list of patch operations for this ChangeEvent.
|
boolean |
requiresApprovals() |
void |
setApprovalConfiguration(ApprovalConfiguration approvalConfiguration) |
void |
setChangeMode(ChangeMode changeMode)
Sets the change mode for this ChangeEvent.
|
void |
setConnectorCursor(Cursor connectorCursor)
Sets the capture connector cursor for this ChangeEvent.
|
void |
setConnectorNameId(java.lang.String connectorNameId)
Sets the identifier for the connector that produced this ChangeEvent.
|
void |
setEventId(java.lang.String eventId)
Sets the event ID for this ChangeEvent.
|
void |
setEventType(EventType eventType)
Sets the event type for this ChangeEvent.
|
void |
setFromUpload(boolean isFromUpload)
Sets if this ChangeEvent was created as part of an Upload operation.
|
void |
setOldDn(java.lang.String oldDn)
Sets the value of the "old_dn" attribute.
|
void |
setSystemExpirationDate(java.lang.String systemExpirationDate) |
java.lang.String |
toShortString()
Returns a shortened String representation of this ChangeEvent.
|
java.lang.String |
toString()
Returns a String representation of this ChangeEvent.
|
java.lang.String |
toString(boolean isHideValueOfPasswordAttributes)
Returns a String representation of this ChangeEvent.
|
java.lang.String |
toString(boolean isHideValueOfPasswordAttributes,
boolean isDetailedCursor)
Returns a String representation of this ChangeEvent.
|
addAttribute, addAttribute, addAttribute, addComplexAttribute, addComplexAttribute, addComplexAttribute, clone, containsAttribute, containsComplexAttributeValue, getAdditionalProperties, getAttributeNames, getComplexValues, getFirstComplexValue, getFirstValueAsString, getNullSafeValuesAsString, getValuesAsString, isAttributeValueComplex, listAttributeNames, putAttribute, removeAttribute, renameAttribute, setAdditionalPropertypublic static final java.lang.String OLD_DN
public static final java.lang.String MESSAGE_ATTRS_KEY
public static final java.lang.String CHG_OPS_KEY
public static final java.lang.String EVENT_TYPE_KEY
public static final java.lang.String IS_FROM_UPLOAD_KEY
public static final java.lang.String CONNECTOR_NAME_KEY
public static final java.lang.String EVENT_ID_ATTR_KEY
public static final java.lang.String CONNECTOR_CURSOR_KEY
public static final java.lang.String CHANGE_MODE_KEY
public static final java.lang.String APPROVAL_CONFIG_KEY
public static final java.lang.String APPROVALS_ATTRIBUTE_STATUS_REJECTED
public static final java.lang.String APPROVALS_ATTRIBUTE_APPROVERS_LIST
public static final java.lang.String SYNC_EVENT_PIPELINE_ID
public ChangeEvent()
public ChangeEvent(EventType eventType)
eventType - The event type (INSERT/UPDATE/DELETE/MOVE/SKIP) for the ChangeEvent.protected java.lang.Object getExtraAttributeValue(java.lang.String attributeName)
getExtraAttributeValue in class IdentityDatapublic boolean isFromUpload()
public void setFromUpload(boolean isFromUpload)
isFromUpload - true if this ChangeEvent was created as part of an Upload operation.public java.lang.String getOldDn()
public void setOldDn(java.lang.String oldDn)
oldDn - The value to set for the "old_dn" attribute.public EventType getEventType()
public void setEventType(EventType eventType)
eventType - The event type to set for this ChangeEvent.public java.lang.String getEventId()
public void setEventId(java.lang.String eventId)
eventId - The event ID (distinguished name) to set for this ChangeEvent.public Cursor getConnectorCursor()
public void setConnectorCursor(Cursor connectorCursor)
connectorCursor - The capture connector cursor to set for this change event.public java.lang.String getConnectorNameId()
null.null if this
ChangeEvent was not generated by a connector.public void setConnectorNameId(java.lang.String connectorNameId)
connectorNameId - The connector that produced this ChangeEvent.public ChangeMode getChangeMode()
public void setChangeMode(ChangeMode changeMode)
changeMode - The change mode for this ChangeEvent.public java.util.List<IdentityPatchOperation> getPatchOperations()
public boolean isEmptyPatchOperations()
true if the list of patch operations for this ChangeEvent is empty, or false otherwise.public boolean requiresApprovals()
public java.lang.String getSystemExpirationDate()
public void setSystemExpirationDate(java.lang.String systemExpirationDate)
public void addPatchOperation(IdentityPatchOperation patchOperation)
patchOperation - The patch operation to add to the list of patch operations for this ChangeEvent.public void addPatchOperations(java.util.List<IdentityPatchOperation> patchOperations)
patchOperations - The list of patch operation objects to add to the list of patch operations for this ChangeEvent.public void removePatchOperation(IdentityPatchOperation patchOpToRemove)
patchOpToRemove - The patch operation to remove from the current list of patch operations for this ChangeEvent.public void clearPatchOperations()
public java.util.Map<java.lang.String,java.util.Map<PatchOpType,IdentityPatchOperation>> getPatchOperationsByAttributeMap()
public ApprovalConfiguration getApprovalConfiguration()
public void setApprovalConfiguration(ApprovalConfiguration approvalConfiguration)
public java.lang.String toString()
toString in class IdentityDatapublic java.lang.String toString(boolean isHideValueOfPasswordAttributes)
toString in class IdentityDataisHideValueOfPasswordAttributes - Indicates whether password attributes should have their value
hidden from the returned String.public java.lang.String toString(boolean isHideValueOfPasswordAttributes,
boolean isDetailedCursor)
isHideValueOfPasswordAttributes - Indicates whether password attributes should have their value
hidden from the returned String.isDetailedCursor - Indicates whether the connector cursor should have its full value included
in the returned String.public java.lang.String toShortString()