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

java.lang.Object
  extended by 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 Synchronization 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
SyncDestination()
          Creates a new instance of this notification destination.
 
Method Summary
abstract  void createEntry(com.unboundid.ldap.sdk.Entry entryToCreate, SyncOperation operation)
          Creates a full destination "entry", corresponding to the 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 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 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, 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 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(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 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<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 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.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 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 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(com.unboundid.ldap.sdk.Entry entryToDelete,
                                 SyncOperation operation)
                          throws EndpointException
Delete a full "entry" from the destination, corresponding to the 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