/*
 * Copyright © 2016-2025 The LmdbJava Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.lmdbjava;

import static java.util.Objects.requireNonNull;
import static org.lmdbjava.Dbi.KeyExistsException.MDB_KEYEXIST;
import static org.lmdbjava.Dbi.KeyNotFoundException.MDB_NOTFOUND;
import static org.lmdbjava.Env.SHOULD_CHECK;
import static org.lmdbjava.Library.LIB;
import static org.lmdbjava.PutFlags.MDB_MULTIPLE;
import static org.lmdbjava.PutFlags.MDB_NODUPDATA;
import static org.lmdbjava.PutFlags.MDB_NOOVERWRITE;
import static org.lmdbjava.PutFlags.MDB_RESERVE;
import static org.lmdbjava.ResultCodeMapper.checkRc;
import static org.lmdbjava.SeekOp.MDB_FIRST;
import static org.lmdbjava.SeekOp.MDB_LAST;
import static org.lmdbjava.SeekOp.MDB_NEXT;
import static org.lmdbjava.SeekOp.MDB_PREV;

import jnr.ffi.Pointer;
import jnr.ffi.byref.NativeLongByReference;

/**
 * A cursor handle.
 *
 * @param <T> buffer type
 */
public final class Cursor<T> implements AutoCloseable {

  private boolean closed;
  private final KeyVal<T> kv;
  private final Pointer ptrCursor;
  private Txn<T> txn;
  private final Env<T> env;

  Cursor(final Pointer ptr, final Txn<T> txn, final Env<T> env) {
    requireNonNull(ptr);
    requireNonNull(txn);
    this.ptrCursor = ptr;
    this.txn = txn;
    this.kv = txn.newKeyVal();
    this.env = env;
  }

  /**
   * Close a cursor handle.
   *
   * <p>The cursor handle will be freed and must not be used again after this call. Its transaction
   * must still be live if it is a write-transaction.
   */
  @Override
  public void close() {
    if (closed) {
      return;
    }
    kv.close();
    if (SHOULD_CHECK) {
      env.checkNotClosed();
      if (!txn.isReadOnly()) {
        txn.checkReady();
      }
    }
    LIB.mdb_cursor_close(ptrCursor);
    closed = true;
  }

  /**
   * Return count of duplicates for current key.
   *
   * <p>This call is only valid on databases that support sorted duplicate data items {@link
   * DbiFlags#MDB_DUPSORT}.
   *
   * @return count of duplicates for current key
   */
  public long count() {
    if (SHOULD_CHECK) {
      env.checkNotClosed();
      checkNotClosed();
      txn.checkReady();
    }
    final NativeLongByReference longByReference = new NativeLongByReference();
    checkRc(LIB.mdb_cursor_count(ptrCursor, longByReference));
    return longByReference.longValue();
  }

  /**
   * @deprecated Instead use {@link Cursor#delete(PutFlagSet)}. <hr> Delete current key/data pair.
   *     <p>This function deletes the key/data pair to which the cursor refers.
   * @param flags flags (either null or {@link PutFlags#MDB_NODUPDATA}
   */
  @Deprecated
  public void delete(final PutFlags... flags) {
    delete(PutFlagSet.of(flags));
  }

  /**
   * Delete current key/data pair.
   *
   * <p>This function deletes the key/data pair to which the cursor refers.
   */
  public void delete() {
    delete(PutFlagSet.EMPTY);
  }

  /**
   * Delete current key/data pair.
   *
   * <p>This function deletes the key/data pair to which the cursor refers.
   *
   * @param flags flags (either null or {@link PutFlags#MDB_NODUPDATA}
   */
  public void delete(final PutFlagSet flags) {
    if (SHOULD_CHECK) {
      env.checkNotClosed();
      checkNotClosed();
      txn.checkReady();
      txn.checkWritesAllowed();
    }
    final PutFlagSet putFlagSet = flags != null ? flags : PutFlagSet.EMPTY;
    checkRc(LIB.mdb_cursor_del(ptrCursor, putFlagSet.getMask()));
  }

  /**
   * Position at first key/data item.
   *
   * @return false if requested position not found
   */
  public boolean first() {
    return seek(MDB_FIRST);
  }

  /**
   * Reposition the key/value buffers based on the passed key and operation.
   *
   * @param key to search for
   * @param data to search for
   * @param op options for this operation
   * @return false if key not found
   */
  public boolean get(final T key, final T data, final SeekOp op) {
    if (SHOULD_CHECK) {
      requireNonNull(key);
      requireNonNull(op);
      env.checkNotClosed();
      checkNotClosed();
      txn.checkReady();
    }
    final Pointer transientKey = kv.keyIn(key);
    final Pointer transientVal = kv.valIn(data);

    final int rc = LIB.mdb_cursor_get(ptrCursor, kv.pointerKey(), kv.pointerVal(), op.getCode());

    if (rc == MDB_NOTFOUND) {
      return false;
    }

    checkRc(rc);
    kv.keyOut();
    kv.valOut();
    ReferenceUtil.reachabilityFence0(transientKey);
    ReferenceUtil.reachabilityFence0(transientVal);
    ReferenceUtil.reachabilityFence0(kv.key());
    ReferenceUtil.reachabilityFence0(kv.val());
    ReferenceUtil.reachabilityFence0(key);
    return true;
  }

  /**
   * Reposition the key/value buffers based on the passed key and operation.
   *
   * @param key to search for
   * @param op options for this operation
   * @return false if key not found
   */
  public boolean get(final T key, final GetOp op) {
    if (SHOULD_CHECK) {
      requireNonNull(key);
      requireNonNull(op);
      env.checkNotClosed();
      checkNotClosed();
      txn.checkReady();
    }
    final Pointer transientKey = kv.keyIn(key);

    final int rc = LIB.mdb_cursor_get(ptrCursor, kv.pointerKey(), kv.pointerVal(), op.getCode());

    if (rc == MDB_NOTFOUND) {
      return false;
    }

    checkRc(rc);
    kv.keyOut();
    kv.valOut();
    ReferenceUtil.reachabilityFence0(transientKey);
    ReferenceUtil.reachabilityFence0(kv.key());
    ReferenceUtil.reachabilityFence0(kv.val());
    ReferenceUtil.reachabilityFence0(key);
    return true;
  }

  /**
   * Obtain the key.
   *
   * @return the key that the cursor is located at.
   */
  public T key() {
    return kv.key();
  }

  KeyVal<T> keyVal() {
    return kv;
  }

  /**
   * Position at last key/data item.
   *
   * @return false if requested position not found
   */
  public boolean last() {
    return seek(MDB_LAST);
  }

  /**
   * Position at next data item.
   *
   * @return false if requested position not found
   */
  public boolean next() {
    return seek(MDB_NEXT);
  }

  /**
   * Position at previous data item.
   *
   * @return false if requested position not found
   */
  public boolean prev() {
    return seek(MDB_PREV);
  }

  /**
   * @deprecated Use {@link Cursor#put(Object, Object, PutFlagSet)} instead. <hr> Store by cursor.
   *     <p>This function stores key/data pairs into the database.
   * @param key key to store
   * @param val data to store
   * @param flags options for this operation
   * @return true if the value was put, false if MDB_NOOVERWRITE or MDB_NODUPDATA were set and the
   *     key/value existed already.
   */
  @Deprecated
  public boolean put(final T key, final T val, final PutFlags... flags) {
    return put(key, val, PutFlagSet.of(flags));
  }

  /**
   * Store by cursor.
   *
   * <p>This function stores key/data pairs into the database.
   *
   * @param key key to store
   * @param val data to store
   * @return true if the value was put, false if MDB_NOOVERWRITE or MDB_NODUPDATA were set and the
   *     key/value existed already.
   */
  public boolean put(final T key, final T val) {
    return put(key, val, PutFlagSet.EMPTY);
  }

  /**
   * Store by cursor.
   *
   * <p>This function stores key/data pairs into the database.
   *
   * @param key key to store
   * @param val data to store
   * @param flags options for this operation
   * @return true if the value was put, false if MDB_NOOVERWRITE or MDB_NODUPDATA were set and the
   *     key/value existed already.
   */
  public boolean put(final T key, final T val, final PutFlagSet flags) {
    if (SHOULD_CHECK) {
      requireNonNull(key);
      requireNonNull(val);
      requireNonNull(flags);
      env.checkNotClosed();
      checkNotClosed();
      txn.checkReady();
      txn.checkWritesAllowed();
    }
    final Pointer transientKey = kv.keyIn(key);
    final Pointer transientVal = kv.valIn(val);
    final int rc = LIB.mdb_cursor_put(ptrCursor, kv.pointerKey(), kv.pointerVal(), flags.getMask());
    if (rc == MDB_KEYEXIST) {
      if (flags.isSet(MDB_NOOVERWRITE)) {
        kv.valOut(); // marked as in,out in LMDB C docs
      } else if (!flags.isSet(MDB_NODUPDATA)) {
        checkRc(rc);
      }
      return false;
    }
    checkRc(rc);
    ReferenceUtil.reachabilityFence0(transientKey);
    ReferenceUtil.reachabilityFence0(transientVal);
    ReferenceUtil.reachabilityFence0(key);
    ReferenceUtil.reachabilityFence0(val);
    return true;
  }

  /**
   * @deprecated Use {@link Cursor#put(Object, Object, PutFlagSet)} instead. <hr> Put multiple
   *     values into the database in one <code>MDB_MULTIPLE</code> operation.
   *     <p>The database must have been opened with {@link DbiFlags#MDB_DUPFIXED}. The buffer must
   *     contain fixed-sized values to be inserted. The size of each element is calculated from the
   *     buffer's size divided by the given element count. For example, to populate 10 X 4 byte
   *     integers at once, present a buffer of 40 bytes and specify the element as 10.
   * @param key key to store in the database (not null)
   * @param val value to store in the database (not null)
   * @param elements number of elements contained in the passed value buffer
   * @param flags options for operation (must set <code>MDB_MULTIPLE</code>)
   */
  @Deprecated
  public void putMultiple(final T key, final T val, final int elements, final PutFlags... flags) {
    putMultiple(key, val, elements, PutFlagSet.of(flags));
  }

  /**
   * Put multiple values into the database in one <code>MDB_MULTIPLE</code> operation.
   *
   * <p>The database must have been opened with {@link DbiFlags#MDB_DUPFIXED}. The buffer must
   * contain fixed-sized values to be inserted. The size of each element is calculated from the
   * buffer's size divided by the given element count. For example, to populate 10 X 4 byte integers
   * at once, present a buffer of 40 bytes and specify the element as 10.
   *
   * @param key key to store in the database (not null)
   * @param val value to store in the database (not null)
   * @param elements number of elements contained in the passed value buffer
   */
  public void putMultiple(final T key, final T val, final int elements) {
    putMultiple(key, val, elements, PutFlagSet.EMPTY);
  }

  /**
   * Put multiple values into the database in one <code>MDB_MULTIPLE</code> operation.
   *
   * <p>The database must have been opened with {@link DbiFlags#MDB_DUPFIXED}. The buffer must
   * contain fixed-sized values to be inserted. The size of each element is calculated from the
   * buffer's size divided by the given element count. For example, to populate 10 X 4 byte integers
   * at once, present a buffer of 40 bytes and specify the element as 10.
   *
   * @param key key to store in the database (not null)
   * @param val value to store in the database (not null)
   * @param elements number of elements contained in the passed value buffer
   * @param flags options for operation (must set <code>MDB_MULTIPLE</code>) Either a {@link
   *     PutFlagSet} or a single {@link PutFlags}.
   */
  public void putMultiple(final T key, final T val, final int elements, final PutFlagSet flags) {
    if (SHOULD_CHECK) {
      requireNonNull(txn);
      requireNonNull(key);
      requireNonNull(val);
      env.checkNotClosed();
      txn.checkReady();
      txn.checkWritesAllowed();
      if (!flags.isSet(MDB_MULTIPLE)) {
        throw new IllegalArgumentException("Must set " + MDB_MULTIPLE + " flag");
      }
    }

    final Pointer transientKey = txn.kv().keyIn(key);
    final Pointer dataPtr = txn.kv().valInMulti(val, elements);
    final int rc = LIB.mdb_cursor_put(ptrCursor, txn.kv().pointerKey(), dataPtr, flags.getMask());
    checkRc(rc);
    ReferenceUtil.reachabilityFence0(transientKey);
    ReferenceUtil.reachabilityFence0(dataPtr);
    ReferenceUtil.reachabilityFence0(key);
    ReferenceUtil.reachabilityFence0(val);
  }

  /**
   * Renew a cursor handle.
   *
   * <p>A cursor is associated with a specific transaction and database. Cursors that are only used
   * in read-only transactions may be re-used, to avoid unnecessary malloc/free overhead. The cursor
   * may be associated with a new read-only transaction, and referencing the same database handle as
   * it was created with. This may be done whether the previous transaction is live or dead.
   *
   * @param newTxn transaction handle
   */
  public void renew(final Txn<T> newTxn) {
    if (SHOULD_CHECK) {
      requireNonNull(newTxn);
      env.checkNotClosed();
      checkNotClosed();
      this.txn.checkReadOnly(); // existing
      newTxn.checkReadOnly();
      newTxn.checkReady();
    }
    checkRc(LIB.mdb_cursor_renew(newTxn.pointer(), ptrCursor));
    this.txn = newTxn;
  }

  /**
   * @deprecated Use {@link Cursor#reserve(Object, int, PutFlagSet)} instead. <hr> Reserve space for
   *     data of the given size, but don't copy the given val. Instead, return a pointer to the
   *     reserved space, which the caller can fill in later - before the next update operation or
   *     the transaction ends. This saves an extra memcpy if the data is being generated later. LMDB
   *     does nothing else with this memory, the caller is expected to modify all of the space
   *     requested.
   *     <p>This flag must not be specified if the database was opened with MDB_DUPSORT
   * @param key key to store in the database (not null)
   * @param size size of the value to be stored in the database (not null)
   * @param flags options for this operation
   * @return a buffer that can be used to modify the value
   */
  @Deprecated
  public T reserve(final T key, final int size, final PutFlags... flags) {
    return reserve(key, size, PutFlagSet.of(flags));
  }

  /**
   * Reserve space for data of the given size, but don't copy the given val. Instead, return a
   * pointer to the reserved space, which the caller can fill in later - before the next update
   * operation or the transaction ends. This saves an extra {@code memcpy} if the data is being
   * generated later. LMDB does nothing else with this memory, the caller is expected to modify all
   * the space requested.
   *
   * <p>This flag must not be specified if the database was opened with MDB_DUPSORT
   *
   * @param key key to store in the database (not null)
   * @param size size of the value to be stored in the database (not null)
   * @return a buffer that can be used to modify the value
   */
  public T reserve(final T key, final int size) {
    return reserve(key, size, PutFlagSet.EMPTY);
  }

  /**
   * Reserve space for data of the given size, but don't copy the given val. Instead, return a
   * pointer to the reserved space, which the caller can fill in later - before the next update
   * operation or the transaction ends. This saves an extra memcpy if the data is being generated
   * later. LMDB does nothing else with this memory, the caller is expected to modify all the space
   * requested.
   *
   * <p>This flag must not be specified if the database was opened with MDB_DUPSORT
   *
   * @param key key to store in the database (not null)
   * @param size size of the value to be stored in the database (not null)
   * @param flags options for this operation
   * @return a buffer that can be used to modify the value
   */
  public T reserve(final T key, final int size, final PutFlagSet flags) {
    if (SHOULD_CHECK) {
      requireNonNull(key);
      requireNonNull(flags);
      env.checkNotClosed();
      checkNotClosed();
      txn.checkReady();
      txn.checkWritesAllowed();
    }
    final Pointer transientKey = kv.keyIn(key);
    final Pointer transientVal = kv.valIn(size);
    // This is inconsistent with putMultiple which require MDB_MULTIPLE to be in the set.
    final int flagsMask = flags.getMaskWith(MDB_RESERVE);
    checkRc(LIB.mdb_cursor_put(ptrCursor, kv.pointerKey(), kv.pointerVal(), flagsMask));
    kv.valOut();
    ReferenceUtil.reachabilityFence0(transientKey);
    ReferenceUtil.reachabilityFence0(transientVal);
    ReferenceUtil.reachabilityFence0(key);
    return val();
  }

  /**
   * Reposition the key/value buffers based on the passed operation.
   *
   * @param op options for this operation
   * @return false if requested position not found
   */
  public boolean seek(final SeekOp op) {
    if (SHOULD_CHECK) {
      requireNonNull(op);
      env.checkNotClosed();
      checkNotClosed();
      txn.checkReady();
    }

    final int rc = LIB.mdb_cursor_get(ptrCursor, kv.pointerKey(), kv.pointerVal(), op.getCode());

    if (rc == MDB_NOTFOUND) {
      return false;
    }

    checkRc(rc);
    kv.keyOut();
    kv.valOut();
    return true;
  }

  /**
   * Obtain the value.
   *
   * @return the value that the cursor is located at.
   */
  public T val() {
    return kv.val();
  }

  private void checkNotClosed() {
    if (closed) {
      throw new ClosedException();
    }
  }

  /** Cursor has already been closed. */
  public static final class ClosedException extends LmdbException {

    private static final long serialVersionUID = 1L;

    /** Creates a new instance. */
    public ClosedException() {
      super("Cursor has already been closed");
    }
  }

  /** Cursor stack too deep - internal error. */
  public static final class FullException extends LmdbNativeException {

    static final int MDB_CURSOR_FULL = -30_787;
    private static final long serialVersionUID = 1L;

    FullException() {
      super(MDB_CURSOR_FULL, "Cursor stack too deep - internal error");
    }
  }
}