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 use `Tuple`s to define namespaces for different categories of data. The namespace is specified by a prefix `Tuple` which is prepended to all `Tuple`s 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
`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

All Methods Instance Methods Concrete Methods
`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​(Tuple tuple)` Gets a new subspace which is equivalent to this subspace with its prefix `Tuple` extended by the specified `Tuple`.
`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`.
`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​(Tuple tuple)` Gets the key encoding the specified tuple in this `Subspace`.
`byte[]` `pack​(java.lang.Object obj)` Gets the key encoding the specified `Object` 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 `Versionstamp`s as any of its entries.

Parameters:
  `prefix` - a `Tuple` used to form the subspace
Throws:
  `java.lang.IllegalArgumentException` - if `prefix` contains any incomplete `Versionstamp`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 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 `Versionstamp`s 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 `Versionstamp`s

### Method Detail

#### equals

    public boolean equals​(java.lang.Object rhs)

Returns true if this `Subspace` is equal to `rhs`. Two `Subspace`s 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 `Tuple`s
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 `Tuple`s
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`