Package com.unboundid.directory.sdk.sync.api

Class 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

    • Method Detail

      • 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

      • 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