org.rocksdb.AbstractComparator Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of rocksdbjni Show documentation
RocksDB fat jar that contains .so files for linux32 and linux64 (glibc and musl-libc), jnilib files for Mac OSX, and a .dll for Windows x64.
The newest version!
// Copyright (c) 2011-present, Facebook, Inc.  All rights reserved.
//  This source code is licensed under both the GPLv2 (found in the
//  COPYING file in the root directory) and Apache 2.0 License
//  (found in the LICENSE.Apache file in the root directory).

package org.rocksdb;

import java.nio.ByteBuffer;

/**
 * Comparators are used by RocksDB to determine
 * the ordering of keys.
 *
 * Implementations of Comparators in Java should extend this class.
 */
public abstract class AbstractComparator
    extends RocksCallbackObject {

  AbstractComparator() {
    super();
  }

  protected AbstractComparator(final ComparatorOptions copt) {
    super(copt.nativeHandle_);
  }

  @Override
  protected long initializeNative(final long... nativeParameterHandles) {
      return createNewComparator(nativeParameterHandles[0]);
  }

  /**
   * Get the type of this comparator.
   *
   * Used for determining the correct C++ cast in native code.
   *
   * @return The type of the comparator.
   */
  ComparatorType getComparatorType() {
    return ComparatorType.JAVA_COMPARATOR;
  }

  /**
   * The name of the comparator.  Used to check for comparator
   * mismatches (i.e., a DB created with one comparator is
   * accessed using a different comparator).
   *
   * A new name should be used whenever
   * the comparator implementation changes in a way that will cause
   * the relative ordering of any two keys to change.
   *
   * Names starting with "rocksdb." are reserved and should not be used.
   *
   * @return The name of this comparator implementation
   */
  public abstract String name();

  /**
   * Three-way key comparison. Implementations should provide a
   * total order
   * on keys that might be passed to it.
   *
   * The implementation may modify the {@code ByteBuffer}s passed in, though
   * it would be unconventional to modify the "limit" or any of the
   * underlying bytes. As a callback, RocksJava will ensure that {@code a}
   * is a different instance from {@code b}.
   *
   * @param a buffer containing the first key in its "remaining" elements
   * @param b buffer containing the second key in its "remaining" elements
   *
   * @return Should return either:
   *    1) < 0 if "a" < "b"
   *    2) == 0 if "a" == "b"
   *    3) > 0 if "a" > "b"
   */
  public abstract int compare(final ByteBuffer a, final ByteBuffer b);

  /**
   * Used to reduce the space requirements
   * for internal data structures like index blocks.
   *
   * If start < limit, you may modify start which is a
   * shorter string in [start, limit).
   *
   * If you modify start, it is expected that you set the byte buffer so that
   * a subsequent read of start.remaining() bytes from start.position()
   * to start.limit() will obtain the new start value.
   *
   * Simple comparator implementations may return with start unchanged.
   * i.e., an implementation of this method that does nothing is correct.
   *
   * @param start the start
   * @param limit the limit
   */
  public void findShortestSeparator(final ByteBuffer start,
      final ByteBuffer limit) {
    // no-op
  }

  /**
   * Used to reduce the space requirements
   * for internal data structures like index blocks.
   *
   * You may change key to a shorter key (key1) where
   * key1 ≥ key.
   *
   * Simple comparator implementations may return the key unchanged.
   * i.e., an implementation of
   * this method that does nothing is correct.
   *
   * @param key the key
   */
  public void findShortSuccessor(final ByteBuffer key) {
    // no-op
  }

  public final boolean usingDirectBuffers() {
    return usingDirectBuffers(nativeHandle_);
  }

  private native boolean usingDirectBuffers(final long nativeHandle);

  private native long createNewComparator(final long comparatorOptionsHandle);
}