cascading.tuple
Class Tuple

java.lang.Object
  extended by cascading.tuple.Tuple
All Implemented Interfaces:
Serializable, Comparable<Object>, Iterable<Object>
Direct Known Subclasses:
IndexTuple, TuplePair

public class Tuple
extends Object
implements Comparable<Object>, Iterable<Object>, Serializable

A Tuple represents a set of values. Consider a Tuple the same as a database record where every value is a column in that table.

A "tuple stream" is a set of Tuple instances passed consecutively through a Pipe assembly.

Tuples work in tandem with Fields and the TupleEntry classes. A TupleEntry holds an instance of Fields and a Tuple. It allows a tuple to be accessed by its field names, and will help maintain consistent types if any are given on the Fields instance. That is, if a field is specified at an Integer, calling set(int, Object) with a String will force the String to be coerced into a Integer instance.

For managing custom types, see the CoercibleType interface which extends Type.

Tuple instances created by user code, by default, are mutable (or modifiable). Tuple instances created by the system are immutable (or unmodifiable, tested by calling isUnmodifiable()).

For example tuples returned by FunctionCall.getArguments(), will always be unmodifiable. Thus they must be copied if they will be changed by user code or cached in the local context. See the Tuple copy constructor, or *Copy() methods on TupleEntry.

Because a Tuple can hold any Object type, it is suitable for storing custom types. But all custom types must have a serialization support per the underlying framework.

For Hadoop, a Serialization implementation must be registered with Hadoop. For further performance improvements, see the SerializationToken Java annotation.

See Also:
Serialization, SerializationToken, Serialized Form

Field Summary
protected  List<Object> elements
          Field elements
protected  boolean isUnmodifiable
          Field isUnmodifiable
static Tuple NULL
          A constant empty Tuple instance.
 
Constructor Summary
  Tuple()
          Constructor Tuple creates a new Tuple instance.
protected Tuple(List<Object> elements)
           
  Tuple(Object... values)
          Constructor Tuple creates a new Tuple instance with all the given values.
  Tuple(Tuple tuple)
          Copy constructor.
 
Method Summary
 void add(Comparable value)
          Method add adds a new element value to this instance.
 void add(Object value)
          Method add adds a new element value to this instance.
 void addAll(Object... values)
          Method addAll adds all given values to this instance.
 void addAll(Tuple tuple)
          Method addAll adds all the element values of the given Tuple instance to this instance.
 void addBoolean(boolean value)
          Method addBoolean adds a new element value to this instance.
 void addDouble(double value)
          Method addDouble adds a new element value to this instance.
 void addFloat(float value)
          Method addFloat adds a new element value to this instance.
 void addInteger(int value)
          Method addInteger adds a new element value to this instance.
 void addLong(long value)
          Method addLong adds a new element value to this instance.
 void addShort(short value)
          Method addShort adds a new element value to this instance.
 void addString(String value)
          Method addString adds a new element value to this instance.
 Tuple append(Tuple... tuples)
          Method append appends all the values of the given Tuple instances to a copy of this instance.
 void clear()
          Method clear empties this Tuple instance.
 int compareTo(Comparator[] comparators, Tuple other)
           
 int compareTo(Object other)
          Method compareTo implements the Comparable.compareTo(Object) method.
 int compareTo(Tuple other)
          Method compareTo compares this Tuple to the given Tuple instance.
static List<Object> elements(Tuple tuple)
          Returns a reference to the private elements of the given Tuple.
 boolean equals(Object object)
           
 String format(String format)
          Method format uses the Formatter class for formatting this tuples values into a new string.
 Tuple get(Fields declarator, Fields selector)
          Method get returns a new Tuple populated with only those values whose field names are specified in the given selector.
 Comparable get(int pos)
          Deprecated. 
 Tuple get(int[] pos)
          Method get will return a new Tuple instance populated with element values from the given array of positions.
 boolean getBoolean(int pos)
          Method getBoolean returns the element at the given position as a boolean.
 char getChar(int pos)
          Method getChar returns the element at the given position as a char.
 double getDouble(int pos)
          Method getDouble returns the element at the given position as a double.
 float getFloat(int pos)
          Method getFloat returns the element at the given position as a float.
 int getInteger(int pos)
          Method getInteger returns the element at the given position as an int.
 long getLong(int pos)
          Method getLong returns the element at the given position as an long.
 Object getObject(int pos)
          Method get returns the element at the given position.
 int[] getPos(Fields declarator, Fields selector)
           
 short getShort(int pos)
          Method getShort returns the element at the given position as an short.
 String getString(int pos)
          Method getString returns the element at the given position as a String.
 Class[] getTypes()
          Method getTypes returns an array of the element classes.
 int hashCode()
           
protected  void internalSet(int index, Object value)
           
 boolean isEmpty()
          Method isEmpty returns true if this Tuple instance has no values.
 boolean isUnmodifiable()
          Method isUnmodifiable returns true if this Tuple instance is unmodifiable.
 Iterator<Object> iterator()
          Method iterator returns an Iterator over this Tuple instances values.
 Tuple leave(int[] pos)
          Method is the inverse of remove(int[]).
static Tuple parse(String string)
          Deprecated.  
 String print()
          Method print returns a parsable String representation of this Tuple instance.
 StringBuffer printTo(StringBuffer buffer)
           
 void put(Fields declarator, Fields fields, Tuple tuple)
          Method put places the values of the given tuple into the positions specified by the fields argument.
 Tuple remove(Fields declarator, Fields selector)
          Method remove removes the values specified by the given selector.
 Tuple remove(int[] pos)
          Method remove removes the values specified by the given pos array and returns a new Tuple containing the removed values.
 void set(Fields declarator, Fields selector, Tuple tuple)
          Method set sets the values in the given selector positions to the values from the given Tuple.
protected  void set(Fields declarator, Fields selector, Tuple tuple, CoercibleType[] coercions)
           
 void set(int index, Object value)
          Method set sets the given value to the given index position in this instance.
 void setAll(Tuple... tuples)
          Method setAll sets each element value of the given Tuple instances into the corresponding position of this instance.
 void setAll(Tuple tuple)
          Method setAll sets each element value of the given Tuple instance into the corresponding position of this instance.
 void setBoolean(int index, boolean value)
          Method setBoolean sets the given value to the given index position in this instance.
 void setDouble(int index, double value)
          Method setDouble sets the given value to the given index position in this instance.
 void setFloat(int index, float value)
          Method setFloat sets the given value to the given index position in this instance.
 void setInteger(int index, int value)
          Method setInteger sets the given value to the given index position in this instance.
 void setLong(int index, long value)
          Method setLong sets the given value to the given index position in this instance.
 void setShort(int index, short value)
          Method setShort sets the given value to the given index position in this instance.
 void setString(int index, String value)
          Method setString sets the given value to the given index position in this instance.
 int size()
          Method size returns the number of values in this Tuple instance.
static Tuple size(int size)
          Method size returns a new Tuple instance of the given size with nulls as its element values.
static Tuple size(int size, Comparable value)
          Method size returns a new Tuple instance of the given size with the given Comparable as its element values.
 String toString()
           
 String toString(String delim)
          Method toString writes this Tuple instance values out to a String delimited by the given String value.
 String toString(String delim, boolean printNull)
          Method toString writes this Tuple instance values out to a String delimited by the given String value.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

NULL

public static final Tuple NULL
A constant empty Tuple instance. This instance is immutable.


isUnmodifiable

protected boolean isUnmodifiable
Field isUnmodifiable


elements

protected List<Object> elements
Field elements

Constructor Detail

Tuple

protected Tuple(List<Object> elements)

Tuple

public Tuple()
Constructor Tuple creates a new Tuple instance.


Tuple

@ConstructorProperties(value="tuple")
public Tuple(Tuple tuple)
Copy constructor. Does not nest the given Tuple instance within this new instance. Use add(Object).

Parameters:
tuple - of type Tuple

Tuple

@ConstructorProperties(value="values")
public Tuple(Object... values)
Constructor Tuple creates a new Tuple instance with all the given values.

Parameters:
values - of type Object...
Method Detail

size

public static Tuple size(int size)
Method size returns a new Tuple instance of the given size with nulls as its element values.

Parameters:
size - of type int
Returns:
Tuple

size

public static Tuple size(int size,
                         Comparable value)
Method size returns a new Tuple instance of the given size with the given Comparable as its element values.

Parameters:
size - of type int
value - of type Comparable
Returns:
Tuple

parse

@Deprecated
public static Tuple parse(String string)
Deprecated. 

Method parse will parse the print() String representation of a Tuple instance and return a new Tuple instance.

This method has been deprecated as it doesn't properly handle nulls, and any types other than primitive types.

Parameters:
string - of type String
Returns:
Tuple

elements

public static List<Object> elements(Tuple tuple)
Returns a reference to the private elements of the given Tuple.

This method is for internal use and is subject to change scope in a future release.

Parameters:
tuple - of type Tuple
Returns:
List

isUnmodifiable

public boolean isUnmodifiable()
Method isUnmodifiable returns true if this Tuple instance is unmodifiable.

"Unmodifiable" tuples are generally owned by the system and cannot be changed, nor should they be cached as the internal values may change.

Returns:
boolean

get

@Deprecated
public Comparable get(int pos)
Deprecated. 

Method get returns the element at the given position i.

This method assumes the element implements Comparable in order to maintain backwards compatibility. See getObject(int) for an alternative.

This method is deprecated, use getObject(int) instead.

Parameters:
pos - of type int
Returns:
Comparable

getObject

public Object getObject(int pos)
Method get returns the element at the given position.

This method will perform no coercion on the element.

Parameters:
pos - of type int
Returns:
Object

getChar

public char getChar(int pos)
Method getChar returns the element at the given position as a char.

Parameters:
pos - of type int
Returns:
String

getString

public String getString(int pos)
Method getString returns the element at the given position as a String.

Parameters:
pos - of type int
Returns:
String

getFloat

public float getFloat(int pos)
Method getFloat returns the element at the given position as a float. Zero if null.

Parameters:
pos - of type int
Returns:
float

getDouble

public double getDouble(int pos)
Method getDouble returns the element at the given position as a double. Zero if null.

Parameters:
pos - of type int
Returns:
double

getInteger

public int getInteger(int pos)
Method getInteger returns the element at the given position as an int. Zero if null.

Parameters:
pos - of type int
Returns:
int

getLong

public long getLong(int pos)
Method getLong returns the element at the given position as an long. Zero if null.

Parameters:
pos - of type int
Returns:
long

getShort

public short getShort(int pos)
Method getShort returns the element at the given position as an short. Zero if null.

Parameters:
pos - of type int
Returns:
long

getBoolean

public boolean getBoolean(int pos)
Method getBoolean returns the element at the given position as a boolean. If the value is (case ignored) the string 'true', a true value will be returned. false if null.

Parameters:
pos - of type int
Returns:
boolean

get

public Tuple get(int[] pos)
Method get will return a new Tuple instance populated with element values from the given array of positions.

Parameters:
pos - of type int[]
Returns:
Tuple

get

public Tuple get(Fields declarator,
                 Fields selector)
Method get returns a new Tuple populated with only those values whose field names are specified in the given selector. The declarator Fields instance declares the fields and positions in the current Tuple instance.

Parameters:
declarator - of type Fields
selector - of type Fields
Returns:
Tuple

getPos

public int[] getPos(Fields declarator,
                    Fields selector)

leave

public Tuple leave(int[] pos)
Method is the inverse of remove(int[]).

Parameters:
pos - of type int[]
Returns:
Tuple

clear

public void clear()
Method clear empties this Tuple instance. A subsequent call to size() will return zero (0).


add

public void add(Comparable value)
Method add adds a new element value to this instance.

Parameters:
value - of type Comparable

add

public void add(Object value)
Method add adds a new element value to this instance.

Parameters:
value - of type Object

addBoolean

public void addBoolean(boolean value)
Method addBoolean adds a new element value to this instance.

Parameters:
value - of type boolean

addShort

public void addShort(short value)
Method addShort adds a new element value to this instance.

Parameters:
value - of type short

addInteger

public void addInteger(int value)
Method addInteger adds a new element value to this instance.

Parameters:
value - of type int

addLong

public void addLong(long value)
Method addLong adds a new element value to this instance.

Parameters:
value - of type long

addFloat

public void addFloat(float value)
Method addFloat adds a new element value to this instance.

Parameters:
value - of type float

addDouble

public void addDouble(double value)
Method addDouble adds a new element value to this instance.

Parameters:
value - of type double

addString

public void addString(String value)
Method addString adds a new element value to this instance.

Parameters:
value - of type String

addAll

public void addAll(Object... values)
Method addAll adds all given values to this instance.

Parameters:
values - of type Object...

addAll

public void addAll(Tuple tuple)
Method addAll adds all the element values of the given Tuple instance to this instance.

Parameters:
tuple - of type Tuple

setAll

public void setAll(Tuple tuple)
Method setAll sets each element value of the given Tuple instance into the corresponding position of this instance.

Parameters:
tuple - of type Tuple

setAll

public void setAll(Tuple... tuples)
Method setAll sets each element value of the given Tuple instances into the corresponding position of this instance.

All given tuple instances after the first will be offset by the length of the prior tuple instances.

Parameters:
tuples - of type Tuple[]

set

public void set(int index,
                Object value)
Method set sets the given value to the given index position in this instance.

Parameters:
index - of type int
value - of type Object

setBoolean

public void setBoolean(int index,
                       boolean value)
Method setBoolean sets the given value to the given index position in this instance.

Parameters:
index - of type int
value - of type boolean

setShort

public void setShort(int index,
                     short value)
Method setShort sets the given value to the given index position in this instance.

Parameters:
index - of type int
value - of type short

setInteger

public void setInteger(int index,
                       int value)
Method setInteger sets the given value to the given index position in this instance.

Parameters:
index - of type int
value - of type int

setLong

public void setLong(int index,
                    long value)
Method setLong sets the given value to the given index position in this instance.

Parameters:
index - of type int
value - of type long

setFloat

public void setFloat(int index,
                     float value)
Method setFloat sets the given value to the given index position in this instance.

Parameters:
index - of type int
value - of type float

setDouble

public void setDouble(int index,
                      double value)
Method setDouble sets the given value to the given index position in this instance.

Parameters:
index - of type int
value - of type double

setString

public void setString(int index,
                      String value)
Method setString sets the given value to the given index position in this instance.

Parameters:
index - of type int
value - of type String

internalSet

protected final void internalSet(int index,
                                 Object value)

put

public void put(Fields declarator,
                Fields fields,
                Tuple tuple)
Method put places the values of the given tuple into the positions specified by the fields argument. The declarator Fields value declares the fields in this Tuple instance.

Parameters:
declarator - of type Fields
fields - of type Fields
tuple - of type Tuple

remove

public Tuple remove(int[] pos)
Method remove removes the values specified by the given pos array and returns a new Tuple containing the removed values.

Parameters:
pos - of type int[]
Returns:
Tuple

remove

public Tuple remove(Fields declarator,
                    Fields selector)
Method remove removes the values specified by the given selector. The declarator declares the fields in this instance.

Parameters:
declarator - of type Fields
selector - of type Fields
Returns:
Tuple

set

public void set(Fields declarator,
                Fields selector,
                Tuple tuple)
Method set sets the values in the given selector positions to the values from the given Tuple.

Parameters:
declarator - of type Fields
selector - of type Fields
tuple - of type Tuple

set

protected void set(Fields declarator,
                   Fields selector,
                   Tuple tuple,
                   CoercibleType[] coercions)

iterator

public Iterator<Object> iterator()
Method iterator returns an Iterator over this Tuple instances values.

Specified by:
iterator in interface Iterable<Object>
Returns:
Iterator

isEmpty

public boolean isEmpty()
Method isEmpty returns true if this Tuple instance has no values.

Returns:
the empty (type boolean) of this Tuple object.

size

public int size()
Method size returns the number of values in this Tuple instance.

Returns:
int

getTypes

public Class[] getTypes()
Method getTypes returns an array of the element classes. Null if the element is null.

Returns:
the types (type Class[]) of this Tuple object.

append

public Tuple append(Tuple... tuples)
Method append appends all the values of the given Tuple instances to a copy of this instance.

Parameters:
tuples - of type Tuple
Returns:
Tuple

compareTo

public int compareTo(Tuple other)
Method compareTo compares this Tuple to the given Tuple instance.

Parameters:
other - of type Tuple
Returns:
int

compareTo

public int compareTo(Comparator[] comparators,
                     Tuple other)

compareTo

public int compareTo(Object other)
Method compareTo implements the Comparable.compareTo(Object) method.

Specified by:
compareTo in interface Comparable<Object>
Parameters:
other - of type Object
Returns:
int

equals

public boolean equals(Object object)
Overrides:
equals in class Object

hashCode

public int hashCode()
Overrides:
hashCode in class Object

toString

public String toString()
Overrides:
toString in class Object

toString

public String toString(String delim)
Method toString writes this Tuple instance values out to a String delimited by the given String value.

Parameters:
delim - of type String
Returns:
String

toString

public String toString(String delim,
                       boolean printNull)
Method toString writes this Tuple instance values out to a String delimited by the given String value.

Parameters:
delim - of type String
printNull - of type boolean
Returns:
String

format

public String format(String format)
Method format uses the Formatter class for formatting this tuples values into a new string.

Parameters:
format - of type String
Returns:
String

print

public String print()
Method print returns a parsable String representation of this Tuple instance.

Returns:
String

printTo

public StringBuffer printTo(StringBuffer buffer)


Copyright © 2007-2013 Concurrent, Inc. All Rights Reserved.