Package com.apple.foundationdb.subspace

Class Subspace

java.lang.Object
com.apple.foundationdb.subspace.Subspace
Direct Known Subclasses:
DirectorySubspace
public class Subspace extends 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
    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
    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(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(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(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 representing 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.
    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

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait

  • Constructor Details

    • 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:
      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:
      IllegalArgumentException - if prefix contains any incomplete Versionstamps

  • Method Details

    • equals

      public boolean equals(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 Object
      Parameters:
      rhs - the object to check for equality
      Returns:
      true if this Subspace and rhs have equal prefixes

    • toString

      public 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 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 Object
      Returns:
      a hash of this subspace

    • get

      public Subspace get(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(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:
      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 representing 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