com.apple.foundationdb.tuple

Class Tuple

java.lang.Object

com.apple.foundationdb.tuple.Tuple

All Implemented Interfaces:

java.lang.Comparable<Tuple>, java.lang.Iterable<java.lang.Object>

public class Tuple
extends java.lang.Object
implements java.lang.Comparable<Tuple>, java.lang.Iterable<java.lang.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 and Description
Tuple() Construct a new empty Tuple.

Method Summary

Modifier and Type	Method and Description
Tuple	add(java.math.BigInteger bi) Creates a copy of this Tuple with a BigInteger appended as the last element.
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(java.util.List<? extends java.lang.Object> l) Creates a copy of this Tuple with an List 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(java.lang.String s) Creates a copy of this Tuple with a String 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(java.util.UUID uuid) Creates a copy of this Tuple with a UUID 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	addAll(java.util.List<? extends java.lang.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(java.lang.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(java.lang.Object o) Tests for equality with another Tuple.
static Tuple	from(java.lang.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(java.lang.Iterable<? extends java.lang.Object> items) Creates a new Tuple from a variable number of elements.
static Tuple	fromList(java.util.List<? extends java.lang.Object> items) Efficiently creates a new Tuple from a list of objects.
static Tuple	fromStream(java.util.stream.Stream<? extends java.lang.Object> items) Efficiently creates a new Tuple from a Stream of objects.
java.lang.Object	get(int index) Gets an indexed item without forcing a type.
java.math.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.
java.util.List<java.lang.Object>	getItems() Gets the unserialized contents of this Tuple.
long	getLong(int index) Gets an indexed item as a long.
java.util.List<java.lang.Object>	getNestedList(int index) Gets an indexed item as a List.
Tuple	getNestedTuple(int index) Gets an indexed item as a Tuple.
java.lang.String	getString(int index) Gets an indexed item as a String.
java.util.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.
java.util.Iterator<java.lang.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.
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.
int	size() Gets the number of elements in this Tuple.
java.util.stream.Stream<java.lang.Object>	stream() Gets a Stream of the unserialized contents of this Tuple.
java.lang.String	toString() Returns a string representing this Tuple.

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.lang.Iterable

forEach, spliterator

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(java.lang.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(java.lang.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(java.util.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(java.math.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(java.util.List<? extends java.lang.Object> l)

Creates a copy of this Tuple with an 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(java.util.List<? extends java.lang.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.

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.

Parameters:

prefix - additional byte-array prefix to prepend to serialized bytes.

Returns:

a serialized representation of this Tuple prepended by the prefix.

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 serialized representation of this Tuple for use with versionstamp ops.

Throws:

java.lang.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 serialized 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.

Parameters:

prefix - additional byte-array prefix to prepend to serialized bytes.

Returns:

a serialized representation of this Tuple for use with versionstamp ops.

Throws:

java.lang.IllegalArgumentException - if there is not exactly one incomplete Versionstamp included in this Tuple

getItems

public java.util.List<java.lang.Object> getItems()

Gets the unserialized contents of this Tuple.

Returns:

the elements that make up this Tuple.

stream

public java.util.stream.Stream<java.lang.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 java.util.Iterator<java.lang.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 java.lang.Iterable<java.lang.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.

Parameters:

bytes - encoded Tuple source

Returns:

a new Tuple constructed by deserializing the provided byte array

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.

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

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:

java.lang.ClassCastException - if the element at index is not a Number

java.lang.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:

java.lang.ClassCastException - if the element at index is not a Number

getString

public java.lang.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:

java.lang.ClassCastException - if the element at index is not a String

getBigInteger

public java.math.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:

java.lang.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:

java.lang.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:

java.lang.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:

java.lang.ClassCastException - if the element at index is not a Boolean

java.lang.NullPointerException - if the element at index is null

getUUID

public java.util.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:

java.lang.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:

java.lang.ClassCastException - if the element at index is not a Versionstamp

getNestedList

public java.util.List<java.lang.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:

java.lang.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:

java.lang.ClassCastException - if the element at index is not a Tuple or a List

get

public java.lang.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:

java.lang.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:

java.lang.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", ...)

Returns:

the range of keys containing all Tuples that have this Tuple as a 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

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 java.lang.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 java.lang.Object

Returns:

a hash code for this Tuple that can be used by hash tables

equals

public boolean equals(java.lang.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 java.lang.Object

Returns:

true if obj is a Tuple and their binary representation is identical

toString

public java.lang.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 java.lang.Object

Returns:

a human-readable String representation of this Tuple

fromItems

public static Tuple fromItems(java.lang.Iterable<? extends java.lang.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

fromList

public static Tuple fromList(java.util.List<? extends java.lang.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, 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(java.util.stream.Stream<? extends java.lang.Object> 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(java.lang.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