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

Modifier and Type	Method and 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
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