cascading.tuple

## Class Tuple

- java.lang.Object
- - cascading.tuple.Tuple

- All Implemented Interfaces:
    Serializable, Comparable<Object>, Iterable<Object>
  Direct Known Subclasses:
    GroupingSpliceGate.DelegatedTuple, IndexTuple, KeyTuple, TuplePair, ValueTuple

      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

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected List<Object>` | `elements` Field elements
    `protected boolean` | `isUnmodifiable` Field isUnmodifiable
    `static Tuple` | `NULL` A constant empty Tuple instance.

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `` | `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

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `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.
    `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[])`.
    `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 transient 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

    - #### 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

    - #### 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.

      If type information is given, each incoming value from tuple will be coerced from its canonical type to the current type as declared in the declarator.
      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-2015 Concurrent, Inc. All Rights Reserved.