Package io.permazen.kv

Interface KeyFilter

All Known Implementing Classes:
KeyRanges, Reads
public interface KeyFilter
A predicate for filtering byte[] keys that is also capable of efficiently jumping over contiguous regions of uncontained keys.

Instances assume byte[] keys are ordered in unsigned lexicographical order.

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    contains(byte[] key)
    Determine whether this instance contains the given key.
    byte[]
    seekHigher(byte[] key)
    Skip over the largest possible uncontained region in an upward direction.
    byte[]
    seekLower(byte[] key)
    Skip over the largest possible uncontained region in a downward direction.

  • Method Details

    • contains

      boolean contains(byte[] key)
      Determine whether this instance contains the given key.
      Parameters:
      key - key to test
      Returns:
      true if key is contained by this instance, otherwise false
      Throws:
      IllegalArgumentException - if key is null

    • seekHigher

      byte[] seekHigher(byte[] key)
      Skip over the largest possible uncontained region in an upward direction.

      This method should return an inclusive lower bound on all keys greater than or equal to key that are contained by this instance. The bound does not have to be tight, but the tighter the better.

      A value of null may be returned to indicate that no key greater than or equal to key is contained by this instance.

      If key is contained by this instance, this method must return key; if key is not contained by this instance, this method must return a key strictly higher than key or null.

      Parameters:
      key - starting key
      Returns:
      a lower bound (inclusive) for contained keys greater than or equal to key, or null if no key greater than or equal to key is contained by this instance
      Throws:
      IllegalArgumentException - if key is null

    • seekLower

      byte[] seekLower(byte[] key)
      Skip over the largest possible uncontained region in a downward direction.

      This method should return an exclusive upper bound on all keys strictly less than key that are contained by this instance. The bound does not have to be tight, but the tighter the better.

      A value of null may be returned to indicate that no key strictly less than key is contained by this instance.

      For the purposes of this method, an empty byte[] array represents an upper bound greater than all byte[] keys. This interpretation applies both to the key parameter and returned value. Note that this implies an empty array cannot be returned to indicate that no keys exist (instead, return null).

      This method must either return null or a value less than or equal to key (using the above interpretation for empty arrays).

      Parameters:
      key - starting key, or an empty array to indicate a maximal upper bound
      Returns:
      an upper bound (exclusive) for contained keys strictly less that key, null if no key strictly less than key is contained by this instance, or an empty byte[] array to indicate an upper bound greater than all byte[] keys (which implies key was also empty)
      Throws:
      IllegalArgumentException - if key is null