cascading.tuple

## Class TupleEntry

- java.lang.Object
- - cascading.tuple.TupleEntry

-     public class TupleEntry
      extends Object

  Class TupleEntry allows a `Tuple` instance and its declaring `Fields` instance to be used as a single object.

  Once a TupleEntry is created, its Fields cannot be changed, but the Tuple instance it holds can be replaced or modified. The managed Tuple should not have elements added or removed, as this will break the relationship with the associated Fields instance.

  If type information is provided on the Fields instance, all setters on this class will use that information to coerce the given object to the expected type.

  For example, if position is is of type `long`, then `entry.setString(0, "9" )` will coerce the "9" to a long `9`. Thus, `entry.getObject(0) == 9l`.

  No coercion is performed with the `getObject(Comparable)` and `getObject(int)` methods.

  To set a value without coercion, see the `setRaw(Comparable, Object)` and `setRaw(int, Object)` methods.
  See Also:
    `Fields`, `Tuple`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static TupleEntry` | `NULL` An EMPTY TupleEntry instance for use as a stand in instead of a `null`.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `TupleEntry()` Constructor TupleEntry creates a new TupleEntry instance.
    `TupleEntry(boolean isUnmodifiable)` Constructor TupleEntry creates a new TupleEntry instance.
    `TupleEntry(Fields fields)` Constructor TupleEntry creates a new TupleEntry instance.
    `TupleEntry(Fields fields, boolean isUnmodifiable)` Constructor TupleEntry creates a new TupleEntry instance.
    `TupleEntry(Fields fields, Tuple tuple)` Constructor TupleEntry creates a new TupleEntry instance.
    `TupleEntry(Fields fields, Tuple tuple, boolean isUnmodifiable)` Constructor TupleEntry creates a new TupleEntry instance.
    `TupleEntry(Tuple tuple)` Constructor TupleEntry creates a new TupleEntry instance.
    `TupleEntry(TupleEntry tupleEntry)` Constructor TupleEntry creates a new TupleEntry instance that is a safe copy of the given tupleEntry.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `TupleEntry` | `appendNew(TupleEntry entry)` Method appendNew appends the given TupleEntry instance to this instance.
    `<T> Iterable<T>` | `asIterableOf(Class<T> type)` Method asIterableOf returns an `Iterable` instance that will coerce all Tuple elements into the given `type` parameter.
    `boolean` | `equals(Object object)`
    `boolean` | `getBoolean(Comparable fieldName)` Method getBoolean returns the element for the given field name or position as a boolean.
    `Tuple` | `getCoercedTuple(Type[] types)` Method getCoercedTuple is a helper method for copying the current tuple elements into a new Tuple, of the same size, as the requested coerced types.
    `Tuple` | `getCoercedTuple(Type[] types, Tuple into)` Method getCoercedTuple is a helper method for copying the current tuple elements into the new Tuple, of the same size, as the requested coerced types.
    `double` | `getDouble(Comparable fieldName)` Method getDouble returns the element for the given field name or position as a double.
    `Fields` | `getFields()` Method getFields returns the fields of this TupleEntry object.
    `float` | `getFloat(Comparable fieldName)` Method getFloat returns the element for the given field name or position as a float.
    `int` | `getInteger(Comparable fieldName)` Method getInteger returns the element for the given field name or position as an int.
    `long` | `getLong(Comparable fieldName)` Method getLong returns the element for the given field name or position as a long.
    `Object` | `getObject(Comparable fieldName)` Method getObject returns the value in the given field or position.
    `Object` | `getObject(Comparable fieldName, Type type)` Method getObject returns the value in the given field or position as the requested type.
    `Object` | `getObject(int pos)` Method getObject returns the value in the given position pos.
    `Object` | `getObject(int pos, Type type)` Method getObject returns the value in the given field or position as the requested type.
    `short` | `getShort(Comparable fieldName)` Method getShort returns the element for the given field name or position as a short.
    `String` | `getString(Comparable fieldName)` Method getString returns the element for the given field name or position as a String.
    `Tuple` | `getTuple()` Method getTuple returns the tuple of this TupleEntry object.
    `Tuple` | `getTupleCopy()` Method getTupleCopy returns a copy of the tuple of this TupleEntry object.
    `int` | `hashCode()`
    `boolean` | `hasTypes()` Returns true if there are types associated with this instance.
    `boolean` | `isUnmodifiable()` Method isUnmodifiable returns true if this TupleEntry is unmodifiable.
    `static Tuple` | `select(Fields selector, TupleEntry... entries)` Method select will select a new Tuple instance from the given set of entries.
    `TupleEntry` | `selectEntry(Fields selector)` Method selectEntry selects the fields specified in the selector from this instance.
    `TupleEntry` | `selectEntryCopy(Fields selector)` Method selectEntry selects the fields specified in selector from this instance.
    `Tuple` | `selectInto(Fields selector, Tuple tuple)` Method selectInto selects the fields specified in the selector from this instance and copies them into the given tuple argument.
    `Tuple` | `selectTuple(Fields selector)` Method selectTuple selects the fields specified in the selector from this instance.
    `Tuple` | `selectTupleCopy(Fields selector)` Method selectTupleCopy selects the fields specified in selector from this instance.
    `void` | `set(TupleEntry tupleEntry)` Method set sets the values from the given tupleEntry into this TupleEntry instance based on the given tupleEntry field names.
    `void` | `setBoolean(Comparable fieldName, boolean value)` Method setBoolean sets the value in the given field or position.
    `void` | `setCanonicalTuple(Tuple tuple)` Method setCanonicalTuple replaces each value of the current tuple with the given tuple elements after they are coerced.
    `void` | `setCanonicalValues(Object[] values)` Method setCanonicalValues replaces each value of the current tuple with th give Object[] after they are coerced.
    `void` | `setDouble(Comparable fieldName, double value)` Method setDouble sets the value in the given field or position.
    `void` | `setFloat(Comparable fieldName, float value)` Method setFloat sets the value in the given field or position.
    `void` | `setInteger(Comparable fieldName, int value)` Method setInteger sets the value in the given field or position.
    `void` | `setLong(Comparable fieldName, long value)` Method setLong sets the value in the given field or position.
    `void` | `setObject(Comparable fieldName, Object value)` Method set sets the value in the given field or position.
    `void` | `setRaw(Comparable fieldName, Object value)` Method set sets the value in the given field or position.
    `void` | `setRaw(int pos, Object value)` Method set sets the value in the given position.
    `void` | `setShort(Comparable fieldName, short value)` Method setShort sets the value in the given field or position.
    `void` | `setString(Comparable fieldName, String value)` Method setString sets the value in the given field or position.
    `void` | `setTuple(Fields selector, Tuple tuple)` Method setTuple sets the values specified by the selector to the values given by the given tuple, the given values will always be copied into this TupleEntry.
    `void` | `setTuple(Tuple tuple)` Method setTuple sets the tuple of this TupleEntry object, no copy will be performed.
    `int` | `size()` Method size returns the number of values in this instance.
    `String` | `toString()`

    - ### Methods inherited from class java.lang.Object

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### NULL

          public static final TupleEntry NULL

      An EMPTY TupleEntry instance for use as a stand in instead of a `null`.

  - ### Constructor Detail

    - #### TupleEntry

          public TupleEntry()

      Constructor TupleEntry creates a new TupleEntry instance.

    - #### TupleEntry

          @ConstructorProperties(value="isUnmodifiable")
          public TupleEntry(boolean isUnmodifiable)

      Constructor TupleEntry creates a new TupleEntry instance.
      Parameters:
        `isUnmodifiable` - of type boolean

    - #### TupleEntry

          @ConstructorProperties(value="fields")
          public TupleEntry(Fields fields)

      Constructor TupleEntry creates a new TupleEntry instance.
      Parameters:
        `fields` - of type Fields

    - #### TupleEntry

          @ConstructorProperties(value={"fields","isUnmodifiable"})
          public TupleEntry(Fields fields,
                                               boolean isUnmodifiable)

      Constructor TupleEntry creates a new TupleEntry instance.
      Parameters:
        `fields` - of type Fields
        `isUnmodifiable` - of type boolean

    - #### TupleEntry

          @ConstructorProperties(value={"fields","tuple","isUnmodifiable"})
          public TupleEntry(Fields fields,
                                               Tuple tuple,
                                               boolean isUnmodifiable)

      Constructor TupleEntry creates a new TupleEntry instance.
      Parameters:
        `fields` - of type Fields
        `tuple` - of type Tuple
        `isUnmodifiable` - of type boolean

    - #### TupleEntry

          @ConstructorProperties(value={"fields","tuple"})
          public TupleEntry(Fields fields,
                                               Tuple tuple)

      Constructor TupleEntry creates a new TupleEntry instance.
      Parameters:
        `fields` - of type Fields
        `tuple` - of type Tuple

    - #### TupleEntry

          @ConstructorProperties(value="tupleEntry")
          public TupleEntry(TupleEntry tupleEntry)

      Constructor TupleEntry creates a new TupleEntry instance that is a safe copy of the given tupleEntry.

      The new instance is safe to cache and will be modifiable regardless of the given tupleEntry state.
      Parameters:
        `tupleEntry` - of type TupleEntry

    - #### TupleEntry

          @ConstructorProperties(value="tuple")
          public TupleEntry(Tuple tuple)

      Constructor TupleEntry creates a new TupleEntry instance.
      Parameters:
        `tuple` - of type Tuple

  - ### Method Detail

    - #### select

          public static Tuple select(Fields selector,
                     TupleEntry... entries)

      Method select will select a new Tuple instance from the given set of entries. Entries order is significant to the selector.
      Parameters:
        `selector` - of type Fields
        `entries` - of type TupleEntry
      Returns:
        Tuple

    - #### isUnmodifiable

          public boolean isUnmodifiable()

      Method isUnmodifiable returns true if this TupleEntry is unmodifiable.
      Returns:
        boolean

    - #### getFields

          public Fields getFields()

      Method getFields returns the fields of this TupleEntry object.
      Returns:
        the fields (type Fields) of this TupleEntry object.

    - #### hasTypes

          public boolean hasTypes()

      Returns true if there are types associated with this instance.
      Returns:
        boolean

    - #### getTuple

          public Tuple getTuple()

      Method getTuple returns the tuple of this TupleEntry object.
      Returns:
        the tuple (type Tuple) of this TupleEntry object.

    - #### getTupleCopy

          public Tuple getTupleCopy()

      Method getTupleCopy returns a copy of the tuple of this TupleEntry object.
      Returns:
        a copy of the tuple (type Tuple) of this TupleEntry object.

    - #### getCoercedTuple

          public Tuple getCoercedTuple(Type[] types)

      Method getCoercedTuple is a helper method for copying the current tuple elements into a new Tuple, of the same size, as the requested coerced types.
      Parameters:
        `types` - of type Type[]
      Returns:
        returns the a new Tuple instance with coerced values

    - #### getCoercedTuple

          public Tuple getCoercedTuple(Type[] types,
                              Tuple into)

      Method getCoercedTuple is a helper method for copying the current tuple elements into the new Tuple, of the same size, as the requested coerced types.
      Parameters:
        `types` - of type Type[]
        `into` - of type Tuple
      Returns:
        returns the given into Tuple instance with coerced values

    - #### setTuple

          public void setTuple(Tuple tuple)

      Method setTuple sets the tuple of this TupleEntry object, no copy will be performed.

      If the given tuple is "unmodifiable" (`Tuple.isUnmodifiable() == true`) and this TupleEntry is not "unmodifiable", an exception will be thrown.

      Unmodifiable tuples are generally owned by the system and cannot be be changed and must not be cached.
      Parameters:
        `tuple` - the tuple of this TupleEntry object.

    - #### setCanonicalTuple

          public void setCanonicalTuple(Tuple tuple)

      Method setCanonicalTuple replaces each value of the current tuple with the given tuple elements after they are coerced.

      This method will modify the existing Tuple wrapped by this TupleEntry instance even if it is marked as unmodifiable.

      If tuple argument is `null`, the current tuple will be set to `null`.
      Parameters:
        `tuple` - to replace the current wrapped Tuple instance

    - #### setCanonicalValues

          public void setCanonicalValues(Object[] values)

      Method setCanonicalValues replaces each value of the current tuple with th give Object[] after they are coerced.
      Parameters:
        `values` - to replace the current wrapped tuple instance values

    - #### size

          public int size()

      Method size returns the number of values in this instance.
      Returns:
        int

    - #### getObject

          public Object getObject(int pos)

      Method getObject returns the value in the given position pos.

      No coercion is performed if there is an associated coercible type.
      Parameters:
        `pos` - position of the element to return.
      Returns:
        Object

    - #### getObject

          public Object getObject(int pos,
                         Type type)

      Method getObject returns the value in the given field or position as the requested type.

      Coercion is performed to the given type.
      Parameters:
        `pos` - position of the element to return.
      Returns:
        Object

    - #### getObject

          public Object getObject(Comparable fieldName)

      Method getObject returns the value in the given field or position.
      `fieldName` may optionally be a `Fields` instance. Only the first field name or position will be considered.

      No coercion is performed if there is an associated coercible type.
      Parameters:
        `fieldName` - field name or position to return
      Returns:
        Comparable

    - #### getObject

          public Object getObject(Comparable fieldName,
                         Type type)

      Method getObject returns the value in the given field or position as the requested type.
      `fieldName` may optionally be a `Fields` instance. Only the first field name or position will be considered.

      Coercion is performed to the given type.
      Parameters:
        `fieldName` - field name or position to return
      Returns:
        Comparable

    - #### setRaw

          public void setRaw(int pos,
                    Object value)

      Method set sets the value in the given position.

      No coercion is performed if there is an associated coercible type.
      Parameters:
        `pos` - position to set
        `value` - of type Comparable

    - #### setRaw

          public void setRaw(Comparable fieldName,
                    Object value)

      Method set sets the value in the given field or position.

      No coercion is performed if there is an associated coercible type.
      Parameters:
        `fieldName` - field name or position to set
        `value` - of type Comparable

    - #### setObject

          public void setObject(Comparable fieldName,
                       Object value)

      Method set sets the value in the given field or position.
      Parameters:
        `fieldName` - field name or position to set
        `value` - of type Comparable

    - #### setBoolean

          public void setBoolean(Comparable fieldName,
                        boolean value)

      Method setBoolean sets the value in the given field or position.
      Parameters:
        `fieldName` - field name or position to set
        `value` - of type boolean

    - #### setShort

          public void setShort(Comparable fieldName,
                      short value)

      Method setShort sets the value in the given field or position.
      Parameters:
        `fieldName` - field name or position to set
        `value` - of type short

    - #### setInteger

          public void setInteger(Comparable fieldName,
                        int value)

      Method setInteger sets the value in the given field or position.
      Parameters:
        `fieldName` - field name or position to set
        `value` - of type int

    - #### setLong

          public void setLong(Comparable fieldName,
                     long value)

      Method setLong sets the value in the given field or position.
      Parameters:
        `fieldName` - field name or position to set
        `value` - of type long

    - #### setFloat

          public void setFloat(Comparable fieldName,
                      float value)

      Method setFloat sets the value in the given field or position.
      Parameters:
        `fieldName` - field name or position to set
        `value` - of type float

    - #### setDouble

          public void setDouble(Comparable fieldName,
                       double value)

      Method setDouble sets the value in the given field or position.
      Parameters:
        `fieldName` - field name or position to set
        `value` - of type double

    - #### setString

          public void setString(Comparable fieldName,
                       String value)

      Method setString sets the value in the given field or position.
      Parameters:
        `fieldName` - field name or position to set
        `value` - of type String

    - #### getString

          public String getString(Comparable fieldName)

      Method getString returns the element for the given field name or position as a String.
      `fieldName` may optionally be a `Fields` instance. Only the first field name or position will be considered.
      Parameters:
        `fieldName` - field name or position to return
      Returns:
        String

    - #### getFloat

          public float getFloat(Comparable fieldName)

      Method getFloat returns the element for the given field name or position as a float. Zero if null.
      `fieldName` may optionally be a `Fields` instance. Only the first field name or position will be considered.
      Parameters:
        `fieldName` - field name or position to return
      Returns:
        float

    - #### getDouble

          public double getDouble(Comparable fieldName)

      Method getDouble returns the element for the given field name or position as a double. Zero if null.
      `fieldName` may optionally be a `Fields` instance. Only the first field name or position will be considered.
      Parameters:
        `fieldName` - field name or position to return
      Returns:
        double

    - #### getInteger

          public int getInteger(Comparable fieldName)

      Method getInteger returns the element for the given field name or position as an int. Zero if null.
      `fieldName` may optionally be a `Fields` instance. Only the first field name or position will be considered.
      Parameters:
        `fieldName` - field name or position to return
      Returns:
        int

    - #### getLong

          public long getLong(Comparable fieldName)

      Method getLong returns the element for the given field name or position as a long. Zero if null.
      `fieldName` may optionally be a `Fields` instance. Only the first field name or position will be considered.
      Parameters:
        `fieldName` - field name or position to return
      Returns:
        long

    - #### getShort

          public short getShort(Comparable fieldName)

      Method getShort returns the element for the given field name or position as a short. Zero if null.
      `fieldName` may optionally be a `Fields` instance. Only the first field name or position will be considered.
      Parameters:
        `fieldName` - field name or position to return
      Returns:
        short

    - #### getBoolean

          public boolean getBoolean(Comparable fieldName)

      Method getBoolean returns the element for the given field name or position as a boolean. If the value is (case ignored) the string 'true', a `true` value will be returned. `false` if null.
      `fieldName` may optionally be a `Fields` instance. Only the first field name or position will be considered.
      Parameters:
        `fieldName` - field name or position to return
      Returns:
        boolean

    - #### selectEntry

          public TupleEntry selectEntry(Fields selector)

      Method selectEntry selects the fields specified in the selector from this instance. If `Fields.ALL` or the same fields as declared are given, `this` will be returned.

      The returned TupleEntry will be either modifiable or unmodifiable, depending on the state of this TupleEntry instance.

      See `selectEntryCopy(Fields)` to guarantee a copy suitable for modifying or caching/storing in a collection.

      Note this is a bug fix and change from 2.0 and 2.1. In previous versions the modifiable state was dependent on the given selector.
      Parameters:
        `selector` - Fields selector that selects the values to return
      Returns:
        TupleEntry

    - #### selectEntryCopy

          public TupleEntry selectEntryCopy(Fields selector)

      Method selectEntry selects the fields specified in selector from this instance.

      It is guaranteed to return a new modifiable TupleEntry instance at a cost of copying data.

      The returned instance is safe to cache.
      Parameters:
        `selector` - Fields selector that selects the values to return
      Returns:
        TupleEntry

    - #### selectTuple

          public Tuple selectTuple(Fields selector)

      Method selectTuple selects the fields specified in the selector from this instance. If `Fields.ALL` or the same fields as declared are given, `this.getTuple()` will be returned.

      The returned Tuple will be either modifiable or unmodifiable, depending on the state of this TupleEntry instance.

      See `selectTupleCopy(Fields)` to guarantee a copy suitable for modifying or caching/storing in a collection.

      Note this is a bug fix and change from 2.0 and 2.1. In previous versions the modifiable state was dependent on the given selector.
      Parameters:
        `selector` - Fields selector that selects the values to return
      Returns:
        Tuple

    - #### selectTupleCopy

          public Tuple selectTupleCopy(Fields selector)

      Method selectTupleCopy selects the fields specified in selector from this instance.

      It is guaranteed to return a new modifiable Tuple instance at a cost of copying data.

      The returned instance is safe to cache.
      Parameters:
        `selector` - Fields selector that selects the values to return
      Returns:
        Tuple

    - #### selectInto

          public Tuple selectInto(Fields selector,
                         Tuple tuple)

      Method selectInto selects the fields specified in the selector from this instance and copies them into the given tuple argument.
      Parameters:
        `selector` - of type Fields
        `tuple` - of type Tuple
      Returns:
        returns the given tuple argument with new values added

    - #### setTuple

          public void setTuple(Fields selector,
                      Tuple tuple)

      Method setTuple sets the values specified by the selector to the values given by the given tuple, the given values will always be copied into this TupleEntry.
      Parameters:
        `selector` - of type Fields
        `tuple` - of type Tuple

    - #### set

          public void set(TupleEntry tupleEntry)

      Method set sets the values from the given tupleEntry into this TupleEntry instance based on the given tupleEntry field names.

      If type information is given, each incoming value will be coerced from its canonical type to the current type.
      Parameters:
        `tupleEntry` - of type TupleEntry

    - #### appendNew

          public TupleEntry appendNew(TupleEntry entry)

      Method appendNew appends the given TupleEntry instance to this instance.
      Parameters:
        `entry` - of type TupleEntry
      Returns:
        TupleEntry

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

    - #### asIterableOf

          public <T> Iterable<T> asIterableOf(Class<T> type)

      Method asIterableOf returns an `Iterable` instance that will coerce all Tuple elements into the given `type` parameter.

      This method honors any `CoercibleType` instances on the internal Fields instance for the specified Tuple element.
      Parameters:
        `type` - of type Class
      Returns:
        an Iterable

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