org.apache.pig.data
Interface Tuple

All Superinterfaces:
Comparable, Serializable, org.apache.hadoop.io.Writable, org.apache.hadoop.io.WritableComparable
All Known Implementing Classes:
AmendableTuple, BinSedesTuple, DefaultAbstractBag.BagDelimiterTuple, DefaultAbstractBag.EndBag, DefaultAbstractBag.StartBag, DefaultTuple, ExampleTuple, TargetedTuple, TimestampedTuple, ZebraTuple

@InterfaceAudience.Public
@InterfaceStability.Stable
public interface Tuple
extends org.apache.hadoop.io.WritableComparable, Serializable

An ordered list of Data. A tuple has fields, numbered 0 through (number of fields - 1). The entry in the field can be any datatype, or it can be null.

Tuples are constructed only by a TupleFactory. A DefaultTupleFactory is provided by the system. If users wish to use their own type of Tuple, they should also provide an implementation of TupleFactory to construct their types of Tuples.


Field Summary
static byte NOTNULL
          Marker for indicating whether the value this object holds is not a null
static byte NULL
          Marker for indicating whether the value this object holds is a null
 
Method Summary
 void append(Object val)
          Append a field to a tuple.
 Object get(int fieldNum)
          Get the value in a given field.
 List<Object> getAll()
          Get all of the fields in the tuple as a list.
 long getMemorySize()
          Determine the size of tuple in memory.
 byte getType(int fieldNum)
          Find the type of a given field.
 boolean isNull()
          Determine if this entire tuple (not any particular field) is null.
 boolean isNull(int fieldNum)
          Find out if a given field is null.
 void reference(Tuple t)
          Make this tuple reference the contents of another.
 void set(int fieldNum, Object val)
          Set the value in a given field.
 void setNull(boolean isNull)
          Mark this entire tuple as null or not null.
 int size()
          Find the size of the tuple.
 String toDelimitedString(String delim)
          Write a tuple of atomic values into a string.
 
Methods inherited from interface org.apache.hadoop.io.Writable
readFields, write
 
Methods inherited from interface java.lang.Comparable
compareTo
 

Field Detail

NULL

static final byte NULL
Marker for indicating whether the value this object holds is a null

See Also:
Constant Field Values

NOTNULL

static final byte NOTNULL
Marker for indicating whether the value this object holds is not a null

See Also:
Constant Field Values
Method Detail

reference

void reference(Tuple t)
Make this tuple reference the contents of another. This method does not copy the underlying data. It maintains references to the data from the original tuple (and possibly even to the data structure holding the data).

Parameters:
t - Tuple to reference.

size

int size()
Find the size of the tuple. Used to be called arity().

Returns:
number of fields in the tuple.

isNull

boolean isNull(int fieldNum)
               throws ExecException
Find out if a given field is null.

Parameters:
fieldNum - Number of field to check for null.
Returns:
true if the field is null, false otherwise.
Throws:
ExecException - if the field number given is greater than or equal to the number of fields in the tuple.

getType

byte getType(int fieldNum)
             throws ExecException
Find the type of a given field.

Parameters:
fieldNum - Number of field to get the type for.
Returns:
type, encoded as a byte value. The values are defined in DataType. If the field is null, then DataType.UNKNOWN will be returned.
Throws:
ExecException - if the field number is greater than or equal to the number of fields in the tuple.

get

Object get(int fieldNum)
           throws ExecException
Get the value in a given field.

Parameters:
fieldNum - Number of the field to get the value for.
Returns:
value, as an Object.
Throws:
ExecException - if the field number is greater than or equal to the number of fields in the tuple.

getAll

List<Object> getAll()
Get all of the fields in the tuple as a list.

Returns:
a list of objects containing the fields of the tuple in order.

set

void set(int fieldNum,
         Object val)
         throws ExecException
Set the value in a given field. This should not be called unless the tuple was constructed by TupleFactory.newTuple(int) with an argument greater than the fieldNum being passed here. This call will not automatically expand the tuple size. That is if you called TupleFactory.newTuple(int) with a 2, it is okay to call this function with a 1, but not with a 2 or greater.

Parameters:
fieldNum - Number of the field to set the value for.
val - Object to put in the indicated field.
Throws:
ExecException - if the field number is greater than or equal to the number of fields in the tuple.

append

void append(Object val)
Append a field to a tuple. This method is not efficient as it may force copying of existing data in order to grow the data structure. Whenever possible you should construct your Tuple with TupleFactory.newTuple(int) and then fill in the values with set(int, Object), rather than construct it with TupleFactory.newTuple() and append values.

Parameters:
val - Object to append to the tuple.

getMemorySize

long getMemorySize()
Determine the size of tuple in memory. This is used by data bags to determine their memory size. This need not be exact, but it should be a decent estimation.

Returns:
estimated memory size, in bytes.

toDelimitedString

String toDelimitedString(String delim)
                         throws ExecException
Write a tuple of atomic values into a string. All values in the tuple must be atomic (no bags, tuples, or maps).

Parameters:
delim - Delimiter to use in the string.
Returns:
A string containing the tuple.
Throws:
ExecException - if a non-atomic value is found.

isNull

boolean isNull()
Determine if this entire tuple (not any particular field) is null.

Returns:
true if this Tuple is null

setNull

void setNull(boolean isNull)
Mark this entire tuple as null or not null.

Parameters:
isNull - boolean indicating whether this tuple is null


Copyright © ${year} The Apache Software Foundation