Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

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

java.lang.Object
  extended by com.unboundid.directory.sdk.sync.api.JDBCSyncDestination
All Implemented Interfaces:
Configurable, ExampleUsageProvider, UnboundIDExtension
@Extensible
@SynchronizationServerExtension(appliesToLocalContent=false,
                                appliesToSynchronizedContent=true)
public abstract class JDBCSyncDestination
extends java.lang.Object
implements UnboundIDExtension, Configurable, ExampleUsageProvider

This class defines an API that must be implemented by extensions in order to synchronize data into a relational database. Since the UnboundID Synchronization Server is LDAP-centric, this API allows you to take LDAP entries and split them out into database content and make the appropriate updates. The lifecycle of a sync operation is as follows:

  1. Detect change at the synchronization source
  2. Fetch full source entry
  3. Perform any mappings and compute the equivalent destination entry
  4. Fetch full destination entry
  5. Diff the computed destination entry and actual destination entry
  6. Apply the minimal set of changes at the destination to bring it in sync
This implies that the fetchEntry(TransactionContext, Entry, SyncOperation) method will always be called once prior to any of the other methods in this class.

In several places a TransactionContext is provided, which allows controlled access to the target database. By default, methods in this class are always provided with a fresh connection (i.e. a new transaction), and the Synchronization Server will always commit or rollback the transaction automatically, depending on whether the method returned normally or threw an exception. Implementers may optionally perform their own transaction management within these methods if necessary.

Several of these methods throw SQLException, which should be used in the case of any database access error. For other types of errors, runtime exceptions may be used (IllegalStateException, NullPointerException, etc.). The Synchronization Server will automatically retry operations that fail, up to a configurable amount of attempts. The exception to this rule is if a SQLException is thrown with a SQL state string beginning with "08"; this indicates a connection error, and in this case the operation is retried indefinitely.

Configuring JDBC Sync Destinations

In order to configure a JDBC sync destination based on this API and written in Java, use a command like: 
      dsconfig create-sync-destination \
           --destination-name "{destination-name}" \
           --type third-party-jdbc \
           --set "server:{server-name}" \
           --set "extension-class:{class-name}" \
           --set "extension-argument:{name=value}"
where "{destination-name}" is the name to use for the JDBC sync destination instance, "{server-name}" is the name of the JDBC external server that will be used as the sync destination, "{class-name}" is the fully-qualified name of the Java class written using this API, and "{name=value}" represents name-value pairs for any arguments to provide to the JDBC sync destination. If multiple arguments should be provided to the JDBC sync destination, then the "--set extension-argument:{name=value}" option should be provided multiple times.

Constructor Summary
JDBCSyncDestination()
          Creates a new instance of this JDBC Sync Destination.
 
Method Summary
abstract  void createEntry(TransactionContext ctx, com.unboundid.ldap.sdk.Entry entryToCreate, SyncOperation operation)
          Creates a full database "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(TransactionContext ctx, com.unboundid.ldap.sdk.Entry fetchedDestEntry, SyncOperation operation)
          Delete a full "entry" from the database, corresponding to the the LDAP Entry that is passed in.
abstract  com.unboundid.ldap.sdk.Entry fetchEntry(TransactionContext ctx, com.unboundid.ldap.sdk.Entry destEntryMappedFromSrc, SyncOperation operation)
          Return a full destination entry (in LDAP form) from the database, corresponding to the the source Entry that is passed in.
 void finalizeJDBCSyncDestination(TransactionContext ctx)
          This hook is called when a Sync Pipe shuts down, or when the resync process shuts down.
 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 initializeJDBCSyncDestination(TransactionContext ctx, SyncServerContext serverContext, JDBCSyncDestinationConfig config, com.unboundid.util.args.ArgumentParser parser)
          This hook is called when a Sync Pipe first starts up, or when the resync process first starts up.
abstract  void modifyEntry(TransactionContext ctx, com.unboundid.ldap.sdk.Entry fetchedDestEntry, java.util.List<com.unboundid.ldap.sdk.Modification> modsToApply, SyncOperation operation)
          Modify an "entry" in the database, 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

JDBCSyncDestination

public JDBCSyncDestination()
Creates a new instance of this JDBC Sync Destination. All sync destination implementations must include a default constructor, but any initialization should generally be done in the initializeJDBCSyncDestination(com.unboundid.directory.sdk.sync.types.TransactionContext, com.unboundid.directory.sdk.sync.types.SyncServerContext, com.unboundid.directory.sdk.sync.config.JDBCSyncDestinationConfig, 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.

initializeJDBCSyncDestination

@ThreadSafety(level=METHOD_NOT_THREADSAFE)
public void initializeJDBCSyncDestination(TransactionContext ctx,
                                                       SyncServerContext serverContext,
                                                       JDBCSyncDestinationConfig config,
                                                       com.unboundid.util.args.ArgumentParser parser)
This hook is called when a Sync Pipe first starts up, or when the resync process first starts up. Any initialization of this sync destination 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.

A TransactionContext is provided, which allows controlled access to the target database. The context will contain a fresh fresh connection (i.e. a new transaction), and the Synchronization Server will always commit or rollback the transaction automatically, depending on whether this method returns normally or throws an exception. Implementers may optionally perform their own transaction management within this method if necessary.

The default implementation is empty.

Parameters:
ctx - a TransactionContext which provides a valid JDBC connection to the database.
serverContext - A handle to the server context for the server in which this extension is running.
config - The general configuration for this sync destination.
parser - The argument parser which has been initialized from the configuration for this JDBC sync destination.

finalizeJDBCSyncDestination

@ThreadSafety(level=METHOD_NOT_THREADSAFE)
public void finalizeJDBCSyncDestination(TransactionContext ctx)
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.

A TransactionContext is provided, which allows controlled access to the target database. The context will contain a fresh fresh connection (i.e. a new transaction), and the Synchronization Server will always commit or rollback the transaction automatically, depending on whether this method returns normally or throws an exception. Implementers may optionally perform their own transaction management within this method if necessary.

The default implementation is empty.

Parameters:
ctx - a TransactionContext which provides a valid JDBC connection to the database.

fetchEntry

@ThreadSafety(level=METHOD_THREADSAFE)
public abstract com.unboundid.ldap.sdk.Entry fetchEntry(TransactionContext ctx,
                                                                     com.unboundid.ldap.sdk.Entry destEntryMappedFromSrc,
                                                                     SyncOperation operation)
                                                 throws java.sql.SQLException
Return a full destination entry (in LDAP form) from the database, 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.

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).

A TransactionContext is provided, which allows controlled access to the target database. The context will contain a fresh fresh connection (i.e. a new transaction), and the Synchronization Server will always commit or rollback the transaction automatically, depending on whether this method returns normally or throws an exception. Implementers may optionally perform their own transaction management within this method if necessary.

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:
ctx - a TransactionContext which provides a valid JDBC connection to the database.
destEntryMappedFromSrc - the LDAP entry which corresponds to the database "entry" to fetch
operation - the sync operation for this change
Returns:
a full LDAP Entry, or null if no such entry exists.
Throws:
java.sql.SQLException - if there is an error fetching the entry

createEntry

@ThreadSafety(level=METHOD_THREADSAFE)
public abstract void createEntry(TransactionContext ctx,
                                              com.unboundid.ldap.sdk.Entry entryToCreate,
                                              SyncOperation operation)
                          throws java.sql.SQLException
Creates a full database "entry", corresponding to the the LDAP Entry that is passed in. This method should perform any inserts and updates necessary to make sure the entry is fully created on the database.

A TransactionContext is provided, which allows controlled access to the target database. The context will contain a fresh fresh connection (i.e. a new transaction), and the Synchronization Server will always commit or rollback the transaction automatically, depending on whether this method returns normally or throws an exception. Implementers may optionally perform their own transaction management within this method if necessary.

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:
ctx - a TransactionContext which provides a valid JDBC connection to the database.
entryToCreate - the LDAP entry which corresponds to the database "entry" to create
operation - the sync operation for this change
Throws:
java.sql.SQLException - if there is an error creating the entry

modifyEntry

@ThreadSafety(level=METHOD_THREADSAFE)
public abstract void modifyEntry(TransactionContext ctx,
                                              com.unboundid.ldap.sdk.Entry fetchedDestEntry,
                                              java.util.List<com.unboundid.ldap.sdk.Modification> modsToApply,
                                              SyncOperation operation)
                          throws java.sql.SQLException
Modify an "entry" in the database, corresponding to the the LDAP Entry that is passed in. This method may perform multiple updates (including inserting or deleting rows) in order to fully synchronize the entire entry on the database.

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.

A TransactionContext is provided, which allows controlled access to the target database. The context will contain a fresh fresh connection (i.e. a new transaction), and the Synchronization Server will always commit or rollback the transaction automatically, depending on whether this method returns normally or throws an exception. Implementers may optionally perform their own transaction management within this method if necessary.

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:
ctx - a TransactionContext which provides a valid JDBC connection to the database.
fetchedDestEntry - the LDAP entry which corresponds to the database "entry" to modify
modsToApply - a list of Modification objects which should be applied
operation - the sync operation for this change
Throws:
java.sql.SQLException - if there is an error modifying the entry

deleteEntry

@ThreadSafety(level=METHOD_THREADSAFE)
public abstract void deleteEntry(TransactionContext ctx,
                                              com.unboundid.ldap.sdk.Entry fetchedDestEntry,
                                              SyncOperation operation)
                          throws java.sql.SQLException
Delete a full "entry" from the database, 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 database.

A TransactionContext is provided, which allows controlled access to the target database. The context will contain a fresh fresh connection (i.e. a new transaction), and the Synchronization Server will always commit or rollback the transaction automatically, depending on whether this method returns normally or throws an exception. Implementers may optionally perform their own transaction management within this method if necessary.

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:
ctx - a TransactionContext which provides a valid JDBC connection to the database.
fetchedDestEntry - the LDAP entry which corresponds to the database "entry" to delete
operation - the sync operation for this change
Throws:
java.sql.SQLException - if there is an error deleting the entry
Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD