com.apple.foundationdb.subspace

Class Subspace

java.lang.Object

com.apple.foundationdb.subspace.Subspace

Direct Known Subclasses:

DirectorySubspace

public class Subspace
extends java.lang.Object

Subspace provide a convenient way to use Tuples to define namespaces for different categories of data. The namespace is specified by a prefix Tuple which is prepended to all Tuples packed by the Subspace. When unpacking a key with the Subspace, the prefix Tuple will be removed from the result.

For general guidance on subspace usage, see the discussion in Developer Guide.

As a best practice, API clients should use at least one subspace for application data.

Constructor Summary

Constructors

Constructor and Description
Subspace() Constructor for a subspace formed with an empty prefix Tuple.
Subspace(byte[] rawPrefix) Constructor for a subspace formed with the specified byte string, which will be prepended to all packed keys.
Subspace(Tuple prefix) Constructor for a subspace formed with the specified prefix Tuple.
Subspace(Tuple prefix, byte[] rawPrefix) Constructor for a subspace formed with both a prefix Tuple and a prefix byte string.

Method Summary

Modifier and Type	Method and Description
boolean	contains(byte[] key) Tests whether the specified key starts with this Subspace's prefix, indicating that the Subspace logically contains key.
boolean	equals(java.lang.Object rhs) Returns true if this Subspace is equal to rhs.
Subspace	get(java.lang.Object obj) Gets a new subspace which is equivalent to this subspace with its prefix Tuple extended by the specified Object.
Subspace	get(Tuple tuple) Gets a new subspace which is equivalent to this subspace with its prefix Tuple extended by the specified Tuple.
byte[]	getKey() Gets the key encoding the prefix used for this Subspace.
int	hashCode() Returns a hash-table compatible hash of this subspace.
byte[]	pack() Gets the key encoding the prefix used for this Subspace.
byte[]	pack(java.lang.Object obj) Gets the key encoding the specified Object in this Subspace.
byte[]	pack(Tuple tuple) Gets the key encoding the specified tuple in this Subspace.
byte[]	packWithVersionstamp(Tuple tuple) Gets the key encoding the specified tuple in this Subspace for use with MutationType.SET_VERSIONSTAMPED_KEY.
Range	range() Gets a Range respresenting all keys strictly in the Subspace.
Range	range(Tuple tuple) Gets a Range representing all keys in the Subspace strictly starting with the specified Tuple.
Subspace	subspace(Tuple tuple) Gets a new subspace which is equivalent to this subspace with its prefix Tuple extended by the specified Tuple.
java.lang.String	toString() Create a human-readable string representation of this subspace.
Tuple	unpack(byte[] key) Gets the Tuple encoded by the given key, with this Subspace's prefix Tuple and raw prefix removed.

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

Subspace

public Subspace()

Constructor for a subspace formed with an empty prefix Tuple.

Subspace

public Subspace(Tuple prefix)

Constructor for a subspace formed with the specified prefix Tuple. Note that the Tuple prefix should not contain any incomplete Versionstamps as any of its entries.

Parameters:

prefix - a Tuple used to form the subspace

Throws:

java.lang.IllegalArgumentException - if prefix contains any incomplete Versionstamps

Subspace

public Subspace(byte[] rawPrefix)

Constructor for a subspace formed with the specified byte string, which will be prepended to all packed keys.

Parameters:

rawPrefix - a byte array used as the prefix for all packed keys

Subspace

public Subspace(Tuple prefix,
                byte[] rawPrefix)

Constructor for a subspace formed with both a prefix Tuple and a prefix byte string. The prefix Tuple will be prepended to all Tuples packed by the Subspace, and the byte string prefix will be prepended to the packed result. Note that the Tuple prefix should not contain any incomplete Versionstamps as any of its entries.

Parameters:

prefix - a Tuple used to form the subspace

rawPrefix - a byte array used as the prefix for all packed keys

Throws:

java.lang.IllegalArgumentException - if prefix contains any incomplete Versionstamps

Method Detail

equals

public boolean equals(java.lang.Object rhs)

Returns true if this Subspace is equal to rhs. Two Subspaces are equal if they have the same prefix.

Overrides:

equals in class java.lang.Object

Parameters:

rhs - the object to check for equality

Returns:

true if this Subspace and rhs have equal prefixes

toString

public java.lang.String toString()

Create a human-readable string representation of this subspace. This is really only useful for debugging purposes, but it includes information on what raw prefix the subspace is using.

Overrides:

toString in class java.lang.Object

Returns:

a printable representation of the subspace

hashCode

public int hashCode()

Returns a hash-table compatible hash of this subspace. This is based off of the hash of the underlying byte-array prefix.

Overrides:

hashCode in class java.lang.Object

Returns:

a hash of this subspace

get

public Subspace get(java.lang.Object obj)

Gets a new subspace which is equivalent to this subspace with its prefix Tuple extended by the specified Object. The object will be inserted into a Tuple and passed to get(Tuple).

Parameters:

obj - an Object compatible with Tuples

Returns:

a new subspace formed by joining this Subspace's prefix to obj

get

public Subspace get(Tuple tuple)

Gets a new subspace which is equivalent to this subspace with its prefix Tuple extended by the specified Tuple.

Parameters:

tuple - the Tuple used to form the new Subspace

Returns:

a new subspace formed by joining this Subspace's prefix to tuple

getKey

public byte[] getKey()

Gets the key encoding the prefix used for this Subspace. This is equivalent to pack()ing the empty Tuple.

Returns:

the key encoding the prefix used for this Subspace

pack

public byte[] pack()

Gets the key encoding the prefix used for this Subspace.

Returns:

the key encoding the prefix used for this Subspace

pack

public byte[] pack(java.lang.Object obj)

Gets the key encoding the specified Object in this Subspace. obj is inserted into a Tuple and packed with pack(Tuple).

Parameters:

obj - an Object to be packed that is compatible with Tuples

Returns:

the key encoding the tuple derived from obj

pack

public byte[] pack(Tuple tuple)

Gets the key encoding the specified tuple in this Subspace. For example, if you have a Subspace with prefix Tuple ("users") and you use it to pack the Tuple ("Smith"), the result is the same as if you packed the Tuple ("users", "Smith").

Parameters:

tuple - the Tuple to be packed

Returns:

the key encoding the specified tuple in this Subspace

packWithVersionstamp

public byte[] packWithVersionstamp(Tuple tuple)

Gets the key encoding the specified tuple in this Subspace for use with MutationType.SET_VERSIONSTAMPED_KEY. There must be exactly one incomplete Versionstamp included in the given Tuple. It will create a key that is within this Subspace that can be provided as the key argument to Transaction.mutate() with the SET_VERSIONSTAMPED_KEY mutation. This will throw an IllegalArgumentException if the Tuple does not contain an incomplete Versionstamp or if it contains multiple.

Parameters:

tuple - the Tuple to be packed

Returns:

the key encoding the specified tuple in this Subspace

Throws:

java.lang.IllegalArgumentException - if tuple does not contain exactly one incomplete Versionstamp

unpack

public Tuple unpack(byte[] key)

Gets the Tuple encoded by the given key, with this Subspace's prefix Tuple and raw prefix removed.

Parameters:

key - The key being decoded

Returns:

the Tuple encoded by key with the prefix removed

range

public Range range()

Gets a Range respresenting all keys strictly in the Subspace.

Returns:

the Range of keyspace corresponding to this Subspace

range

public Range range(Tuple tuple)

Gets a Range representing all keys in the Subspace strictly starting with the specified Tuple.

Parameters:

tuple - the Tuple whose sub-keys we are searching for

Returns:

the Range of keyspace corresponding to tuple

contains

public boolean contains(byte[] key)

Tests whether the specified key starts with this Subspace's prefix, indicating that the Subspace logically contains key.

Parameters:

key - the key to be tested

Returns:

true if key starts with Subspace.key()

subspace

public Subspace subspace(Tuple tuple)

Gets a new subspace which is equivalent to this subspace with its prefix Tuple extended by the specified Tuple.

Parameters:

tuple - the Tuple used to form the new Subspace

Returns:

a new subspace formed by joining this Subspace's prefix to tuple