/*
 * The contents of this file are subject to the terms of the Common Development and
 * Distribution License (the License). You may not use this file except in compliance with the
 * License.
 *
 * You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the
 * specific language governing permission and limitations under the License.
 *
 * When distributing Covered Software, include this CDDL Header Notice in each file and include
 * the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL
 * Header, with the fields enclosed by brackets [] replaced by your own identifying
 * information: "Portions Copyright [year] [name of copyright owner]".
 *
 * Copyright 2013-2016 ForgeRock AS.
 */
package org.opends.server.replication.server.changelog.api;

import java.io.Closeable;
import java.util.Objects;

import net.jcip.annotations.NotThreadSafe;

import org.opends.server.replication.common.CSN;

/**
 * Generic cursor interface into the changelog database. Once it is not used
 * anymore, a cursor must be closed to release all the resources into the
 * database.
 * <p>
 * The cursor provides a java.sql.ResultSet like API : it is positioned before
 * the first requested record and needs to be moved forward by calling
 * {@link DBCursor#next()}.
 * <p>
 * Usage:
 * <pre>
 *  DBCursor cursor = ...;
 *  try {
 *    while (cursor.next()) {
 *      Record record = cursor.getRecord();
 *      // ... can call cursor.getRecord() again: it will return the same result
 *    }
 *  }
 *  finally {
 *    close(cursor);
 *  }
 * }
 * </pre>
 *
 * A cursor can be initialised from a key, using a {@code KeyMatchingStrategy} and
 * a {@code PositionStrategy}, to determine the exact starting position.
 * <p>
 * Let's call Kp the highest key lower than K and Kn the lowest key higher
 * than K : Kp &lt; K &lt; Kn
 * <ul>
 *  <li>When using EQUAL_TO_KEY on key K :
 *   <ul>
 *    <li>with ON_MATCHING_KEY, cursor is positioned on key K (if K exists in log),
 *        otherwise it is empty</li>
 *    <li>with AFTER_MATCHING_KEY, cursor is positioned on key Kn (if K exists in log),
 *        otherwise it is empty</li>
 *   </ul>
 *  </li>
 *  <li>When using LESS_THAN_OR_EQUAL_TO_KEY on key K :
 *   <ul>
 *    <li>with ON_MATCHING_KEY, cursor is positioned on key K (if K exists in log)
 *        or else Kp (if Kp exists in log), otherwise it is empty</li>
 *    <li>with AFTER_MATCHING_KEY, cursor is positioned on key Kn (if Kp or K exist in log),
 *        otherwise it is empty</li>
 *   </ul>
 *  </li>
 *  <li>When using GREATER_THAN_OR_EQUAL_TO_KEY on key K :
 *   <ul>
 *    <li>with ON_MATCHING_KEY, cursor is positioned on key K (if K exists in log)
 *        or else Kn (if Kn exists in log), otherwise it is empty</li>
 *    <li>with AFTER_MATCHING_KEY, cursor is positioned on key Kn (if K or Kn exist in log),
 *        otherwise it is empty</li>
 *   </ul>
 *  </li>
 * </ul>
 *
 * @param <T>
 *          type of the record being returned
 */
@NotThreadSafe
public interface DBCursor<T> extends Closeable
{

  /**
   * Represents a cursor key matching strategy, which allow to choose if only
   * the exact key must be found or if any key equal or lower/higher should match.
   */
  public enum KeyMatchingStrategy {
    /** Matches if the key or a lower key is found. */
    LESS_THAN_OR_EQUAL_TO_KEY,
    /** Matches only if the exact key is found. */
    EQUAL_TO_KEY,
    /** Matches if the key or a greater key is found. */
    GREATER_THAN_OR_EQUAL_TO_KEY
  }

  /**
   * Represents a cursor positioning strategy, which allow to choose if the start point
   * corresponds to the record at the provided key or the record just after the provided
   * key.
   */
  public enum PositionStrategy {
    /** Start point is on the matching key. */
    ON_MATCHING_KEY,
    /** Start point is after the matching key. */
    AFTER_MATCHING_KEY
  }

  /** Options to create a cursor. */
  public static final class CursorOptions
  {
    private final KeyMatchingStrategy keyMatchingStrategy;
    private final PositionStrategy positionStrategy;
    private final CSN defaultCSN;

    /**
     * Creates options with provided strategies.
     *
     * @param keyMatchingStrategy
     *          The key matching strategy
     * @param positionStrategy
     *          The position strategy
     */
    public CursorOptions(KeyMatchingStrategy keyMatchingStrategy, PositionStrategy positionStrategy)
    {
      this(keyMatchingStrategy, positionStrategy, null);
    }

    /**
     * Creates options with provided strategies and default CSN.
     *
     * @param keyMatchingStrategy
     *          The key matching strategy
     * @param positionStrategy
     *          The position strategy
     * @param defaultCSN
     *          When creating a replica DB Cursor, this is the default CSN to
     *          use for replicas which do not have an associated CSN
     */
    public CursorOptions(KeyMatchingStrategy keyMatchingStrategy, PositionStrategy positionStrategy, CSN defaultCSN)
    {
      this.keyMatchingStrategy = keyMatchingStrategy;
      this.positionStrategy = positionStrategy;
      this.defaultCSN = defaultCSN;
    }

    /**
     * Returns the key matching strategy.
     *
     * @return the key matching strategy
     */
    public KeyMatchingStrategy getKeyMatchingStrategy()
    {
      return keyMatchingStrategy;
    }

    /**
     * Returns the position strategy.
     *
     * @return the position strategy
     */
    public PositionStrategy getPositionStrategy()
    {
      return positionStrategy;
    }

    /**
     * Returns the default CSN.
     *
     * @return the default CSN
     */
    public CSN getDefaultCSN()
    {
      return defaultCSN;
    }

    @Override
    public boolean equals(Object obj)
    {
      if (this == obj) {
        return true;
      }
      if (obj instanceof CursorOptions) {
        CursorOptions other = (CursorOptions) obj;
        return keyMatchingStrategy == other.keyMatchingStrategy
            && positionStrategy == other.positionStrategy
            && Objects.equals(defaultCSN, other.defaultCSN);
      }
      return false;
    }

    @Override
    public int hashCode()
    {
      final int prime = 31;
      int result = 1;
      result = prime * result + ((keyMatchingStrategy == null) ? 0 : keyMatchingStrategy.hashCode());
      result = prime * result + ((positionStrategy == null) ? 0 : positionStrategy.hashCode());
      result = prime * result + ((defaultCSN == null) ? 0 : defaultCSN.hashCode());
      return result;
    }

    @Override
    public String toString()
    {
      return getClass().getSimpleName()
          + " [keyMatchingStrategy=" + keyMatchingStrategy
          + ", positionStrategy=" + positionStrategy
          + ", defaultCSN=" + defaultCSN + "]";
    }
  }

  /**
   * Getter for the current record.
   *
   * @return The current record.
   */
  T getRecord();

  /**
   * Skip to the next record of the database.
   *
   * @return true if has next, false otherwise
   * @throws ChangelogException
   *           When database exception raised.
   */
  boolean next() throws ChangelogException;

  /**
   * Release the resources and locks used by this Iterator. This method must be
   * called when the iterator is no longer used. Failure to do it could cause DB
   * deadlock.
   */
  @Override
  void close();
}