Tuple (FoundationDB Java Client API)

java.lang.Object
- com.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, and null. All Numbers will be converted to a long integral value, so all floating point information will be lost and their range will be constrained to the range [2^63-1, -2^63]. 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[] and Strings can be null, where integral numbers (i.e. longs) cannot. This means that the typed getters (getBytes() and getString()) will return null if the entry at that location was null and the typed adds (add(byte[]) and add(String)) will accept null. The typed get for integers, 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 and Description

Tuple()
Construct a new empty Tuple.

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

Method Summary

Methods
Modifier and Type	Method and Description
`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(long l)` Creates a copy of this `Tuple` with a `long` appended as the last element.
`Tuple`	`add(String s)` Creates a copy of this `Tuple` with a `String` appended as the last element.
`Tuple`	`addAll(List<? extends Object> o)` Create a copy of this `Tuple` with a list of items appended.
`Tuple`	`addAll(Tuple other)` Create a copy of this `Tuple` with all elements from anther `Tuple` 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<? extends Object> items)` Creates a new `Tuple` from a variable number of elements.
`static Tuple`	`fromList(List<? extends Object> items)` Efficiently creates a new `Tuple` from a list of objects.
`Object`	`get(int index)` Gets an indexed item without forcing a type.
`byte[]`	`getBytes(int index)` Gets an indexed item as a `byte[]`.
`List<Object>`	`getItems()` Gets the unserialized contents of this `Tuple`.
`long`	`getLong(int index)` Gets an indexed item as a `long`.
`String`	`getString(int index)` Gets an indexed item as a `String`.
`int`	`hashCode()` Returns a hash code value for this `Tuple`.
`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`.
`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 `Tuple`s strictly starting with this `Tuple`.
`int`	`size()` Gets the number of elements in this `Tuple`.

Methods inherited from class java.lang.Object
getClass, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - Tuple
```
public Tuple()
```
    Construct a new empty Tuple. After creation, items can be added with calls the the variations of add().
    
    See Also:
    from(Object...), fromBytes(byte[]), fromItems(Iterable)
- Method Detail
  - 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, and null are allowed. All Numbers are converted to a 8 byte integral value, so all floating point information is lost.
    
    Parameters:
    o - the object to append. Must be String, byte[], Numbers, 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(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<? extends Object> 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.
    
    Returns:
    a serialized representation of this Tuple.
  - getItems
```
public List<Object> getItems()
```
    Gets the unserialized contents of this Tuple.
    
    Returns:
    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.
    
    Parameters:
    bytes - encoded Tuple source. Must not be null
    
    Returns:
    a newly constructed object.
  - fromBytes
```
public static Tuple fromBytes(byte[] bytes,
              int offset,
              int length)
```
    Construct a new Tuple with elements decoded from a supplied byte array.
    
    Parameters:
    bytes - encoded Tuple source. Must not be null
    
    Returns:
    a newly constructed object.
  - size
```
public int size()
```
    Gets the number of elements in this Tuple.
    
    Returns:
    the count of elements
  - 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
  - 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[]
  - 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
  - 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
  - popBack
```
public Tuple popBack()
```
    Creates a new Tuple with the last item of this Tuple removed.
    
    Returns:
    a newly created Tuple
  - 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", ...)
    Returns:
    the keyspace range containing all Tuples that have this Tuple as a prefix.
  - 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.
    
    Overrides:
    
    hashCode in class Object
    
    Returns:
    a hashcode
  - 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.
  - fromItems
```
public static Tuple fromItems(Iterable<? extends 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, or nulls.
    
    Parameters:
    items - the elements from which to create the Tuple.
    
    Returns:
    a newly created Tuple
  - fromList
```
public static Tuple fromList(List<? extends Object> 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, or nulls.
    
    Parameters:
    items - the elements from which to create the Tuple.
    
    Returns:
    a newly created Tuple
  - 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, or nulls.
    
    Parameters:
    items - the elements from which to create the Tuple.
    
    Returns:
    a newly created Tuple

Class Tuple

Types

`null` values

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Tuple

Method Detail

addObject

add

add

add

add

addAll

addAll

pack

getItems

iterator

fromBytes

fromBytes

size

isEmpty

getLong

getBytes

getString

get

popFront

popBack

range

compareTo

hashCode

equals

fromItems

fromList

from

Class Tuple

Types

null values

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Tuple

Method Detail

addObject

add

add

add

add

addAll

addAll

pack

getItems

iterator

fromBytes

fromBytes

size

isEmpty

getLong

getBytes

getString

get

popFront

popBack

range

compareTo

hashCode

equals

fromItems

fromList

from

`null` values