Package io.permazen.kv

Class KeyRange

java.lang.Object
io.permazen.kv.KeyRange
public class KeyRange extends Object
Represents a contiguous range of byte[] keys, when keys are sorted in unsigned lexical order. Instances are defined by an inclusive lower bound and an exclusive upper bound. The upper bound may be specified as null to represent no maximum.

Instances are immutable: the minimum and maximum byte[] arrays are copied during construction and when accessed by getMin() and getMax().

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final KeyRange
    FULL
    The KeyRange containing the full range (i.e., all keys).
    protected final byte[]
    max
    Upper bound (exclusive), or null for no maximum.
    protected final byte[]
    min
    Lower bound (inclusive), or null for no minimum.
    static final Comparator<KeyRange>
    SORT_BY_MAX
    Sorts instances by max value, then min value.
    static final Comparator<KeyRange>
    SORT_BY_MIN
    Sorts instances by min value, then max value.

  • Constructor Summary

    Constructors
    Constructor
    Description
    KeyRange(byte[] key)
    Construct key range containing a single key.
    KeyRange(byte[] min, byte[] max)
    Constructor.

  • Method Summary

    Modifier and Type
    Method
    Description
    static int
    compare(byte[] key1, byte[] key2)
    Compare two byte[] keys using unsigned lexical ordering, while also accepting null values that represent "positive infinity".
    int
    compareTo(byte[] key)
    Determine if this range is left of, contains, or is right of the given key.
    boolean
    contains(byte[] key)
    Determine if this key range contains the specified key.
    boolean
    contains(KeyRange range)
    Determine if this key range fully contains the specified key range.
    static KeyRange
    empty(byte[] key)
    Create an empty key range at the specified key.
    boolean
    equals(Object obj)
     
    static KeyRange
    forPrefix(byte[] prefix)
    Construct an instance containing all keys with the given prefix.
    byte[]
    getMax()
    Get range maximum (exclusive), or null if there is no upper bound.
    byte[]
    getMin()
    Get range minimum (inclusive).
    int
    hashCode()
     
    boolean
    isEmpty()
    Determine whether this instance contains zero keys (implying getMin()== getMax()).
    boolean
    isFull()
    Determine whether this instance contains the full range covering all keys.
    boolean
    isPrefixRange()
    Determine whether this instance contains all keys having some common prefix.
    boolean
    isSingleKey()
    Determine whether this instance contains exactly one key.
    boolean
    overlaps(KeyRange range)
    Determine if this key range overlaps the specified key range, i.e., there exists at least one byte[] key that both ranges have in common.
    KeyRange
    prefixedBy(byte[] prefix)
    Create a new instance whose minimum and maximum keys are the same as this instance's but with the given byte sequence prepended.
    String
    toString()
     

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait

  • Field Details

    • FULL

      public static final KeyRange FULL
      The KeyRange containing the full range (i.e., all keys).

    • SORT_BY_MIN

      public static final Comparator<KeyRange> SORT_BY_MIN
      Sorts instances by min value, then max value.

    • SORT_BY_MAX

      public static final Comparator<KeyRange> SORT_BY_MAX
      Sorts instances by max value, then min value.

    • min

      protected final byte[] min
      Lower bound (inclusive), or null for no minimum. Subclasses must not modify the array (to preserve immutability).

    • max

      protected final byte[] max
      Upper bound (exclusive), or null for no maximum. Subclasses must not modify the array (to preserve immutability).

  • Constructor Details

    • KeyRange

      public KeyRange(byte[] min, byte[] max)
      Constructor.
      Parameters:
      min - minimum key (inclusive); must not be null
      max - maximum key (exclusive), or null for no maximum
      Throws:
      IllegalArgumentException - if min is null
      IllegalArgumentException - if min > max

    • KeyRange

      public KeyRange(byte[] key)
      Construct key range containing a single key.
      Parameters:
      key - the key contained in the range
      Throws:
      IllegalArgumentException - if key is null

  • Method Details

    • forPrefix

      public static KeyRange forPrefix(byte[] prefix)
      Construct an instance containing all keys with the given prefix.
      Parameters:
      prefix - prefix of all keys in the range
      Returns:
      range of keys prefixed by prefix
      Throws:
      IllegalArgumentException - if prefix is null

    • getMin

      public byte[] getMin()
      Get range minimum (inclusive).

      This method returns a copy of the minimum, so changes do not affect this instance.

      Returns:
      inclusivie minimum, never null

    • getMax

      public byte[] getMax()
      Get range maximum (exclusive), or null if there is no upper bound.

      This method returns a copy of the maximum, so changes do not affect this instance.

      Returns:
      exclusivie maximum, or null for none

    • overlaps

      public boolean overlaps(KeyRange range)
      Determine if this key range overlaps the specified key range, i.e., there exists at least one byte[] key that both ranges have in common.
      Parameters:
      range - other instance
      Returns:
      true if this instance overlaps range
      Throws:
      IllegalArgumentException - if range is null

    • contains

      public boolean contains(KeyRange range)
      Determine if this key range fully contains the specified key range.
      Parameters:
      range - other instance
      Returns:
      true if this instance contains range
      Throws:
      IllegalArgumentException - if range is null

    • contains

      public boolean contains(byte[] key)
      Determine if this key range contains the specified key.
      Parameters:
      key - key to test
      Returns:
      true if this range contains key
      Throws:
      IllegalArgumentException - if key is null

    • isFull

      public boolean isFull()
      Determine whether this instance contains the full range covering all keys.
      Returns:
      true if this instance contains all keys

    • isSingleKey

      public boolean isSingleKey()
      Determine whether this instance contains exactly one key.

      If so, getMin() returns the key.

      Returns:
      true if this instance contains exactly one key, otherwise false

    • isPrefixRange

      public boolean isPrefixRange()
      Determine whether this instance contains all keys having some common prefix.

      If so, getMin() returns the prefix.

      Returns:
      true if this instance contains all keys having some common prefix, otherwise false

    • isEmpty

      public boolean isEmpty()
      Determine whether this instance contains zero keys (implying getMin()== getMax()).
      Returns:
      true if this instance contains no keys

    • prefixedBy

      public KeyRange prefixedBy(byte[] prefix)
      Create a new instance whose minimum and maximum keys are the same as this instance's but with the given byte sequence prepended.
      Parameters:
      prefix - key range prefix
      Returns:
      this range prefixed by prefix
      Throws:
      IllegalArgumentException - if prefix is null

    • compareTo

      public int compareTo(byte[] key)
      Determine if this range is left of, contains, or is right of the given key.
      Parameters:
      key - key for comparison
      Returns:
      -1 if this range is left of key, 0 if this range contains key, or 1 if this range is right of key,
      Throws:
      IllegalArgumentException - if key is null

    • compare

      public static int compare(byte[] key1, byte[] key2)
      Compare two byte[] keys using unsigned lexical ordering, while also accepting null values that represent "positive infinity".
      Parameters:
      key1 - first key
      key2 - second key
      Returns:
      -1 if key1 < key2, 1 if key1 > key2, or zero if key1 = key2

    • empty

      public static KeyRange empty(byte[] key)
      Create an empty key range at the specified key.
      Parameters:
      key - the minimum and maximum key
      Returns:
      the empty key range [key,key)
      Throws:
      IllegalArgumentException - if key is null

    • equals

      public boolean equals(Object obj)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object