Package com.apple.foundationdb.tuple

Class Tuple

java.lang.Object
com.apple.foundationdb.tuple.Tuple
All Implemented Interfaces:
Comparable<Tuple>, Iterable<Object>
public class Tuple extends Object implements Comparable<Tuple>, Iterable<Object>
Represents a set of elements that make up a sortable, typed key. This object is comparable with other Tuples and will sort in Java in the same order in which they would sort in FoundationDB. Tuples sort first by the first element, then by the second, etc. This makes the tuple layer ideal for building a variety of higher-level data models.

Types

A Tuple can contain byte arrays (byte[]), Strings, Numbers, UUIDs, booleans, Lists, Versionstamps, other Tuples, and null. Float and Double instances will be serialized as single- and double-precision numbers respectively, and BigIntegers within the range [-2^2040+1, 2^2040-1] are serialized without loss of precision (those outside the range will raise an IllegalArgumentException). All other Numbers will be converted to a long integral value, so the range will be constrained to [-2^63, 2^63-1]. Note that for numbers outside this range the way that Java truncates integral values may yield unexpected results.

null values

The FoundationDB tuple specification has a special type-code for None; nil; or, as Java would understand it, null. The behavior of the layer in the presence of null varies by type with the intention of matching expected behavior in Java. byte[], Strings, UUIDs, and nested Lists and Tuples can be null, whereas numbers (e.g., longs and doubles) and booleans cannot. This means that the typed getters (getBytes(), getString()), getUUID(), getNestedTuple(), getVersionstamp, and getNestedList()) will return null if the entry at that location was null and the typed adds (add(byte[]), add(String), add(Versionstamp) add(Tuple), and add(List)) will accept null. The typed get for integers and other typed getters, however, will throw a NullPointerException if the entry in the Tuple was null at that position.

This class is not thread safe.

  • Constructor Summary

    Constructors
    Constructor
    Description
    Tuple()
    Construct a new empty Tuple.

  • Method Summary

    Modifier and Type
    Method
    Description
    Tuple
    add(boolean b)
    Creates a copy of this Tuple with a boolean appended as the last element.
    Tuple
    add(byte[] b)
    Creates a copy of this Tuple with a byte array appended as the last element.
    Tuple
    add(byte[] b, int offset, int length)
    Creates a copy of this Tuple with a byte array appended as the last element.
    Tuple
    add(double d)
    Creates a copy of this Tuple with a double appended as the last element.
    Tuple
    add(float f)
    Creates a copy of this Tuple with a float appended as the last element.
    Tuple
    add(long l)
    Creates a copy of this Tuple with a long appended as the last element.
    Tuple
    add(Tuple t)
    Creates a copy of this Tuple with a Tuple appended as the last element.
    Tuple
    add(Versionstamp v)
    Creates a copy of this Tuple with a Versionstamp object appended as the last element.
    Tuple
    add(String s)
    Creates a copy of this Tuple with a String appended as the last element.
    Tuple
    add(BigInteger bi)
    Creates a copy of this Tuple with a BigInteger appended as the last element.
    Tuple
    add(List<?> l)
    Creates a copy of this Tuple with a List appended as the last element.
    Tuple
    add(UUID uuid)
    Creates a copy of this Tuple with a UUID appended as the last element.
    Tuple
    addAll(Tuple other)
    Create a copy of this Tuple with all elements from anther Tuple appended.
    Tuple
    addAll(List<?> o)
    Create a copy of this Tuple with a list of items appended.
    Tuple
    addObject(Object o)
    Creates a copy of this Tuple with an appended last element.
    int
    compareTo(Tuple t)
    Compare the byte-array representation of this Tuple against another.
    boolean
    equals(Object o)
    Tests for equality with another Tuple.
    static Tuple
    from(Object... items)
    Creates a new Tuple from a variable number of elements.
    static Tuple
    fromBytes(byte[] bytes)
    Construct a new Tuple with elements decoded from a supplied byte array.
    static Tuple
    fromBytes(byte[] bytes, int offset, int length)
    Construct a new Tuple with elements decoded from a supplied byte array.
    static Tuple
    fromItems(Iterable<?> items)
    Creates a new Tuple from a variable number of elements.
    static Tuple
    fromList(List<?> items)
    Efficiently creates a new Tuple from a list of objects.
    static Tuple
    fromStream(Stream<?> items)
    Efficiently creates a new Tuple from a Stream of objects.
    Object
    get(int index)
    Gets an indexed item without forcing a type.
    BigInteger
    getBigInteger(int index)
    Gets an indexed item as a BigInteger.
    boolean
    getBoolean(int index)
    Gets an indexed item as a boolean.
    byte[]
    getBytes(int index)
    Gets an indexed item as a byte[].
    double
    getDouble(int index)
    Gets an indexed item as a double.
    float
    getFloat(int index)
    Gets an indexed item as a float.
    List<Object>
    getItems()
    Gets the unserialized contents of this Tuple.
    long
    getLong(int index)
    Gets an indexed item as a long.
    List<Object>
    getNestedList(int index)
    Gets an indexed item as a List.
    Tuple
    getNestedTuple(int index)
    Gets an indexed item as a Tuple.
    int
    getPackedSize()
    Get the number of bytes in the packed representation of this Tuple.
    String
    getString(int index)
    Gets an indexed item as a String.
    UUID
    getUUID(int index)
    Gets an indexed item as a UUID.
    Versionstamp
    getVersionstamp(int index)
    Gets an indexed item as a Versionstamp.
    int
    hashCode()
    Returns a hash code value for this Tuple.
    boolean
    hasIncompleteVersionstamp()
    Determines if there is a Versionstamp included in this Tuple that has not had its transaction version set.
    boolean
    isEmpty()
    Determine if this Tuple contains no elements.
    Iterator<Object>
    iterator()
    Gets an Iterator over the Objects in this Tuple.
    byte[]
    pack()
    Get an encoded representation of this Tuple.
    byte[]
    pack(byte[] prefix)
    Get an encoded representation of this Tuple.
    void
    packInto(ByteBuffer dest)
    Pack an encoded representation of this Tuple onto the end of the given ByteBuffer.
    byte[]
    packWithVersionstamp()
    Get an encoded representation of this Tuple for use with MutationType.SET_VERSIONSTAMPED_KEY.
    byte[]
    packWithVersionstamp(byte[] prefix)
    Get an encoded representation of this Tuple for use with MutationType.SET_VERSIONSTAMPED_KEY.
    Tuple
    popBack()
    Creates a new Tuple with the last item of this Tuple removed.
    Tuple
    popFront()
    Creates a new Tuple with the first item of this Tuple removed.
    Range
    range()
    Returns a range representing all keys that encode Tuples strictly starting with this Tuple.
    Range
    range(byte[] prefix)
    Returns a range representing all keys that encode Tuples strictly starting with the given prefix followed by this Tuple.
    int
    size()
    Gets the number of elements in this Tuple.
    Stream<Object>
    stream()
    Gets a Stream of the unserialized contents of this Tuple.
    String
    toString()
    Returns a string representing this Tuple.

    Methods inherited from class java.lang.Object

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

    Methods inherited from interface java.lang.Iterable

    forEach, spliterator

  • Constructor Details

  • Method Details

    • addObject

      public Tuple addObject(Object o)
      Creates a copy of this Tuple with an appended last element. The parameter is untyped but only String, byte[], Numbers, UUIDs, Booleans, Lists, Tuples, and null are allowed. If an object of another type is passed, then an IllegalArgumentException is thrown.
      Parameters:
      o - the object to append. Must be String, byte[], Numbers, UUID, List, Boolean, or null.
      Returns:
      a newly created Tuple

    • add

      public Tuple add(String s)
      Creates a copy of this Tuple with a String appended as the last element.
      Parameters:
      s - the String to append
      Returns:
      a newly created Tuple

    • add

      public Tuple add(long l)
      Creates a copy of this Tuple with a long appended as the last element.
      Parameters:
      l - the number to append
      Returns:
      a newly created Tuple

    • add

      public Tuple add(byte[] b)
      Creates a copy of this Tuple with a byte array appended as the last element.
      Parameters:
      b - the bytes to append
      Returns:
      a newly created Tuple

    • add

      public Tuple add(boolean b)
      Creates a copy of this Tuple with a boolean appended as the last element.
      Parameters:
      b - the boolean to append
      Returns:
      a newly created Tuple

    • add

      public Tuple add(UUID uuid)
      Creates a copy of this Tuple with a UUID appended as the last element.
      Parameters:
      uuid - the UUID to append
      Returns:
      a newly created Tuple

    • add

      public Tuple add(BigInteger bi)
      Creates a copy of this Tuple with a BigInteger appended as the last element. As Tuples cannot contain null numeric types, a NullPointerException is raised if a null argument is passed.
      Parameters:
      bi - the BigInteger to append
      Returns:
      a newly created Tuple

    • add

      public Tuple add(float f)
      Creates a copy of this Tuple with a float appended as the last element.
      Parameters:
      f - the float to append
      Returns:
      a newly created Tuple

    • add

      public Tuple add(double d)
      Creates a copy of this Tuple with a double appended as the last element.
      Parameters:
      d - the double to append
      Returns:
      a newly created Tuple

    • add

      public Tuple add(Versionstamp v)
      Creates a copy of this Tuple with a Versionstamp object appended as the last element.
      Parameters:
      v - the Versionstamp to append
      Returns:
      a newly created Tuple

    • add

      public Tuple add(List<?> l)
      Creates a copy of this Tuple with a List appended as the last element. This does not add the elements individually (for that, use Tuple.addAll). This adds the list as a single element nested within the outer Tuple.
      Parameters:
      l - the List to append
      Returns:
      a newly created Tuple

    • add

      public Tuple add(Tuple t)
      Creates a copy of this Tuple with a Tuple appended as the last element. This does not add the elements individually (for that, use Tuple.addAll). This adds the list as a single element nested within the outer Tuple.
      Parameters:
      t - the Tuple to append
      Returns:
      a newly created Tuple

    • add

      public Tuple add(byte[] b, int offset, int length)
      Creates a copy of this Tuple with a byte array appended as the last element.
      Parameters:
      b - the bytes to append
      offset - the starting index of b to add
      length - the number of elements of b to copy into this Tuple
      Returns:
      a newly created Tuple

    • addAll

      public Tuple addAll(List<?> o)
      Create a copy of this Tuple with a list of items appended.
      Parameters:
      o - the list of objects to append. Elements must be String, byte[], Numbers, or null.
      Returns:
      a newly created Tuple

    • addAll

      public Tuple addAll(Tuple other)
      Create a copy of this Tuple with all elements from anther Tuple appended.
      Parameters:
      other - the Tuple whose elements should be appended
      Returns:
      a newly created Tuple

    • pack

      public byte[] pack()
      Get an encoded representation of this Tuple. Each element is encoded to bytes and concatenated. Note that once a Tuple has been packed, its serialized representation is stored internally so that future calls to this function are faster than the initial call.
      Returns:
      a packed representation of this Tuple

    • pack

      public byte[] pack(byte[] prefix)
      Get an encoded representation of this Tuple. Each element is encoded to bytes and concatenated, and then the prefix supplied is prepended to the array. Note that once a Tuple has been packed, its serialized representation is stored internally so that future calls to this function are faster than the initial call.
      Parameters:
      prefix - additional byte-array prefix to prepend to the packed bytes
      Returns:
      a packed representation of this Tuple prepended by the prefix

    • packInto

      public void packInto(ByteBuffer dest)
      Pack an encoded representation of this Tuple onto the end of the given ByteBuffer. It is up to the caller to ensure that there is enough space allocated within the buffer to avoid BufferOverflowExceptions. The client may call getPackedSize() to determine how large this Tuple will be once packed in order to allocate sufficient memory. Note that unlike pack(), the serialized representation of this Tuple is not stored, so calling this function multiple times with the same Tuple requires serializing the Tuple multiple times.

      This method will throw an error if there are any incomplete Versionstamps in this Tuple.
      Parameters:
      dest - the destination ByteBuffer for the encoded Tuple

    • packWithVersionstamp

      public byte[] packWithVersionstamp()
      Get an encoded representation of this Tuple for use with MutationType.SET_VERSIONSTAMPED_KEY. This works the same as the one-paramter version of this method, but it does not add any prefix to the array.
      Returns:
      a packed representation of this Tuple for use with versionstamp ops.
      Throws:
      IllegalArgumentException - if there is not exactly one incomplete Versionstamp included in this Tuple

    • packWithVersionstamp

      public byte[] packWithVersionstamp(byte[] prefix)
      Get an encoded representation of this Tuple for use with MutationType.SET_VERSIONSTAMPED_KEY. There must be exactly one incomplete Versionstamp instance within this Tuple or this will throw an IllegalArgumentException. Each element is encoded to bytes and concatenated, the prefix is then prepended to the array, and then the index of the packed incomplete Versionstamp is appended as a little-endian integer. This can then be passed as the key to Transaction.mutate() with the SET_VERSIONSTAMPED_KEY MutationType, and the transaction's version will then be filled in at commit time.

      Note that once a Tuple has been packed, its serialized representation is stored internally so that future calls to this function are faster than the initial call.
      Parameters:
      prefix - additional byte-array prefix to prepend to packed bytes.
      Returns:
      a packed representation of this Tuple for use with versionstamp ops.
      Throws:
      IllegalArgumentException - if there is not exactly one incomplete Versionstamp included in this Tuple

    • getItems

      public List<Object> getItems()
      Gets the unserialized contents of this Tuple.
      Returns:
      the elements that make up this Tuple.

    • stream

      public Stream<Object> stream()
      Gets a Stream of the unserialized contents of this Tuple.
      Returns:
      a Stream of the elements that make up this Tuple.

    • iterator

      public Iterator<Object> iterator()
      Gets an Iterator over the Objects in this Tuple. This Iterator is unmodifiable and will throw an exception if remove() is called.
      Specified by:
      iterator in interface Iterable<Object>
      Returns:
      an unmodifiable Iterator over the elements in the Tuple.

    • fromBytes

      public static Tuple fromBytes(byte[] bytes)
      Construct a new Tuple with elements decoded from a supplied byte array. The passed byte array must not be null. This will throw an exception if the passed byte array does not represent a valid Tuple. For example, this will throw an error if it encounters an unknown type code or if there is a packed element that appears to be truncated.
      Parameters:
      bytes - encoded Tuple source
      Returns:
      a new Tuple constructed by deserializing the provided byte array
      Throws:
      IllegalArgumentException - if bytes does not represent a valid Tuple

    • fromBytes

      public static Tuple fromBytes(byte[] bytes, int offset, int length)
      Construct a new Tuple with elements decoded from a supplied byte array. The passed byte array must not be null. This will throw an exception if the specified slice of the passed byte array does not represent a valid Tuple. For example, this will throw an error if it encounters an unknown type code or if there is a packed element that appears to be truncated.
      Parameters:
      bytes - encoded Tuple source
      offset - starting offset of byte array of encoded data
      length - length of encoded data within the source
      Returns:
      a new Tuple constructed by deserializing the specified slice of the provided byte array
      Throws:
      IllegalArgumentException - if offset or length are negative or would exceed the size of the array or if bytes does not represent a valid Tuple

    • size

      public int size()
      Gets the number of elements in this Tuple.
      Returns:
      the number of elements in this Tuple

    • isEmpty

      public boolean isEmpty()
      Determine if this Tuple contains no elements.
      Returns:
      true if this Tuple contains no elements, false otherwise

    • getLong

      public long getLong(int index)
      Gets an indexed item as a long. This function will not do type conversion and so will throw a ClassCastException if the element is not a number type. The element at the index may not be null.
      Parameters:
      index - the location of the item to return
      Returns:
      the item at index as a long
      Throws:
      ClassCastException - if the element at index is not a Number
      NullPointerException - if the element at index is null

    • getBytes

      public byte[] getBytes(int index)
      Gets an indexed item as a byte[]. This function will not do type conversion and so will throw a ClassCastException if the tuple element is not a byte array.
      Parameters:
      index - the location of the element to return
      Returns:
      the item at index as a byte[]
      Throws:
      ClassCastException - if the element at index is not a Number

    • getString

      public String getString(int index)
      Gets an indexed item as a String. This function will not do type conversion and so will throw a ClassCastException if the tuple element is not of String type.
      Parameters:
      index - the location of the element to return
      Returns:
      the item at index as a String
      Throws:
      ClassCastException - if the element at index is not a String

    • getBigInteger

      public BigInteger getBigInteger(int index)
      Gets an indexed item as a BigInteger. This function will not do type conversion and so will throw a ClassCastException if the tuple element is not of a Number type. If the underlying type is a floating point value, this will lead to a loss of precision. The element at the index may not be null.
      Parameters:
      index - the location of the element to return
      Returns:
      the item at index as a BigInteger
      Throws:
      ClassCastException - if the element at index is not a Number

    • getFloat

      public float getFloat(int index)
      Gets an indexed item as a float. This function will not do type conversion and so will throw a ClassCastException if the element is not a number type. The element at the index may not be null.
      Parameters:
      index - the location of the item to return
      Returns:
      the item at index as a float
      Throws:
      ClassCastException - if the element at index is not a Number

    • getDouble

      public double getDouble(int index)
      Gets an indexed item as a double. This function will not do type conversion and so will throw a ClassCastException if the element is not a number type. The element at the index may not be null.
      Parameters:
      index - the location of the item to return
      Returns:
      the item at index as a double
      Throws:
      ClassCastException - if the element at index is not a Number

    • getBoolean

      public boolean getBoolean(int index)
      Gets an indexed item as a boolean. This function will not do type conversion and so will throw a ClassCastException if the element is not a Boolean. The element at the index may not be null.
      Parameters:
      index - the location of the item to return
      Returns:
      the item at index as a boolean
      Throws:
      ClassCastException - if the element at index is not a Boolean
      NullPointerException - if the element at index is null

    • getUUID

      public UUID getUUID(int index)
      Gets an indexed item as a UUID. This function will not do type conversion and so will throw a ClassCastException if the element is not a UUID. The element at the index may be null.
      Parameters:
      index - the location of the item to return
      Returns:
      the item at index as a UUID
      Throws:
      ClassCastException - if the element at index is not a UUID

    • getVersionstamp

      public Versionstamp getVersionstamp(int index)
      Gets an indexed item as a Versionstamp. This function will not do type conversion and so will throw a ClassCastException if the element is not a Versionstamp. The element at the index may be null.
      Parameters:
      index - the location of the item to return
      Returns:
      the item at index as a Versionstamp
      Throws:
      ClassCastException - if the element at index is not a Versionstamp

    • getNestedList

      public List<Object> getNestedList(int index)
      Gets an indexed item as a List. This function will not do type conversion and so will throw a ClassCastException if the element is not a List or Tuple. The element at the index may be null.
      Parameters:
      index - the location of the item to return
      Returns:
      the item at index as a List
      Throws:
      ClassCastException - if the element at index is not a List or a Tuple

    • getNestedTuple

      public Tuple getNestedTuple(int index)
      Gets an indexed item as a Tuple. This function will not do type conversion and so will throw a ClassCastException if the element is not a List or Tuple. The element at the index may be null.
      Parameters:
      index - the location of the item to return
      Returns:
      the item at index as a List
      Throws:
      ClassCastException - if the element at index is not a Tuple or a List

    • get

      public Object get(int index)
      Gets an indexed item without forcing a type.
      Parameters:
      index - the index of the item to return
      Returns:
      an item from the list, without forcing type conversion

    • popFront

      public Tuple popFront()
      Creates a new Tuple with the first item of this Tuple removed.
      Returns:
      a newly created Tuple without the first item of this Tuple
      Throws:
      IllegalStateException - if this Tuple is empty

    • popBack

      public Tuple popBack()
      Creates a new Tuple with the last item of this Tuple removed.
      Returns:
      a newly created Tuple without the last item of this Tuple
      Throws:
      IllegalStateException - if this Tuple is empty

    • range

      public Range range()
      Returns a range representing all keys that encode Tuples strictly starting with this Tuple.

      For example: 
         Tuple t = Tuple.from("a", "b");
   Range r = t.range();
      r includes all tuples ("a", "b", ...)
      This function will throw an error if this Tuple contains an incomplete Versionstamp.
      Returns:
      the range of keys containing all possible keys that have this Tuple as a strict prefix

    • range

      public Range range(byte[] prefix)
      Returns a range representing all keys that encode Tuples strictly starting with the given prefix followed by this Tuple.

      For example: 
         Tuple t = Tuple.from("a", "b");
   Range r = t.range(Tuple.from("c").pack());
      r contains all tuples ("c", "a", "b", ...)
      This function will throw an error if this Tuple contains an incomplete Versionstamp.
      Parameters:
      prefix - a byte prefix to precede all elements in the range
      Returns:
      the range of keys containing all possible keys that have prefix followed by this Tuple as a strict prefix

    • hasIncompleteVersionstamp

      public boolean hasIncompleteVersionstamp()
      Determines if there is a Versionstamp included in this Tuple that has not had its transaction version set. It will search through nested Tuples contained within this Tuple. It will not throw an error if it finds multiple incomplete Versionstamp instances.
      Returns:
      whether there is at least one incomplete Versionstamp included in this Tuple

    • getPackedSize

      public int getPackedSize()
      Get the number of bytes in the packed representation of this Tuple. This is done by summing the serialized sizes of all of the elements of this Tuple and does not pack everything into a single Tuple. The return value of this function is stored within this Tuple after this function has been called so that subsequent calls on the same object are fast. This method does not validate that there is not more than one incomplete Versionstamp in this Tuple.
      Returns:
      the number of bytes in the packed representation of this Tuple

    • compareTo

      public int compareTo(Tuple t)
      Compare the byte-array representation of this Tuple against another. This method will sort Tuples in the same order that they would be sorted as keys in FoundationDB. Returns a negative integer, zero, or a positive integer when this object's byte-array representation is found to be less than, equal to, or greater than the specified Tuple.
      Specified by:
      compareTo in interface Comparable<Tuple>
      Parameters:
      t - the Tuple against which to compare
      Returns:
      a negative integer, zero, or a positive integer when this Tuple is less than, equal, or greater than the parameter t.

    • hashCode

      public int hashCode()
      Returns a hash code value for this Tuple. Computing the hash code is fairly expensive as it involves packing the underlying Tuple to bytes. However, this value is memoized, so for any given Tuple, it only needs to be computed once. This means that it is generally safe to use Tuples with hash-based data structures such as HashSets or HashMaps.
      Overrides:
      hashCode in class Object
      Returns:
      a hash code for this Tuple that can be used by hash tables

    • equals

      public boolean equals(Object o)
      Tests for equality with another Tuple. If the passed object is not a Tuple this returns false. If the object is a Tuple, this returns true if compareTo() would return 0.
      Overrides:
      equals in class Object
      Returns:
      true if obj is a Tuple and their binary representation is identical

    • toString

      public String toString()
      Returns a string representing this Tuple. This contains human-readable representations of all of the elements of this Tuple. For most elements, this means using that object's default string representation. For byte-arrays, this means using ByteArrayUtil.printable() to produce a byte-string where most printable ASCII code points have been rendered as characters.
      Overrides:
      toString in class Object
      Returns:
      a human-readable String representation of this Tuple

    • fromItems

      public static Tuple fromItems(Iterable<?> items)
      Creates a new Tuple from a variable number of elements. The elements must follow the type guidelines from add, and so can only be Strings, byte[]s, Numbers, UUIDs, Booleans, Lists, Tuples, or nulls.
      Parameters:
      items - the elements from which to create the Tuple
      Returns:
      a new Tuple with the given items as its elements

    • fromList

      public static Tuple fromList(List<?> items)
      Efficiently creates a new Tuple from a list of objects. The elements must follow the type guidelines from add, and so can only be Strings, byte[]s, Numbers, UUIDs, Booleans, Lists, Tuples, or nulls.
      Parameters:
      items - the elements from which to create the Tuple.
      Returns:
      a new Tuple with the given items as its elements

    • fromStream

      public static Tuple fromStream(Stream<?> items)
      Efficiently creates a new Tuple from a Stream of objects. The elements must follow the type guidelines from add, and so can only be Strings, byte[]s, Numbers, UUIDs, Booleans, Lists, Tuples, or nulls. Note that this class will consume all elements from the Stream.
      Parameters:
      items - the Stream of items from which to create the Tuple
      Returns:
      a new Tuple with the given items as its elements

    • from

      public static Tuple from(Object... items)
      Creates a new Tuple from a variable number of elements. The elements must follow the type guidelines from add, and so can only be Strings, byte[]s, Numbers, UUIDs, Booleans, Lists, Tuples, or nulls.
      Parameters:
      items - the elements from which to create the Tuple
      Returns:
      a new Tuple with the given items as its elements