/*
 * CDDL HEADER START
 *
 * The contents of this file are subject to the terms of the
 * Common Development and Distribution License, Version 1.0 only
 * (the "License").  You may not use this file except in compliance
 * with the License.
 *
 * You can obtain a copy of the license at
 * docs/licenses/cddl.txt
 * or http://www.opensource.org/licenses/cddl1.php.
 * See the License for the specific language governing permissions
 * and limitations under the License.
 *
 * When distributing Covered Code, include this CDDL HEADER in each
 * file and include the License file at
 * docs/licenses/cddl.txt.  If applicable,
 * add the following below this CDDL HEADER, with the fields enclosed
 * by brackets "[]" replaced with your own identifying information:
 *      Portions Copyright [yyyy] [name of copyright owner]
 *
 * CDDL HEADER END
 *
 *
 *      Copyright 2010-2021 Ping Identity Corporation
 */
package com.unboundid.directory.sdk.sync.scripting;

import java.io.Serializable;
import java.sql.SQLException;
import java.util.LinkedList;
import java.util.List;
import java.util.Iterator;
import java.util.concurrent.BlockingQueue;
import java.util.concurrent.atomic.AtomicLong;

import com.unboundid.ldap.sdk.Entry;
import com.unboundid.util.Extensible;
import com.unboundid.util.ThreadSafety;
import com.unboundid.util.ThreadSafetyLevel;
import com.unboundid.util.args.ArgumentException;
import com.unboundid.util.args.ArgumentParser;
import com.unboundid.directory.sdk.common.internal.Configurable;
import com.unboundid.directory.sdk.sync.config.JDBCSyncSourceConfig;
import com.unboundid.directory.sdk.sync.internal.SynchronizationServerExtension;
import com.unboundid.directory.sdk.sync.types.DatabaseChangeRecord;
import com.unboundid.directory.sdk.sync.types.SetStartpointOptions;
import com.unboundid.directory.sdk.sync.types.SyncOperation;
import com.unboundid.directory.sdk.sync.types.SyncServerContext;
import com.unboundid.directory.sdk.sync.types.TransactionContext;

/**
 * This class defines an API that must be implemented by scripted extensions
 * in order to synchronize data out of a relational database. Since the
 * Ping Identity Data Sync Server is LDAP-centric,
 * this API allows you to take database content and convert it into LDAP
 * entries which can then be processed by the Data Sync Server. The
 * lifecycle of
 * a sync operation is as follows:
 * <ol>
 * <li>Detect change at the synchronization source</li>
 * <li>Fetch full source entry</li>
 * <li>Perform any mappings and compute the equivalent destination entry</li>
 * <li>Fetch full destination entry</li>
 * <li>Diff the computed destination entry and actual (fetched) destination
 * entry</li>
 * <li>Apply the minimal set of changes at the destination to bring it in sync
 * </li>
 * </ol>
 * This implies that the
 * {@link #fetchEntry(TransactionContext, SyncOperation)} method will be
 * called once for every change that is returned by
 * {@link #getNextBatchOfChanges(TransactionContext, int, AtomicLong)}.
 * <p>
 * During realtime synchronization (i.e. when a Sync Pipe is running), there is
 * a sliding window of changes being processed, and this API provides a
 * distinction between some different points along that window:
 * <ul>
 *   <li><b>Old changes</b>: These are changes that the Sync Server has
 *       processed and acknowledged back to the Sync Source. The Sync Source is
 *       under no obligation to re-detect these changes.</li>
 *   <li><b>Startpoint</b>: This marks where the Sync Source will start
 *       detecting changes if it is restarted.</li>
 *   <li><b>Detected but unacknowledged</b>: These changes have been returned by
 *       <code>getNextBatchOfChanges()</code> but not completely processed and
 *       acknowledged back to the Sync Source.</li>
 *   <li><b>Undetected changes</b>: The next call to
 *       <code>getNextBatchOfChanges()</code> should return the first changes
 *       that have not been detected.  This should be somewhere at or ahead of
 *       the startpoint.</li>
 * </ul>
 * <p>
 * In several places a {@link 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
 * Data Sync 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.
 * <p>
 * Several of these methods throw {@link 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 Data Sync 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.
 * <BR>
 * <H2>Configuring Groovy Scripted JDBC Sync Sources</H2>
 * In order to configure a scripted JDBC sync source based on this API and
 * written in the Groovy scripting language, use a command like:
 * <PRE>
 *      dsconfig create-sync-source \
 *           --source-name "<I>{source-name}</I>" \
 *           --type groovy-scripted-jdbc \
 *           --set "server:{server-name}" \
 *           --set "script-class:<I>{class-name}</I>" \
 *           --set "script-argument:<I>{name=value}</I>"
 * </PRE>
 * where "<I>{source-name}</I>" is the name to use for the JDBC sync source
 * instance, "<I>{server-name}</I>" is the name of the JDBC external server that
 * will be used as the sync source, "<I>{class-name}</I>" is the fully-qualified
 * name of the Groovy class written using this API, and "<I>{name=value}</I>"
 * represents name-value pairs for any arguments to provide to the JDBC sync
 * source.  If multiple arguments should be provided to the JDBC sync source,
 * then the "<CODE>--set script-argument:<I>{name=value}</I></CODE>" option
 * should be provided multiple times.
 */
@Extensible()
@SynchronizationServerExtension(appliesToLocalContent=false,
                                appliesToSynchronizedContent=true)
public abstract class ScriptedJDBCSyncSource implements Configurable
{
  /**
   * {@inheritDoc}
   */
  public void defineConfigArguments(final ArgumentParser parser)
         throws ArgumentException
  {
    // No arguments will be allowed by default.
  }

  /**
   * This hook is called when a Sync Pipe first starts up, when the
   * <i>resync</i> process first starts up, or when the set-startpoint
   * subcommand is called from the <i>realtime-sync</i> command line tool.
   * Any initialization of this sync source should be performed here. This
   * method should generally store the {@link SyncServerContext} in a class
   * member so that it can be used elsewhere in the implementation.
   * <p>
   * A {@link 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 Data Sync 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.
   * <p>
   * The default implementation is empty.
   *
   * @param ctx
   *          a TransactionContext which provides a valid JDBC connection to the
   *          database.
   * @param  serverContext  A handle to the server context for the server in
   *                        which this extension is running.
   * @param  config         The general configuration for this sync source.
   * @param  parser         The argument parser which has been initialized from
   *                        the configuration for this JDBC sync source.
   */
  public void initializeJDBCSyncSource(final TransactionContext ctx,
                                          final SyncServerContext serverContext,
                                          final JDBCSyncSourceConfig config,
                                          final ArgumentParser parser)
  {
    // No initialization will be performed by default.
  }

  /**
   * This hook is called when a Sync Pipe shuts down, when the <i>resync</i>
   * process shuts down, or when the set-startpoint subcommand (from the
   * <i>realtime-sync</i> command line tool) is finished. Any clean up of this
   * sync source should be performed here.
   * <p>
   * A {@link 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 Data Sync 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.
   * <p>
   * The default implementation is empty.
   *
   * @param ctx
   *          a TransactionContext which provides a valid JDBC connection to the
   *          database.
   */
  public void finalizeJDBCSyncSource(final TransactionContext ctx)
  {
    //no implementation required
  }

  /**
   * This method should effectively set the starting point for synchronization
   * to the place specified by the <code>options</code> parameter. This should
   * cause all changes previous to the specified start point to be disregarded
   * and only changes after that point to be returned by
   * {@link #getNextBatchOfChanges(TransactionContext, int, AtomicLong)}.
   * <p>
   * There are several different startpoint types (see
   * {@link SetStartpointOptions}), and this implementation is not required to
   * support them all. If the specified startpoint type is unsupported, this
   * method should throw an {@link UnsupportedOperationException}.
   * <p>
   * <b>IMPORTANT</b>: The <code>RESUME_AT_SERIALIZABLE</code> startpoint type
   * must be supported by your implementation, because this is used when a Sync
   * Pipe first starts up.
   * <p>
   * This method can be called from two different contexts:
   * <ul>
   * <li>When the 'set-startpoint' subcommand of the realtime-sync CLI is used
   * (the Sync Pipe is required to be stopped in this context)</li>
   * <li>Immediately after a Sync Pipe starts up and a connection is first
   *     established to the source server (e.g. before the first call to
   * {@link #getNextBatchOfChanges(TransactionContext, int, AtomicLong)})</li>
   * </ul>
   * <p>
   * A {@link 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 Data Sync 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.
   *
   * @param ctx
   *          a TransactionContext which provides a valid JDBC connection to the
   *          database.
   * @param options
   *          an object which indicates where exactly to start synchronizing
   *          (e.g.
   *          the end of the changelog, specific change number, a certain time
   *          ago, etc)
   * @throws SQLException
   *           if there is any error while setting the start point
   */
  @ThreadSafety(level = ThreadSafetyLevel.METHOD_NOT_THREADSAFE)
  public abstract void setStartpoint(final TransactionContext ctx,
                                     final SetStartpointOptions options)
                                          throws SQLException;

  /**
   * Gets the current value of the startpoint for change detection. This is the
   * "bookmark" which indicates which changes have already been processed and
   * which have not. In most cases, a change number is used to detect changes
   * and is managed by the Data Sync Server, in which case this
   * implementation needs only to return the latest acknowledged
   * change number. In other cases, the return value may correspond to a
   * different value, such as the SYS_CHANGE_VERSION in Microsoft SQL Server.
   * In any case, this method should return the value that is updated by
   * {@link #acknowledgeCompletedOps(TransactionContext, LinkedList)}.
   * <p>
   * This method is called periodically and the return value is saved in the
   * persistent state for the Sync Pipe that uses this script as its Sync
   * Source.
   * <p>
   * <b>IMPORTANT</b>: The internal value for the startpoint should only be
   * updated after a sync operation is acknowledged back to this script (via
   * {@link #acknowledgeCompletedOps(TransactionContext, LinkedList)}).
   * Otherwise it will be possible for changes to be missed when the
   * Data Sync Server is restarted or a connection error occurs.
   * @return a value to store in the persistent state for the Sync Pipe. This is
   *         usually
   *         a change number, but if a changelog table is not used to detect
   *         changes,
   *         this value should represent some other token to pass into
   *         {@link #setStartpoint(TransactionContext, SetStartpointOptions)}
   *         when the sync pipe starts up.
   */
  @ThreadSafety(level = ThreadSafetyLevel.METHOD_NOT_THREADSAFE)
  public abstract Serializable getStartpoint();

  /**
   * Return the next batch of change records from the database. Change records
   * are just hints that a change happened; they do not include the actual data
   * of the change. In an effort to never synchronize stale data, the
   * Data Sync Server will go back and fetch the full source entry for
   * each change record.
   * <p>
   * On the first invocation, this should return changes starting from the
   * startpoint that was set by
   * {@link #setStartpoint(TransactionContext, SetStartpointOptions)}. This
   * method is responsible for updating the internal state such that subsequent
   * invocations do not return duplicate changes.
   * <p>
   * The resulting list should be limited by <code>maxChanges</code>. The
   * <code>numStillPending</code> reference should be set to the estimated
   * number of changes that haven't yet been retrieved from the changelog table
   * when this method returns, or zero if all the current changes have been
   * retrieved.
   * <p>
   * <b>IMPORTANT</b>: While this method needs to keep track of which changes
   * have already been returned so that it does not return them again, it should
   * <b>NOT</b> modify the official startpoint. The internal value for the
   * startpoint should only be updated after a sync operation is acknowledged
   * back to this script (via
   * {@link #acknowledgeCompletedOps(TransactionContext, LinkedList)}).
   * Otherwise it will be possible for changes to be missed when the
   * Data Sync Server is restarted or a connection error occurs. The
   * startpoint should not change as a result of this method.
   * <p>
   * A {@link 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 Data Sync 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.
   * <p>
   * This method <b>does not need to be thread-safe</b>. It will be invoked
   * repeatedly by a single thread, based on the polling interval set in the
   * Sync Pipe configuration.
   * @param ctx
   *          a TransactionContext which provides a valid JDBC connection to the
   *          database.
   * @param maxChanges
   *          the maximum number of changes to retrieve
   * @param numStillPending
   *          this should be set to the number of unretrieved changes that
   *          are still pending after this batch has been retrieved. This will
   *          be passed in
   *          as zero, and may be left that way if the actual value cannot be
   *          determined.
   * @return a list of {@link DatabaseChangeRecord} instances, each
   *         corresponding
   *         to a row in the changelog table (or the equivalent if some other
   *         change
   *         tracking mechanism is being used). If there are no new changes to
   *         return, this
   *         method should return an empty list.
   * @throws SQLException
   *           if there is any error while retrieving the next batch of changes
   */
  public abstract List<DatabaseChangeRecord> getNextBatchOfChanges(
                                              final TransactionContext ctx,
                                              final int maxChanges,
                                              final AtomicLong numStillPending)
                                                      throws SQLException;

  /**
   * Return a full source entry (in LDAP form) from the database, corresponding
   * to the {@link DatabaseChangeRecord} that is passed in through the
   * {@link SyncOperation}. This method should perform any queries necessary to
   * gather the latest values for all the attributes to be synchronized.
   * <p>
   * A {@link 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 Data Sync 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.
   * <p>
   * This method <b>must be thread safe</b>, as it will be called repeatedly and
   * concurrently by each of the Sync Pipe worker threads as they process
   * entries.
   * @param ctx
   *          a TransactionContext which provides a valid JDBC connection to the
   *          database.
   * @param operation
   *          the SyncOperation which identifies the database "entry" to
   *          fetch. The DatabaseChangeRecord can be obtained by calling
   *          <code>operation.getDatabaseChangeRecord()</code>.
   *          This is returned by
   *        {@link #getNextBatchOfChanges(TransactionContext, int, AtomicLong)}
   *          or by
   *        {@link #listAllEntries(TransactionContext, String, BlockingQueue)}
   *          .
   * @return a full LDAP Entry, or null if no such entry exists.
   * @throws SQLException
   *           if there is an error fetching the entry
   */
  public abstract Entry fetchEntry(final TransactionContext ctx,
                                   final SyncOperation operation)
                                            throws SQLException;

  /**
   * Provides a way for the Data Sync Server to acknowledge back to the
   * script which sync operations it has processed. This method should update
   * the official startpoint which was set by
   * {@link #setStartpoint(TransactionContext, SetStartpointOptions)} and is
   * returned by {@link #getStartpoint()}.
   * <p>
   * <b>IMPORTANT</b>: The internal value for the startpoint should only be
   * updated after a sync operation is acknowledged back to this script (via
   * this method). Otherwise it will be possible for changes to be missed when
   * the Data Sync Server is restarted or a connection error occurs.
   * <p>
   * A {@link TransactionContext} is provided in case the acknowledgment needs
   * to make it all the way back to the database itself (for example if you were
   * using Oracle's Change Data Capture). The context will contain a fresh
   * fresh connection (i.e. a new transaction), and the Data Sync 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.
   *
   * @param ctx
   *          a TransactionContext which provides a valid JDBC connection to the
   *          database.
   * @param completedOps
   *          a list of {@link SyncOperation}s that have finished processing.
   *          The records are listed in the order they were
   *          first detected.
   * @throws SQLException
   *           if there is an error acknowledging the changes back to the
   *           database
   */
  public abstract void acknowledgeCompletedOps(
                                   final TransactionContext ctx,
                                   final LinkedList<SyncOperation> completedOps)
                                             throws SQLException;

  /**
   * Performs a cleanup of the changelog table (if desired). There is a
   * background thread that periodically invokes this method. It should remove
   * any rows in the changelog table that are more than
   * <code>maxAgeMillis</code> milliseconds old.
   * <p>
   * <b>NOTE:</b> If the system clock on the database server is not in sync with
   * the system clock on the Data Sync Server, this method should query
   * the database for its current time in order to determine the cut-off point
   * for deleting changelog records.
   * <p>
   * A {@link 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 Data Sync 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.
   * <p>
   * If a separate mechanism will be used to manage the changelog table, this
   * method may be implemented as a no-op and always return zero. This is how
   * the default implementation behaves.
   * @param ctx
   *          a TransactionContext which provides a valid JDBC connection to the
   *          database.
   * @param maxAgeMillis
   *          the period of time (in milliseconds) after which a changelog table
   *          record should be deleted
   * @return the number of rows that were deleted from the changelog table
   * @throws SQLException
   *           if there is an error purging records from the changelog table
   */
  public int cleanupChangelog(final TransactionContext ctx,
                              final long maxAgeMillis)
                                  throws SQLException
  {
    //no implementation provided by default; this is an opt-in feature.
    return 0;
  }

  /**
   * Gets a list of all the entries in the database for a given entry type. This
   * is used by the 'resync' command line tool. The default implementation
   * throws a {@link UnsupportedOperationException}; subclasses should override
   * if the resync functionality is needed.
   * <p>
   * The <code>entryType</code> is user-defined; it will be
   * passed in on the command line for resync. The <code>outputQueue</code>
   * should contain {@link DatabaseChangeRecord} objects with the
   * <code>ChangeType</code> set to <i>resync</i>.
   * <p>
   * This method should not return until all the entries of the given entryType
   * have been added to the output queue. Separate threads will concurrently
   * drain entries from the queue and process them. The queue should not
   * actually contain full entries, but rather DatabaseChangeRecord objects
   * which identify the full database entries. These objects are then
   * individually passed in to
   * {@link #fetchEntry(TransactionContext, SyncOperation)}. Therefore,
   * it is important to make sure that the DatabaseChangeRecord instances
   * contain enough identifiable information (e.g. primary keys) for each entry
   * so that the entry can be found again.
   * <p>
   * The lifecycle of resync is similar to that of real-time sync, with a few
   * differences:
   * <ol>
   * <li>Stream out a list of all IDs in the database (for a given entryType)
   * </li>
   * <li>Fetch full source entry for an ID</li>
   * <li>Perform any mappings and compute the equivalent destination entry</li>
   * <li>Fetch full destination entry</li>
   * <li>Diff the computed destination entry and actual destination entry</li>
   * <li>Apply the minimal set of changes at the destination to bring it in sync
   * </li>
   * </ol>
   * If the total set of entries is very large, it is fine to split up the work
   * into multiple database queries within this method. The queue will not grow
   * out of control because it blocks when it becomes full. The queue capacity
   * is fixed at 1000.
   * <p>
   * A {@link 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 Data Sync 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.
   *
   * @param ctx
   *          a TransactionContext which provides a valid JDBC connection to the
   *          database.
   * @param entryType
   *          the type of database entry to be fetched (this is specified
   *          on the CLI for the resync command)
   * @param outputQueue
   *          a queue of DatabaseChangeRecord objects which will be individually
   *          fetched via
   *          {@link #fetchEntry(TransactionContext, SyncOperation)}
   * @throws SQLException
   *           if there is an error retrieving the list of entries to resync
   */
  public void listAllEntries(final TransactionContext ctx,
                             final String entryType,
                             final BlockingQueue<DatabaseChangeRecord>
                                      outputQueue) throws SQLException
  {
    throw new UnsupportedOperationException(
            "The listAllEntries(TransactionContext,String,BlockingQueue) " +
            "method must be implemented in the " +
            getClass().getName() + " extension.");
  }

  /**
   * Note: This method is deprecated and may be removed in a future release.
   * All new and existing code should be changed to use the version of this
   * method which includes the <code>entryType</code> parameter.
   * <p>
   * Gets a list of all the entries in the database from a given file input.
   * This is used by the 'resync' command line tool. The default implementation
   * throws a {@link UnsupportedOperationException}; subclasses should override
   * if the resync functionality is needed for specific database records, which
   * can be specified in the input file.
   * <p>
   * The format for the <code>inputLines</code> (e.g. the content of the file)
   * is user-defined; it may be key/value pairs, primary keys, or full SQL
   * statements, for example. The use of this method is triggered via the
   * <i>--sourceInputFile</i> argument on the resync CLI. The
   * <code>outputQueue</code> should contain {@link DatabaseChangeRecord}
   * objects with the <code>ChangeType</code> set to <i>resync</i>.
   * <p>
   * This method should not return until all the entries specified by the input
   * file have been added to the output queue. Separate threads will
   * concurrently drain entries from the queue and process them. The queue
   * should not actually contain full entries, but rather DatabaseChangeRecord
   * objects which identify the full database entries. These objects are then
   * individually passed in to
   * {@link #fetchEntry(TransactionContext, SyncOperation)}. Therefore,
   * it is important to make sure that the DatabaseChangeRecord instances
   * contain enough identifiable information (e.g. primary keys) for each entry
   * so that the entry can be found again.
   * <p>
   * The lifecycle of resync is similar to that of real-time sync, with a few
   * differences:
   * <ol>
   * <li>Stream out a list of all IDs in the database (using the given input
   *  file)</li>
   * <li>Fetch full source entry for an ID</li>
   * <li>Perform any mappings and compute the equivalent destination entry</li>
   * <li>Fetch full destination entry</li>
   * <li>Diff the computed destination entry and actual destination entry</li>
   * <li>Apply the minimal set of changes at the destination to bring it in sync
   * </li>
   * </ol>
   * If the total set of entries is very large, it is fine to split up the work
   * into multiple database queries within this method. The queue will not grow
   * out of control because it blocks when it becomes full. The queue capacity
   * is fixed at 1000.
   * <p>
   * A {@link 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 Data Sync 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.
   *
   * @param ctx
   *          a TransactionContext which provides a valid JDBC connection to the
   *          database.
   * @param inputLines
   *          an Iterator containing the lines from the specified input file to
   *          resync (this is specified on the CLI for the resync command).
   *          These lines can be any format, for example a set of primary keys,
   *          a set of WHERE clauses, a set of full SQL queries, etc.
   * @param outputQueue
   *          a queue of DatabaseChangeRecord objects which will be individually
   *          fetched via {@link #fetchEntry(TransactionContext, SyncOperation)}
   * @throws SQLException
   *           if there is an error retrieving the list of entries to resync
   */
  @Deprecated
  public void listAllEntries(final TransactionContext ctx,
                             final Iterator<String> inputLines,
                             final BlockingQueue<DatabaseChangeRecord>
                                      outputQueue) throws SQLException
  {
    throw new UnsupportedOperationException(
            "The listAllEntries(TransactionContext,Iterator,BlockingQueue) " +
            "method must be implemented in the " +
            getClass().getName() + " extension.");
  }

  /**
   * Gets a list of all the entries in the database from a given file input.
   * This is used by the 'resync' command line tool. The default implementation
   * throws a {@link UnsupportedOperationException}; subclasses should override
   * if the resync functionality is needed for specific database records, which
   * can be specified in the input file.
   * <p>
   * The format for the <code>inputLines</code> (e.g. the content of the file)
   * is user-defined; it may be key/value pairs, primary keys, or full SQL
   * statements, for example. The use of this method is triggered via the
   * <i>--sourceInputFile</i> argument on the resync CLI. The
   * <code>outputQueue</code> should contain {@link DatabaseChangeRecord}
   * objects with the <code>ChangeType</code> set to <i>resync</i>.
   * <p>
   * This method should not return until all the entries specified by the input
   * file have been added to the output queue. Separate threads will
   * concurrently drain entries from the queue and process them. The queue
   * should not actually contain full entries, but rather DatabaseChangeRecord
   * objects which identify the full database entries. These objects are then
   * individually passed in to
   * {@link #fetchEntry(TransactionContext, SyncOperation)}. Therefore,
   * it is important to make sure that the DatabaseChangeRecord instances
   * contain enough identifiable information (e.g. primary keys) for each entry
   * so that the entry can be found again.
   * <p>
   * The lifecycle of resync is similar to that of real-time sync, with a few
   * differences:
   * <ol>
   * <li>Stream out a list of all IDs in the database (using the given input
   *  file)</li>
   * <li>Fetch full source entry for an ID</li>
   * <li>Perform any mappings and compute the equivalent destination entry</li>
   * <li>Fetch full destination entry</li>
   * <li>Diff the computed destination entry and actual destination entry</li>
   * <li>Apply the minimal set of changes at the destination to bring it in sync
   * </li>
   * </ol>
   * If the total set of entries is very large, it is fine to split up the work
   * into multiple database queries within this method. The queue will not grow
   * out of control because it blocks when it becomes full. The queue capacity
   * is fixed at 1000.
   * <p>
   * A {@link 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 Data Sync 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.
   *
   * @param ctx
   *          a TransactionContext which provides a valid JDBC connection to the
   *          database.
   * @param entryType
   *          the type of database entry to be fetched (this is specified
   *          on the CLI for the resync command)
   * @param inputLines
   *          an Iterator containing the lines from the specified input file to
   *          resync (this is specified on the CLI for the resync command).
   *          These lines can be any format, for example a set of primary keys,
   *          a set of WHERE clauses, a set of full SQL queries, etc.
   * @param outputQueue
   *          a queue of DatabaseChangeRecord objects which will be individually
   *          fetched via {@link #fetchEntry(TransactionContext, SyncOperation)}
   * @throws SQLException
   *           if there is an error retrieving the list of entries to resync
   */
  public void listAllEntries(final TransactionContext ctx,
                             final String entryType,
                             final Iterator<String> inputLines,
                             final BlockingQueue<DatabaseChangeRecord>
                                      outputQueue) throws SQLException
  {
    throw new UnsupportedOperationException(
        "The listAllEntries(TransactionContext,String,Iterator,BlockingQueue) "+
        "method must be implemented in the " +
        getClass().getName() + " extension.");
  }
}