Package com.apple.foundationdb.subspace

Class 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 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

      All Methods Instance Methods Concrete Methods 
      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​(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 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