com.unboundid.directory.sdk.sync.api

Class SyncDestination

java.lang.Object

com.unboundid.directory.sdk.sync.api.SyncDestination

All Implemented Interfaces:

Configurable, ExampleUsageProvider, UnboundIDExtension

@Extensible
 @SynchronizationServerExtension(appliesToLocalContent=false,
                                appliesToSynchronizedContent=true)
 @ThreadSafety(level=INTERFACE_THREADSAFE)
public abstract class SyncDestination
extends java.lang.Object
implements UnboundIDExtension, Configurable, ExampleUsageProvider

This class defines an API that must be implemented by 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 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 third-party \
           --set "extension-class:{class-name}" \
           --set "extension-argument:{name=value}"
 

where "{name}" is the name to use for the sync destination instance, "{class-name}" is the fully-qualified name of the Java class that extends com.unboundid.directory.sdk.sync.api.SyncDestination, 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 extension-argument:{name=value}" option should be provided multiple times.

See Also:

ScriptedSyncDestination

Constructor Summary

Constructors

Constructor and Description
SyncDestination() Creates a new instance of this notification destination.

Method Summary

Modifier and Type	Method and Description
abstract void	createEntry(Entry entryToCreate, SyncOperation operation) Creates a full destination "entry", corresponding to the LDAP Entry that is passed in.
void	defineConfigArguments(ArgumentParser parser) Updates the provided argument parser to define any configuration arguments which may be used by this extension.
abstract void	deleteEntry(Entry entryToDelete, SyncOperation operation) Delete a full "entry" from the destination, corresponding to the LDAP Entry that is passed in.
java.util.List<Entry>	fetchEntry(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.
java.util.Map<java.util.List<java.lang.String>,java.lang.String>	getExamplesArgumentSets() Retrieves a map containing examples of configurations that may be used for this extension.
abstract java.lang.String[]	getExtensionDescription() Retrieves a human-readable description for this extension.
abstract java.lang.String	getExtensionName() Retrieves a human-readable name for this extension.
void	initializeSyncDestination(SyncServerContext serverContext, SyncDestinationConfig config, ArgumentParser parser) Initializes this sync destination.
abstract void	modifyEntry(Entry entryToModify, java.util.List<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

SyncDestination

public SyncDestination()

Creates a new instance of this notification destination. All implementations must include a default constructor, but any initialization should generally be done in the initializeSyncDestination(com.unboundid.directory.sdk.sync.types.SyncServerContext, com.unboundid.directory.sdk.sync.config.SyncDestinationConfig, com.unboundid.util.args.ArgumentParser) method.

Method Detail

getExtensionName

public abstract java.lang.String getExtensionName()

Retrieves a human-readable name for this extension.

Specified by:

getExtensionName in interface UnboundIDExtension

Returns:

A human-readable name for this extension.

getExtensionDescription

public abstract java.lang.String[] getExtensionDescription()

Retrieves a human-readable description for this extension. Each element of the array that is returned will be considered a separate paragraph in generated documentation.

Specified by:

getExtensionDescription in interface UnboundIDExtension

Returns:

A human-readable description for this extension, or null or an empty array if no description should be available.

getExamplesArgumentSets

public java.util.Map<java.util.List<java.lang.String>,java.lang.String> getExamplesArgumentSets()

Retrieves a map containing examples of configurations that may be used for this extension. The map key should be a list of sample arguments, and the corresponding value should be a description of the behavior that will be exhibited by the extension when used with that configuration.

Specified by:

getExamplesArgumentSets in interface ExampleUsageProvider

Returns:

A map containing examples of configurations that may be used for this extension. It may be null or empty if there should not be any example argument sets.

defineConfigArguments

public void defineConfigArguments(ArgumentParser parser)
                           throws 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:

ArgumentException - If a problem is encountered while updating the provided argument parser.

initializeSyncDestination

public void initializeSyncDestination(SyncServerContext serverContext,
                                      SyncDestinationConfig config,
                                      ArgumentParser parser)
                               throws EndpointException

Initializes this sync destination. This hook 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<Entry> fetchEntry(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(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(Entry entryToModify,
                                 java.util.List<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 destination entry mapped from the source entry, before changes are applied.

modsToApply - a list of Modification objects which should be applied; these will have any configured attribute mappings already applied

operation - the sync operation for this change

Throws:

EndpointException - if there is an error modifying the entry

deleteEntry

public abstract void deleteEntry(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