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

Tuple

public Tuple()

Construct a new empty Tuple. After creation, items can be added with calls to the variations of add().

See Also:

• from(Object...)
• fromBytes(byte[])
• fromItems(Iterable)

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