1 // Copyright (c) 2011-present, Facebook, Inc.  All rights reserved.
2 //  This source code is licensed under both the GPLv2 (found in the
3 //  COPYING file in the root directory) and Apache 2.0 License
4 //  (found in the LICENSE.Apache file in the root directory).
5 
6 package org.rocksdb;
7 
8 import java.nio.ByteBuffer;
9 
10 /**
11  * Comparators are used by RocksDB to determine
12  * the ordering of keys.
13  *
14  * Implementations of Comparators in Java should extend this class.
15  */
16 public abstract class AbstractComparator
17     extends RocksCallbackObject {
18 
AbstractComparator()19   AbstractComparator() {
20     super();
21   }
22 
AbstractComparator(final ComparatorOptions copt)23   protected AbstractComparator(final ComparatorOptions copt) {
24     super(copt.nativeHandle_);
25   }
26 
27   @Override
initializeNative(final long... nativeParameterHandles)28   protected long initializeNative(final long... nativeParameterHandles) {
29       return createNewComparator(nativeParameterHandles[0]);
30   }
31 
32   /**
33    * Get the type of this comparator.
34    *
35    * Used for determining the correct C++ cast in native code.
36    *
37    * @return The type of the comparator.
38    */
getComparatorType()39   ComparatorType getComparatorType() {
40     return ComparatorType.JAVA_COMPARATOR;
41   }
42 
43   /**
44    * The name of the comparator.  Used to check for comparator
45    * mismatches (i.e., a DB created with one comparator is
46    * accessed using a different comparator).
47    *
48    * A new name should be used whenever
49    * the comparator implementation changes in a way that will cause
50    * the relative ordering of any two keys to change.
51    *
52    * Names starting with "rocksdb." are reserved and should not be used.
53    *
54    * @return The name of this comparator implementation
55    */
name()56   public abstract String name();
57 
58   /**
59    * Three-way key comparison. Implementations should provide a
60    * <a href="https://en.wikipedia.org/wiki/Total_order">total order</a>
61    * on keys that might be passed to it.
62    *
63    * The implementation may modify the {@code ByteBuffer}s passed in, though
64    * it would be unconventional to modify the "limit" or any of the
65    * underlying bytes. As a callback, RocksJava will ensure that {@code a}
66    * is a different instance from {@code b}.
67    *
68    * @param a buffer containing the first key in its "remaining" elements
69    * @param b buffer containing the second key in its "remaining" elements
70    *
71    * @return Should return either:
72    *    1) &lt; 0 if "a" &lt; "b"
73    *    2) == 0 if "a" == "b"
74    *    3) &gt; 0 if "a" &gt; "b"
75    */
compare(final ByteBuffer a, final ByteBuffer b)76   public abstract int compare(final ByteBuffer a, final ByteBuffer b);
77 
78   /**
79    * <p>Used to reduce the space requirements
80    * for internal data structures like index blocks.</p>
81    *
82    * <p>If start &lt; limit, you may modify start which is a
83    * shorter string in [start, limit).</p>
84    *
85    * If you modify start, it is expected that you set the byte buffer so that
86    * a subsequent read of start.remaining() bytes from start.position()
87    * to start.limit() will obtain the new start value.
88    *
89    * <p>Simple comparator implementations may return with start unchanged.
90    * i.e., an implementation of this method that does nothing is correct.</p>
91    *
92    * @param start the start
93    * @param limit the limit
94    */
findShortestSeparator(final ByteBuffer start, final ByteBuffer limit)95   public void findShortestSeparator(final ByteBuffer start,
96       final ByteBuffer limit) {
97     // no-op
98   }
99 
100   /**
101    * <p>Used to reduce the space requirements
102    * for internal data structures like index blocks.</p>
103    *
104    * <p>You may change key to a shorter key (key1) where
105    * key1 &ge; key.</p>
106    *
107    * <p>Simple comparator implementations may return the key unchanged.
108    * i.e., an implementation of
109    * this method that does nothing is correct.</p>
110    *
111    * @param key the key
112    */
findShortSuccessor(final ByteBuffer key)113   public void findShortSuccessor(final ByteBuffer key) {
114     // no-op
115   }
116 
usingDirectBuffers()117   public final boolean usingDirectBuffers() {
118     return usingDirectBuffers(nativeHandle_);
119   }
120 
usingDirectBuffers(final long nativeHandle)121   private native boolean usingDirectBuffers(final long nativeHandle);
122 
createNewComparator(final long comparatorOptionsHandle)123   private native long createNewComparator(final long comparatorOptionsHandle);
124 }
125