Package com.apple.foundationdb

Class KeySelector

  • public class KeySelector
extends java.lang.Object
    A KeySelector identifies a particular key in the database. FoundationDB's lexicographically ordered data model permits finding keys based on their order (for example, finding the first key in the database greater than a given key). Key selectors represent a description of a key in the database that could be resolved to an actual key by Transaction's getKey() or used directly as the beginning or end of a range in Transaction's getRange().

    For more about how key selectors work in practice, see the KeySelector documentation. Note that the way the key selectors are resolved is somewhat non-intuitive, so users who wish to use a key selector other than the default ones described below should probably consult that documentation before proceeding.

    Generally one of the following static methods should be used to construct a KeySelector:
    This is an immutable class. The add(int) call does not modify internal state, but returns a new instance.

    • Constructor Summary

      Constructors 
      Constructor Description
      KeySelector​(byte[] key, boolean orEqual, int offset)
      Constructs a new KeySelector from the given parameters.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      KeySelector add​(int offset)
      Returns a new KeySelector offset by a given number of keys from this one.
      static KeySelector firstGreaterOrEqual​(byte[] key)
      Creates a KeySelector that picks the first key greater than or equal to the parameter
      static KeySelector firstGreaterThan​(byte[] key)
      Creates a KeySelector that picks the first key greater than the parameter
      byte[] getKey()
      Returns a copy of the key that serves as the anchor for this KeySelector.
      int getOffset()
      Returns the key offset parameter for this KeySelector.
      static KeySelector lastLessOrEqual​(byte[] key)
      Creates a KeySelector that picks the last key less than or equal to the parameter
      static KeySelector lastLessThan​(byte[] key)
      Creates a KeySelector that picks the last key less than the parameter
      boolean orEqual()
      Returns the orEqual parameter for this KeySelector.
      java.lang.String toString()  

      • Methods inherited from class java.lang.Object

        equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

    • Constructor Detail

      • KeySelector

        public KeySelector​(byte[] key,
                   boolean orEqual,
                   int offset)
        Constructs a new KeySelector from the given parameters. Client code will not generally call this constructor. A key selector can be used to specify a key that will be resolved at runtime based on a starting key and an offset. When this is passed as an argument to a Transaction's getKey() or getRange() methods, the key selector will be resolved to a key within the database. This is done in a manner equivalent to finding the last key that is less than (or less than or equal to, if orEqual is true) the base key specified here and then returning the key that is offset keys greater than that key.
        Parameters:
        key - the base key to reference
        orEqual - true if the key selector should resolve to key (if key is present) before accounting for the offset
        offset - the offset (in number of keys) that the selector will advance after resolving to a key based on the key and orEqual parameters

    • Method Detail

      • lastLessThan

        public static KeySelector lastLessThan​(byte[] key)
        Creates a KeySelector that picks the last key less than the parameter
        Parameters:
        key - the key to use as the edge of the edge of selection criteria
        Returns:
        a newly created KeySelector

      • lastLessOrEqual

        public static KeySelector lastLessOrEqual​(byte[] key)
        Creates a KeySelector that picks the last key less than or equal to the parameter
        Parameters:
        key - the key to use as the edge of the edge of selection criteria
        Returns:
        a newly created KeySelector

      • firstGreaterThan

        public static KeySelector firstGreaterThan​(byte[] key)
        Creates a KeySelector that picks the first key greater than the parameter
        Parameters:
        key - the key to use as the edge of the edge of selection criteria
        Returns:
        a newly created KeySelector

      • firstGreaterOrEqual

        public static KeySelector firstGreaterOrEqual​(byte[] key)
        Creates a KeySelector that picks the first key greater than or equal to the parameter
        Parameters:
        key - the key to use as the edge of the edge of selection criteria
        Returns:
        a newly created KeySelector

      • add

        public KeySelector add​(int offset)
        Returns a new KeySelector offset by a given number of keys from this one. For example, an offset of 1 means that the new KeySelector specifies the key in the database after the key selected by this KeySelector. The offset can be negative; these will move the selector to previous keys in the database.

        Note that large offsets take time O(offset) to resolve, making them a poor choice for iterating through a large range. (Instead, use the keys returned from a range query operation themselves to create a new beginning KeySelector.) For more information see the KeySelector documentation.
        Parameters:
        offset - the number of keys to offset the KeySelector. This number can be negative.
        Returns:
        a newly created KeySelector that is offset by a number of keys.

      • getKey

        public byte[] getKey()
        Returns a copy of the key that serves as the anchor for this KeySelector. This is not the key to which this KeySelector would resolve to. For this function see ReadTransaction.getKey(KeySelector).
        Returns:
        a copy of the "anchor" key for this KeySelector.

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object

      • orEqual

        public boolean orEqual()
        Returns the orEqual parameter for this KeySelector. See the KeySelector(byte[], boolean, int) KeySelector constructor} for more details.
        Returns:
        the or-equal parameter of this KeySelector.

      • getOffset

        public int getOffset()
        Returns the key offset parameter for this KeySelector. See the KeySelector constructor for more details.
        Returns:
        the key offset for this KeySelector