Skip to content

Commit

Permalink
Rename range descriptors to reflect Guava range terminology (#7)
Browse files Browse the repository at this point in the history 
Deferring to a widely-known external source simplifies adoption and
allows us to more easily identify unsupported range types.
  • Loading branch information
@benalexau
benalexau committed Jul 15, 2017
1 parent bb6d2a6 commit 7881199
Show file tree
Hide file tree
Showing 6 changed files with 165 additions and 154 deletions.
13 changes: 8 additions & 5 deletions src/main/java/org/lmdbjava/Dbi.java
View file
Expand Up @@ -32,6 +32,10 @@
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.KeyRange.all;
import static org.lmdbjava.KeyRange.allBackward;
import static org.lmdbjava.KeyRange.atLeast;
import static org.lmdbjava.KeyRange.atLeastBackward;
import static org.lmdbjava.Library.LIB;
import org.lmdbjava.Library.MDB_stat;
import static org.lmdbjava.Library.RUNTIME;
Expand Down Expand Up @@ -211,7 +215,7 @@ public byte[] getName() {
* @return iterator
*/
public CursorIterator<T> iterate(final Txn<T> txn) {
return iterate(txn, KeyRange.forward());
return iterate(txn, all());
}

/**
Expand All @@ -227,8 +231,7 @@ public CursorIterator<T> iterate(final Txn<T> txn, final IteratorType type) {
if (SHOULD_CHECK) {
requireNonNull(type);
}
final KeyRange<T> range = type == FORWARD
? KeyRange.forward() : KeyRange.backward();
final KeyRange<T> range = type == FORWARD ? all() : allBackward();
return iterate(txn, range);
}

Expand All @@ -251,9 +254,9 @@ public CursorIterator<T> iterate(final Txn<T> txn, final T key,

final KeyRange<T> range;
if (type == FORWARD) {
range = key == null ? KeyRange.forward() : KeyRange.atLeast(key);
range = key == null ? all() : atLeast(key);
} else {
range = key == null ? KeyRange.backward() : KeyRange.atLeastBackward(key);
range = key == null ? allBackward() : atLeastBackward(key);
}

return iterate(txn, range);
Expand Down
108 changes: 54 additions & 54 deletions src/main/java/org/lmdbjava/KeyRange.java
View file
Expand Up @@ -30,8 +30,8 @@
import static org.lmdbjava.KeyRange.IteratorOp.CALL_NEXT_OP;
import static org.lmdbjava.KeyRange.IteratorOp.RELEASE;
import static org.lmdbjava.KeyRange.IteratorOp.TERMINATE;
import static org.lmdbjava.KeyRangeType.BACKWARD;
import static org.lmdbjava.KeyRangeType.FORWARD;
import static org.lmdbjava.KeyRangeType.BACKWARD_ALL;
import static org.lmdbjava.KeyRangeType.FORWARD_ALL;

/**
* Limits the range and direction of keys to iterate.
Expand All @@ -44,8 +44,8 @@
@SuppressWarnings({"PMD.CyclomaticComplexity", "PMD.StdCyclomaticComplexity"})
public final class KeyRange<T> {

private static final KeyRange BACK = new KeyRange<>(BACKWARD, null, null);
private static final KeyRange FORW = new KeyRange<>(FORWARD, null, null);
private static final KeyRange BACK = new KeyRange<>(BACKWARD_ALL, null, null);
private static final KeyRange FORW = new KeyRange<>(FORWARD_ALL, null, null);
private final T start;
private final T stop;
private final KeyRangeType type;
Expand Down Expand Up @@ -75,91 +75,91 @@ public KeyRange(final KeyRangeType type, final T start, final T stop) {
}

/**
* Create a {@link KeyRangeType#FORWARD_START} range.
* Create a {@link KeyRangeType#FORWARD_ALL} range.
*
* @param <T> buffer type
* @param start start key (required)
* @param <T> buffer type
* @return a key range (never null)
*/
public static <T> KeyRange<T> atLeast(final T start) {
return new KeyRange<>(KeyRangeType.FORWARD_START, start, null);
public static <T> KeyRange<T> all() {
return FORW;
}

/**
* Create a {@link KeyRangeType#BACKWARD_START} range.
* Create a {@link KeyRangeType#BACKWARD_ALL} range.
*
* @param <T> buffer type
* @param start start key (required)
* @param <T> buffer type
* @return a key range (never null)
*/
public static <T> KeyRange<T> atLeastBackward(final T start) {
return new KeyRange<>(KeyRangeType.BACKWARD_START, start, null);
public static <T> KeyRange<T> allBackward() {
return BACK;
}

/**
* Create a {@link KeyRangeType#FORWARD_STOP} range.
* Create a {@link KeyRangeType#FORWARD_AT_LEAST} range.
*
* @param <T> buffer type
* @param stop stop key (required)
* @param <T> buffer type
* @param start start key (required)
* @return a key range (never null)
*/
public static <T> KeyRange<T> atMost(final T stop) {
return new KeyRange<>(KeyRangeType.FORWARD_STOP, null, stop);
public static <T> KeyRange<T> atLeast(final T start) {
return new KeyRange<>(KeyRangeType.FORWARD_AT_LEAST, start, null);
}

/**
* Create a {@link KeyRangeType#BACKWARD_STOP} range.
* Create a {@link KeyRangeType#BACKWARD_AT_LEAST} range.
*
* @param <T> buffer type
* @param stop stop key (required)
* @param <T> buffer type
* @param start start key (required)
* @return a key range (never null)
*/
public static <T> KeyRange<T> atMostBackward(final T stop) {
return new KeyRange<>(KeyRangeType.BACKWARD_STOP, null, stop);
public static <T> KeyRange<T> atLeastBackward(final T start) {
return new KeyRange<>(KeyRangeType.BACKWARD_AT_LEAST, start, null);
}

/**
* Create a {@link KeyRangeType#BACKWARD} range.
* Create a {@link KeyRangeType#FORWARD_AT_MOST} range.
*
* @param <T> buffer type
* @param <T> buffer type
* @param stop stop key (required)
* @return a key range (never null)
*/
public static <T> KeyRange<T> backward() {
return BACK;
public static <T> KeyRange<T> atMost(final T stop) {
return new KeyRange<>(KeyRangeType.FORWARD_AT_MOST, null, stop);
}

/**
* Create a {@link KeyRangeType#FORWARD} range.
* Create a {@link KeyRangeType#BACKWARD_AT_MOST} range.
*
* @param <T> buffer type
* @param <T> buffer type
* @param stop stop key (required)
* @return a key range (never null)
*/
public static <T> KeyRange<T> forward() {
return FORW;
public static <T> KeyRange<T> atMostBackward(final T stop) {
return new KeyRange<>(KeyRangeType.BACKWARD_AT_MOST, null, stop);
}

/**
* Create a {@link KeyRangeType#FORWARD_RANGE} range.
* Create a {@link KeyRangeType#FORWARD_CLOSED} range.
*
* @param <T> buffer type
* @param start start key (required)
* @param stop stop key (required)
* @return a key range (never null)
*/
public static <T> KeyRange<T> range(final T start, final T stop) {
return new KeyRange<>(KeyRangeType.FORWARD_RANGE, start, stop);
public static <T> KeyRange<T> closed(final T start, final T stop) {
return new KeyRange<>(KeyRangeType.FORWARD_CLOSED, start, stop);
}

/**
* Create a {@link KeyRangeType#BACKWARD_RANGE} range.
* Create a {@link KeyRangeType#BACKWARD_CLOSED} range.
*
* @param <T> buffer type
* @param start start key (required)
* @param stop stop key (required)
* @return a key range (never null)
*/
public static <T> KeyRange<T> rangeBackward(final T start, final T stop) {
return new KeyRange<>(KeyRangeType.BACKWARD_RANGE, start, stop);
public static <T> KeyRange<T> closedBackward(final T start, final T stop) {
return new KeyRange<>(KeyRangeType.BACKWARD_CLOSED, start, stop);
}

/**
Expand Down Expand Up @@ -201,21 +201,21 @@ public KeyRangeType getType() {
@SuppressWarnings("checkstyle:ReturnCount")
CursorOp initialOp() {
switch (type) {
case FORWARD:
case FORWARD_ALL:
return FIRST;
case FORWARD_START:
case FORWARD_AT_LEAST:
return GET_START_KEY;
case FORWARD_STOP:
case FORWARD_AT_MOST:
return FIRST;
case FORWARD_RANGE:
case FORWARD_CLOSED:
return GET_START_KEY;
case BACKWARD:
case BACKWARD_ALL:
return LAST;
case BACKWARD_START:
case BACKWARD_AT_LEAST:
return GET_START_KEY;
case BACKWARD_STOP:
case BACKWARD_AT_MOST:
return LAST;
case BACKWARD_RANGE:
case BACKWARD_CLOSED:
return GET_START_KEY;
default:
throw new IllegalStateException("Invalid type");
Expand All @@ -238,21 +238,21 @@ <C extends Comparator<T>> IteratorOp iteratorOp(final C c,
return TERMINATE;
}
switch (type) {
case FORWARD:
case FORWARD_ALL:
return RELEASE;
case FORWARD_START:
case FORWARD_AT_LEAST:
return RELEASE;
case FORWARD_STOP:
case FORWARD_AT_MOST:
return c.compare(buffer, stop) > 0 ? TERMINATE : RELEASE;
case FORWARD_RANGE:
case FORWARD_CLOSED:
return c.compare(buffer, stop) > 0 ? TERMINATE : RELEASE;
case BACKWARD:
case BACKWARD_ALL:
return RELEASE;
case BACKWARD_START:
case BACKWARD_AT_LEAST:
return c.compare(buffer, start) > 0 ? CALL_NEXT_OP : RELEASE; // rewind
case BACKWARD_STOP:
case BACKWARD_AT_MOST:
return c.compare(buffer, stop) >= 0 ? RELEASE : TERMINATE;
case BACKWARD_RANGE:
case BACKWARD_CLOSED:
if (c.compare(buffer, start) > 0) {
return CALL_NEXT_OP; // rewind
}
Expand Down
22 changes: 14 additions & 8 deletions src/main/java/org/lmdbjava/KeyRangeType.java
View file
Expand Up @@ -24,6 +24,12 @@
* Key range type.
*
* <p>
* The terminology used in this class is adapted from Google Guava's ranges.
* Refer to the <a href="https://github.com/google/guava/wiki/RangesExplained">
* Ranges Explained</a> wiki page for more information. LmddJava prepends either
* "FORWARD" or "BACKWARD" to denote the iterator order.
*
* <p>
* In the examples below, it is assumed the table has keys 2, 4, 6 and 8.
*/
public enum KeyRangeType {
Expand All @@ -37,7 +43,7 @@ public enum KeyRangeType {
* <p>
* In our example, the returned keys would be 2, 4, 6 and 8.
*/
FORWARD(true, false, false),
FORWARD_ALL(true, false, false),
/**
* Start on the passed key (or the first key immediately after it) and
* iterate forward until no keys remain.
Expand All @@ -49,7 +55,7 @@ public enum KeyRangeType {
* In our example and with a passed search key of 5, the returned keys would
* be 6 and 8. With a passed key of 6, the returned keys would be 6 and 8.
*/
FORWARD_START(true, true, false),
FORWARD_AT_LEAST(true, true, false),
/**
* Start on the first key and iterate forward until a key equal to it (or the
* first key immediately after it) is reached.
Expand All @@ -61,7 +67,7 @@ public enum KeyRangeType {
* In our example and with a passed search key of 5, the returned keys would
* be 2 and 4. With a passed key of 6, the returned keys would be 2, 4 and 6.
*/
FORWARD_STOP(true, false, true),
FORWARD_AT_MOST(true, false, true),
/**
* Iterate forward between the passed keys, matching on the first keys
* directly equal to the passed key (or immediately following it in the case
Expand All @@ -75,7 +81,7 @@ public enum KeyRangeType {
* In our example and with a passed search range of 3 - 7, the returned keys
* would be 4 and 6. With a range of 2 - 6, the keys would be 2, 4 and 6.
*/
FORWARD_RANGE(true, true, true),
FORWARD_CLOSED(true, true, true),
/**
* Start on the last key and iterate backward until no keys remain.
*
Expand All @@ -85,7 +91,7 @@ public enum KeyRangeType {
* <p>
* In our example, the returned keys would be 8, 6, 4 and 2.
*/
BACKWARD(false, false, false),
BACKWARD_ALL(false, false, false),
/**
* Start on the passed key (or the first key immediately preceding it) and
* iterate backward until no keys remain.
Expand All @@ -97,7 +103,7 @@ public enum KeyRangeType {
* In our example and with a passed search key of 5, the returned keys would
* be 4 and 2. With a passed key of 6, the returned keys would be 6, 4 and 2.
*/
BACKWARD_START(false, true, false),
BACKWARD_AT_LEAST(false, true, false),
/**
* Start on the last key and iterate backward until a key equal to it (or the
* first key immediately preceding it it) is reached.
Expand All @@ -109,7 +115,7 @@ public enum KeyRangeType {
* In our example and with a passed search key of 5, the returned keys would
* be 8 and 6. With a passed key of 6, the returned keys would be 8 and 6.
*/
BACKWARD_STOP(false, false, true),
BACKWARD_AT_MOST(false, false, true),
/**
* Iterate backward between the passed keys, matching on the first keys
* directly equal to the passed key (or immediately preceding it in the case
Expand All @@ -123,7 +129,7 @@ public enum KeyRangeType {
* In our example and with a passed search range of 7 - 3, the returned keys
* would be 6 and 4. With a range of 6 - 2, the keys would be 6, 4 and 2.
*/
BACKWARD_RANGE(false, true, true);
BACKWARD_CLOSED(false, true, true);

private final boolean directionForward;
private final boolean startKeyRequired;
Expand Down

0 comments on commit 7881199

Please sign in to comment.