cascading.tuple

Class TupleEntry

java.lang.Object

cascading.tuple.TupleEntry

public class TupleEntry
extends java.lang.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

Modifier and Type	Method and Description
TupleEntry	appendNew(TupleEntry entry) Method appendNew appends the given TupleEntry instance to this instance.
<T> java.lang.Iterable<T>	asIterableOf(java.lang.Class<T> type) Method asIterableOf returns an Iterable instance that will coerce all Tuple elements into the given type parameter.
boolean	equals(java.lang.Object object)
boolean	getBoolean(java.lang.Comparable fieldName) Method getBoolean returns the element for the given field name or position as a boolean.
Tuple	getCoercedTuple(java.lang.reflect.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(java.lang.reflect.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(java.lang.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(java.lang.Comparable fieldName) Method getFloat returns the element for the given field name or position as a float.
int	getInteger(java.lang.Comparable fieldName) Method getInteger returns the element for the given field name or position as an int.
long	getLong(java.lang.Comparable fieldName) Method getLong returns the element for the given field name or position as a long.
java.lang.Object	getObject(java.lang.Comparable fieldName) Method getObject returns the value in the given field or position.
java.lang.Object	getObject(java.lang.Comparable fieldName, java.lang.reflect.Type type) Method getObject returns the value in the given field or position as the requested type.
java.lang.Object	getObject(int pos) Method getObject returns the value in the given position pos.
java.lang.Object	getObject(int pos, java.lang.reflect.Type type) Method getObject returns the value in the given field or position as the requested type.
short	getShort(java.lang.Comparable fieldName) Method getShort returns the element for the given field name or position as a short.
java.lang.String	getString(java.lang.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(java.lang.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(java.lang.Object[] values) Method setCanonicalValues replaces each value of the current tuple with th give Object[] after they are coerced.
void	setCanonicalValues(java.lang.Object[] values, int offset, int length) Method setCanonicalValues replaces each value of the current tuple with th give Object[] after they are coerced.
void	setDouble(java.lang.Comparable fieldName, double value) Method setDouble sets the value in the given field or position.
void	setFloat(java.lang.Comparable fieldName, float value) Method setFloat sets the value in the given field or position.
void	setInteger(java.lang.Comparable fieldName, int value) Method setInteger sets the value in the given field or position.
void	setLong(java.lang.Comparable fieldName, long value) Method setLong sets the value in the given field or position.
void	setObject(java.lang.Comparable fieldName, java.lang.Object value) Method set sets the value in the given field or position.
void	setRaw(java.lang.Comparable fieldName, java.lang.Object value) Method set sets the value in the given field or position.
void	setRaw(int pos, java.lang.Object value) Method set sets the value in the given position.
void	setShort(java.lang.Comparable fieldName, short value) Method setShort sets the value in the given field or position.
void	setString(java.lang.Comparable fieldName, java.lang.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.
java.lang.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(java.lang.reflect.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(java.lang.reflect.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(java.lang.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

setCanonicalValues

public void setCanonicalValues(java.lang.Object[] values,
                               int offset,
                               int length)

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

offset - index to being the copy

length - the number of elements to copy

size

public int size()

Method size returns the number of values in this instance.

Returns:

int

getObject

public java.lang.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 java.lang.Object getObject(int pos,
                                  java.lang.reflect.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 java.lang.Object getObject(java.lang.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 java.lang.Object getObject(java.lang.Comparable fieldName,
                                  java.lang.reflect.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,
                   java.lang.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(java.lang.Comparable fieldName,
                   java.lang.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(java.lang.Comparable fieldName,
                      java.lang.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(java.lang.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(java.lang.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(java.lang.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(java.lang.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(java.lang.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(java.lang.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(java.lang.Comparable fieldName,
                      java.lang.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 java.lang.String getString(java.lang.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(java.lang.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(java.lang.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(java.lang.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(java.lang.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(java.lang.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(java.lang.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(java.lang.Object object)

Overrides:

equals in class java.lang.Object

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

asIterableOf

public <T> java.lang.Iterable<T> asIterableOf(java.lang.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