Package 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 useTuple
s to define namespaces for different categories of data. The namespace is specified by a prefixTuple
which is prepended to allTuple
s packed by theSubspace
. When unpacking a key with theSubspace
, the prefixTuple
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 Description Subspace()
Constructor for a subspace formed with an empty prefixTuple
.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 prefixTuple
.Subspace(Tuple prefix, byte[] rawPrefix)
Constructor for a subspace formed with both a prefixTuple
and a prefix byte string.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description boolean
contains(byte[] key)
Tests whether the specified key starts with thisSubspace
's prefix, indicating that theSubspace
logically contains key.boolean
equals(java.lang.Object rhs)
Returns true if thisSubspace
is equal torhs
.Subspace
get(Tuple tuple)
Subspace
get(java.lang.Object obj)
Gets a new subspace which is equivalent to this subspace with its prefixTuple
extended by the specifiedObject
.byte[]
getKey()
Gets the key encoding the prefix used for thisSubspace
.int
hashCode()
Returns a hash-table compatible hash of this subspace.byte[]
pack()
Gets the key encoding the prefix used for thisSubspace
.byte[]
pack(Tuple tuple)
Gets the key encoding the specified tuple in thisSubspace
.byte[]
pack(java.lang.Object obj)
Gets the key encoding the specifiedObject
in thisSubspace
.byte[]
packWithVersionstamp(Tuple tuple)
Gets the key encoding the specified tuple in thisSubspace
for use withMutationType.SET_VERSIONSTAMPED_KEY
.Range
range()
Gets aRange
respresenting all keys strictly in theSubspace
.Range
range(Tuple tuple)
Subspace
subspace(Tuple tuple)
java.lang.String
toString()
Create a human-readable string representation of this subspace.Tuple
unpack(byte[] key)
-
-
-
Constructor Detail
-
Subspace
public Subspace()
Constructor for a subspace formed with an empty prefixTuple
.
-
Subspace
public Subspace(Tuple prefix)
Constructor for a subspace formed with the specified prefixTuple
. Note that theTuple
prefix
should not contain any incompleteVersionstamp
s as any of its entries.- Parameters:
prefix
- aTuple
used to form the subspace- Throws:
java.lang.IllegalArgumentException
- ifprefix
contains any incompleteVersionstamp
s
-
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 prefixTuple
and a prefix byte string. The prefixTuple
will be prepended to allTuples
packed by theSubspace
, and the byte string prefix will be prepended to the packed result. Note that theTuple
prefix
should not contain any incompleteVersionstamp
s as any of its entries.- Parameters:
prefix
- aTuple
used to form the subspacerawPrefix
- a byte array used as the prefix for all packed keys- Throws:
java.lang.IllegalArgumentException
- ifprefix
contains any incompleteVersionstamp
s
-
-
Method Detail
-
equals
public boolean equals(java.lang.Object rhs)
Returns true if thisSubspace
is equal torhs
. TwoSubspace
s are equal if they have the same prefix.- Overrides:
equals
in classjava.lang.Object
- Parameters:
rhs
- the object to check for equality- Returns:
true
if thisSubspace
andrhs
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 classjava.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 classjava.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 prefixTuple
extended by the specifiedObject
. The object will be inserted into aTuple
and passed toget(Tuple)
.- Parameters:
obj
- anObject
compatible withTuple
s- Returns:
- a new subspace formed by joining this
Subspace
's prefix toobj
-
get
public Subspace get(Tuple tuple)
Gets a new subspace which is equivalent to this subspace with its prefixTuple
extended by the specifiedTuple
.- Parameters:
tuple
- theTuple
used to form the newSubspace
- Returns:
- a new subspace formed by joining this
Subspace
's prefix totuple
-
getKey
public byte[] getKey()
Gets the key encoding the prefix used for thisSubspace
. This is equivalent topack()
ing the emptyTuple
.- Returns:
- the key encoding the prefix used for this
Subspace
-
pack
public byte[] pack()
Gets the key encoding the prefix used for thisSubspace
.- Returns:
- the key encoding the prefix used for this
Subspace
-
pack
public byte[] pack(java.lang.Object obj)
Gets the key encoding the specifiedObject
in thisSubspace
.obj
is inserted into aTuple
and packed withpack(Tuple)
.- Parameters:
obj
- anObject
to be packed that is compatible withTuple
s- Returns:
- the key encoding the tuple derived from
obj
-
pack
public byte[] pack(Tuple tuple)
Gets the key encoding the specified tuple in thisSubspace
. For example, if you have aSubspace
with prefixTuple
("users")
and you use it to pack theTuple
("Smith")
, the result is the same as if you packed theTuple
("users", "Smith")
.- Parameters:
tuple
- theTuple
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 thisSubspace
for use withMutationType.SET_VERSIONSTAMPED_KEY
. There must be exactly one incompleteVersionstamp
included in the givenTuple
. It will create a key that is within thisSubspace
that can be provided as thekey
argument toTransaction.mutate()
with theSET_VERSIONSTAMPED_KEY
mutation. This will throw anIllegalArgumentException
if theTuple
does not contain an incompleteVersionstamp
or if it contains multiple.- Parameters:
tuple
- theTuple
to be packed- Returns:
- the key encoding the specified tuple in this
Subspace
- Throws:
java.lang.IllegalArgumentException
- iftuple
does not contain exactly one incompleteVersionstamp
-
unpack
public Tuple unpack(byte[] key)
- Parameters:
key
- The key being decoded- Returns:
- the
Tuple
encoded bykey
with the prefix removed
-
range
public Range range()
Gets aRange
respresenting all keys strictly in theSubspace
.- Returns:
- the
Range
of keyspace corresponding to thisSubspace
-
range
public Range range(Tuple tuple)
- Parameters:
tuple
- theTuple
whose sub-keys we are searching for- Returns:
- the
Range
of keyspace corresponding totuple
-
contains
public boolean contains(byte[] key)
Tests whether the specified key starts with thisSubspace
's prefix, indicating that theSubspace
logically contains key.- Parameters:
key
- the key to be tested- Returns:
true
ifkey
starts withSubspace.key()
-
-