com.apple.foundationdb

## Class KeySelector

- java.lang.Object
- - com.apple.foundationdb.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`:

- `lastLessThan`
- `lastLessOrEqual`
- `firstGreaterThan`
- `firstGreaterOrEqual`

This is an immutable class. The `add(int)` call does not modify internal state, but returns a new instance.

### Constructor Summary

Constructors
Constructor and 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
`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
`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`

#### 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`