com.unboundid.directory.sdk.sync.scripting

Class ScriptedSyncDestination

java.lang.Object

com.unboundid.directory.sdk.sync.scripting.ScriptedSyncDestination

All Implemented Interfaces:

Configurable

@Extensible
 @SynchronizationServerExtension(appliesToLocalContent=false,
                                appliesToSynchronizedContent=true)
 @ThreadSafety(level=MOSTLY_THREADSAFE)
public abstract class ScriptedSyncDestination
extends java.lang.Object
implements Configurable

This class defines an API that must be implemented by scripted extensions that wish to push changes processed by the Data Sync Server to an arbitrary destination. This type of sync destination is generic and can support a wide range of endpoints. In addition, this type of sync destination supports one-way notifications, where the source and destination entries are never compared but instead changes are pushed straight through.

Configuring Scripted Sync Destinations

In order to configure a sync destination created using this API, use a command like:

      dsconfig create-sync-destination \
           --sync-destination-name "{name}" \
           --type groovy-scripted \
           --set "script-class:{class-name}" \
           --set "script-argument:{name=value}"
 

where "{name}" is the name to use for the sync destination instance, "{script-name}" is the fully-qualified name of the Java class that extends com.unboundid.directory.sdk.sync.scripting.ScriptedSyncDestination, and "{name=value}" represents name-value pairs for any arguments to provide to the sync destination. If multiple arguments should be provided to extension, then the "--set script-argument:{name=value}" option should be provided multiple times.

See Also:

SyncDestination

Constructor Summary

Constructors

Constructor and Description
ScriptedSyncDestination()

Method Summary

Modifier and Type	Method and Description
abstract void	createEntry(com.unboundid.ldap.sdk.Entry entryToCreate, SyncOperation operation) Creates a full destination "entry", corresponding to the LDAP Entry that is passed in.
void	defineConfigArguments(com.unboundid.util.args.ArgumentParser parser) Updates the provided argument parser to define any configuration arguments which may be used by this extension.
abstract void	deleteEntry(com.unboundid.ldap.sdk.Entry entryToDelete, SyncOperation operation) Delete a full "entry" from the destination, corresponding to the LDAP Entry that is passed in.
java.util.List<com.unboundid.ldap.sdk.Entry>	fetchEntry(com.unboundid.ldap.sdk.Entry destEntryMappedFromSrc, SyncOperation operation) Return a full destination entry (in LDAP form) from the destination endpoint, corresponding to the source Entry that is passed in.
void	finalizeSyncDestination() This hook is called when a Sync Pipe shuts down, or when the resync process shuts down.
abstract java.lang.String	getCurrentEndpointURL() Return the URL or path identifying the destination endpoint to which this extension is transmitting data.
void	initializeSyncDestination(SyncServerContext serverContext, SyncDestinationConfig config, com.unboundid.util.args.ArgumentParser parser) Initializes this sync destination.
abstract void	modifyEntry(com.unboundid.ldap.sdk.Entry entryToModify, java.util.List<com.unboundid.ldap.sdk.Modification> modsToApply, SyncOperation operation) Modify an "entry" on the destination, corresponding to the LDAP Entry that is passed in.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ScriptedSyncDestination

public ScriptedSyncDestination()

Method Detail

defineConfigArguments

public void defineConfigArguments(com.unboundid.util.args.ArgumentParser parser)
                           throws com.unboundid.util.args.ArgumentException

Updates the provided argument parser to define any configuration arguments which may be used by this extension. The argument parser may also be updated to define relationships between arguments (e.g., to specify required, exclusive, or dependent argument sets).

Specified by:

defineConfigArguments in interface Configurable

Parameters:

parser - The argument parser to be updated with the configuration arguments which may be used by this extension.

Throws:

com.unboundid.util.args.ArgumentException - If a problem is encountered while updating the provided argument parser.

initializeSyncDestination

public void initializeSyncDestination(SyncServerContext serverContext,
                                      SyncDestinationConfig config,
                                      com.unboundid.util.args.ArgumentParser parser)
                               throws EndpointException

Initializes this sync destination. This is called when a Sync Pipe first starts up, or when the resync process first starts up. Any initialization should be performed here. This method should generally store the SyncServerContext in a class member so that it can be used elsewhere in the implementation.

The default implementation is empty.

Parameters:

serverContext - A handle to the server context for the server in which this extension is running. Extensions should typically store this in a class member.

config - The general configuration for this object.

parser - The argument parser which has been initialized from the configuration for this sync destination.

Throws:

EndpointException - if a problem occurs while initializing this sync destination.

finalizeSyncDestination

public void finalizeSyncDestination()

This hook is called when a Sync Pipe shuts down, or when the resync process shuts down. Any clean-up of this sync destination should be performed here.

The default implementation is empty.

getCurrentEndpointURL

public abstract java.lang.String getCurrentEndpointURL()

Return the URL or path identifying the destination endpoint to which this extension is transmitting data. This is used for logging purposes only, so it could just be a server name or hostname and port, etc.

Returns:

the path to the destination endpoint

fetchEntry

public java.util.List<com.unboundid.ldap.sdk.Entry> fetchEntry(com.unboundid.ldap.sdk.Entry destEntryMappedFromSrc,
                                                               SyncOperation operation)
                                                        throws EndpointException

Return a full destination entry (in LDAP form) from the destination endpoint, corresponding to the source Entry that is passed in. This method should perform any queries necessary to gather the latest values for all the attributes to be synchronized and return them in an Entry.

This method only needs to be implemented if the 'synchronization-mode' on the Sync Pipe is set to 'standard'. If it is set to 'notification', this method will never be called, and the pipe will pass changes straight through to one of createEntry(com.unboundid.ldap.sdk.Entry, com.unboundid.directory.sdk.sync.types.SyncOperation), modifyEntry(com.unboundid.ldap.sdk.Entry, java.util.List<com.unboundid.ldap.sdk.Modification>, com.unboundid.directory.sdk.sync.types.SyncOperation), or deleteEntry(com.unboundid.ldap.sdk.Entry, com.unboundid.directory.sdk.sync.types.SyncOperation).

Note that the if the source entry was renamed (see SyncOperation.isModifyDN()), the destEntryMappedFromSrc will have the new DN; the old DN can be obtained by calling SyncOperation.getDestinationEntryBeforeChange() and getting the DN from there. This method should return the entry in its existing form (i.e. with the old DN, before it is changed).

This method must be thread safe, as it will be called repeatedly and concurrently by each of the Sync Pipe worker threads as they process entries.

Parameters:

destEntryMappedFromSrc - the LDAP entry which corresponds to the destination "entry" to fetch

operation - the sync operation for this change

Returns:

a list containing the full LDAP entries that matched this search (there may be more than one), or an empty list if no such entry exists

Throws:

EndpointException - if there is an error fetching the entry

createEntry

public abstract void createEntry(com.unboundid.ldap.sdk.Entry entryToCreate,
                                 SyncOperation operation)
                          throws EndpointException

Creates a full destination "entry", corresponding to the LDAP Entry that is passed in. This method is responsible for transforming the contents of the entry into the desired format and transmitting it to the target destination. It should perform any inserts or updates necessary to make sure the entry is fully created on the destination endpoint.

This method must be thread safe, as it will be called repeatedly and concurrently by the Sync Pipe worker threads as they process CREATE operations.

Parameters:

entryToCreate - the LDAP entry which corresponds to the destination "entry" to create

operation - the sync operation for this change

Throws:

EndpointException - if there is an error creating the entry

modifyEntry

public abstract void modifyEntry(com.unboundid.ldap.sdk.Entry entryToModify,
                                 java.util.List<com.unboundid.ldap.sdk.Modification> modsToApply,
                                 SyncOperation operation)
                          throws EndpointException

Modify an "entry" on the destination, corresponding to the LDAP Entry that is passed in. This method is responsible for transforming the contents of the entry into the desired format and transmitting it to the target destination. It may perform multiple updates (including inserting or deleting other attributes) in order to fully synchronize the entire entry on the destination endpoint.

Note that the if the source entry was renamed (see SyncOperation.isModifyDN()), the fetchedDestEntry will have the old DN; the new DN can be obtained by calling SyncOperation.getDestinationEntryAfterChange() and getting the DN from there.

This method must be thread safe, as it will be called repeatedly and concurrently by the Sync Pipe worker threads as they process MODIFY operations.

Parameters:

entryToModify - the LDAP entry which corresponds to the destination "entry" to modify. If the synchronization mode is 'standard', this will be the entry that was returned by fetchEntry(com.unboundid.ldap.sdk.Entry, com.unboundid.directory.sdk.sync.types.SyncOperation); otherwise if the synchronization mode is 'notification', this will be the mapped destination entry.

modsToApply - a list of Modification objects which should be applied

operation - the sync operation for this change

Throws:

EndpointException - if there is an error modifying the entry

deleteEntry

public abstract void deleteEntry(com.unboundid.ldap.sdk.Entry entryToDelete,
                                 SyncOperation operation)
                          throws EndpointException

Delete a full "entry" from the destination, corresponding to the LDAP Entry that is passed in. This method may perform multiple deletes or updates if necessary to fully delete the entry from the destination endpoint.

This method must be thread safe, as it will be called repeatedly and concurrently by the Sync Pipe worker threads as they process DELETE operations.

Parameters:

entryToDelete - the LDAP entry which corresponds to the destination "entry" to delete. If the synchronization mode is 'standard', this will be the entry that was returned by fetchEntry(com.unboundid.ldap.sdk.Entry, com.unboundid.directory.sdk.sync.types.SyncOperation); otherwise if the synchronization mode is 'notification', this will be the mapped destination entry.

operation - the sync operation for this change

Throws:

EndpointException - if there is an error deleting the entry