cascading.tuple
Class Fields

java.lang.Object
  cascading.tuple.Fields

All Implemented Interfaces:

Serializable, Comparable, Iterable<Comparable>, Comparator<Tuple>

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

Class Fields represents the field names in a Tuple. A tuple field may be a literal String value representing a name, or it may be a literal Integer value representing a position, where positions start at position 0. A Fields instance may also represent a set of field names and positions.

Fields are used as both declarators and selectors. A declarator declares that a given Tap or Operation returns the given field names, for a set of values the size of the given Fields instance. A selector is used to select given referenced fields from a Tuple. For example;
Fields fields = new Fields( "a", "b", "c" );
This creates a new Fields instance with the field names "a", "b", and "c". This Fields instance can be used as both a declarator or a selector, depending on how it's used.

Or For example;
Fields fields = new Fields( 1, 2, -1 );
This creates a new Fields instance that can only be used as a selector. It would select the second, third, and last position from a given Tuple instance, assuming it has at least four positions. Since the original field names for those positions will carry over to the new selected Tuple instance, if the original Tuple only had three positions, the third and last positions would be the same, and would throw an error on there being duplicate field names in the selected Tuple instance.

Additionally, there are eight predefined Fields sets used for different purposes; NONE, ALL, GROUP, VALUES, ARGS, RESULTS, UNKNOWN, REPLACE, and SWAP.

The NONE Fields set represents no fields.

The ALL Fields set is a "wildcard" that represents all the current available fields.

The GROUP Fields set represents all the fields used as grouping values in a previous Splice. If there is no previous Group in the pipe assembly, the GROUP represents all the current field names.

The VALUES Fields set represent all the fields not used as grouping fields in a previous Group.

The ARGS Fields set is used to let a given Operation inherit the field names of its argument Tuple. This Fields set is a convenience and is typically used when the Pipe output selector is RESULTS or REPLACE.

The RESULTS Fields set is used to represent the field names of the current Operations return values. This Fields set may only be used as an output selector on a Pipe. It effectively replaces in the input Tuple with the Operation result Tuple.

The UNKNOWN Fields set is used when Fields must be declared, but how many and their names is unknown. This allows for arbitrarily length Tuples from an input source or some Operation. Use this Fields set with caution.

The REPLACE Fields set is used as an output selector to inline replace values in the incoming Tuple with the results of an Operation. This is a convenience Fields set that allows subsequent Operations to 'step' on the value with a given field name. The current Operation must always use the exact same field names, or the ARGS Fields set.

The SWAP Fields set is used as an output selector to swap out Operation arguments with its results. Neither the argument and result field names or size need to be the same. This is useful for when the Operation arguments are no longer necessary and the result Fields and values should be appended to the remainder of the input field names and Tuple.

See Also:

Serialized Form

Field Summary

static Fields	ALL Field ALL represents a wildcard for all fields
static Fields	ARGS Field ARGS represents all fields used as the arguments for the current operation
static Fields	FIRST Field FIRST represents the first field position, 0
static Fields	GROUP Field KEYS represents all fields used as they key for the last grouping
static Fields	LAST Field LAST represents the last field position, -1
static Fields	NONE Field NONE represents a wildcard for no fields
static Fields	REPLACE Field REPLACE represents all incoming fields, and allows their values to be replaced by the current operation results.
static Fields	RESULTS Field RESULTS represents all fields returned by the current operation
static Fields	SWAP Field SWAP represents all fields not used as arguments for the current operation and the operations results.
static Fields	UNKNOWN Field UNKNOWN
static Fields	VALUES Field VALUES represents all fields used as values for the last grouping

Constructor Summary

	Fields(Comparable... fields) Constructor Fields creates a new Fields instance.
protected	Fields(cascading.tuple.Fields.Kind kind) Constructor Fields creates a new Fields instance.

Method Summary

Fields	append(Fields fields) Method is used for appending the given Fields instance to this instance, into a new Fields instance.
Fields	append(Fields[] fields) Method is used for appending the given Fields instance to this instance, into a new Fields instance.
static Fields	asDeclaration(Fields fields) Method asDeclaration returns a new Fields instance for use as a declarator based on the given fields value.
protected static Comparable	asFieldName(Comparable fieldName)
int	compare(Tuple lhs, Tuple rhs)
int	compareTo(Fields other) Method compareTo compares this instance to the given Fields instance.
int	compareTo(Object other) Method compareTo implements Comparable.compareTo(Object).
boolean	contains(Fields fields) Method contains returns true if this instance contains the field names and positions specified in the given fields instance.
static Fields	copyComparators(Fields toFields, Fields... fromFields)
boolean	equals(Object object)
static Fields[]	fields(Fields... fields) Method fields is a convenience method to create an array of Fields instances.
Comparable	get(int i) Method get returns the field name or position at the given index i.
protected Comparator	getComparator(Comparable fieldName)
Comparator[]	getComparators() Method getComparators returns the comparators of this Fields object.
int[]	getPos() Method getPos returns the pos array of this Fields object.
int	getPos(Comparable fieldName) Method getPos returns the index of the give field value in this Fields instance.
int[]	getPos(Fields fields)
boolean	hasComparators() Method hasComparators test if this Fields instance has Comparators.
int	hashCode()
boolean	isAll() Method isAll returns true if this instance is the ALL field set.
boolean	isArgSelector() Method isArgSelector returns true if this instance is 'defined' or the field set ALL, GROUP, or VALUES.
boolean	isArguments() Method isArguments returns true if this instance is the ARGS field set.
boolean	isDeclarator() Method isDeclarator returns true if this can be used as a declarator.
boolean	isDefined() Method isDefined returns true if this instance is not a field set like ALL or UNKNOWN.
boolean	isGroup() Method isKeys returns true if this instance is the GROUP field set.
boolean	isNone() Method isNone returns returns true if this instance is the NONE field set.
boolean	isOrdered() Method isOrdered returns true if this instance is ordered.
boolean	isOutSelector() Method isOutSelector returns true if this instance is 'defined', or the field set ALL or RESULTS.
boolean	isReplace() Method isReplace returns true if this instance is the REPLACE field set.
boolean	isResults() Method isResults returns true if this instance is the RESULTS field set.
boolean	isSubstitution() Method isSubstitution returns true if this instance is a substitution fields set.
boolean	isSwap() Method isSwap returns true if this instance is the SWAP field set.
boolean	isUnknown() Method isUnknown returns true if this instance is the UNKNOWN field set.
boolean	isUnOrdered() Method isUnOrdered returns true if this instance is unordered.
boolean	isValues() Method isValues returns true if this instance is the VALUES field set.
Iterator	iterator() Method iterator return an unmodifiable iterator of field values.
static Fields	join(boolean maskDuplicateNames, Fields... fields)
static Fields	join(Fields... fields) Method join joins all given Fields instances into a new Fields instance.
static Fields	mask(Fields fields, Fields mask)
static Fields	merge(Fields... fields) Method merge merges all given Fields instances into a new Fields instance where a merge is a set union of all the given Fields instances.
static Fields	offsetSelector(int size, int startPos) Method offsetSelector is a factory that makes new instances of Fields the given size but offset by startPos.
String	print() Method print returns a String representation of this instance.
String	printVerbose() Method printLong returns a String representation of this instance along with the size.
Fields	project(Fields fields) Method project will return a new Fields instance similar to the given fields instance except any absolute positional elements will be replaced by the current field names, if any.
Fields	rename(Fields from, Fields to) Method rename will rename the from fields to the values in to to fields.
static Fields	resolve(Fields selector, Fields... fields) Method resolve returns a new selector expanded on the given field declarations
Fields	select(Fields selector) Method select returns a new Fields instance with fields specified by the given selector.
Fields	selectPos(Fields selector) Method selectPos returns a Fields instance with only positional fields, no field names.
Fields	selectPos(Fields selector, int offset) Method selectPos returns a Fields instance with only positional fields, offset by given offset value, no field names.
void	setComparator(Comparable fieldName, Comparator comparator) Method setComparator should be used to associate a Comparator with a given field name or position.
void	setComparators(Comparator... comparators) Method setComparators sets all the comparators of this FieldsComparator object.
int	size() Method size returns the number of field positions in this instance.
static Fields	size(int size) Method size is a factory that makes new instances of Fields the given size.
Fields	subtract(Fields fields) Method subtract returns the difference between this instance and the given fields instance.
String	toString()
void	verifyContains(Fields fields) Method verifyContains tests if this instance contains the field names and positions specified in the given fields instance.

Methods inherited from class java.lang.Object

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

Field Detail

UNKNOWN

public static final Fields UNKNOWN

Field UNKNOWN

NONE

public static final Fields NONE

Field NONE represents a wildcard for no fields

ALL

public static final Fields ALL

Field ALL represents a wildcard for all fields

GROUP

public static final Fields GROUP

Field KEYS represents all fields used as they key for the last grouping

VALUES

public static final Fields VALUES

Field VALUES represents all fields used as values for the last grouping

ARGS

public static final Fields ARGS

Field ARGS represents all fields used as the arguments for the current operation

RESULTS

public static final Fields RESULTS

Field RESULTS represents all fields returned by the current operation

REPLACE

public static final Fields REPLACE

Field REPLACE represents all incoming fields, and allows their values to be replaced by the current operation results.

SWAP

public static final Fields SWAP

Field SWAP represents all fields not used as arguments for the current operation and the operations results.

FIRST

public static final Fields FIRST

Field FIRST represents the first field position, 0

LAST

public static final Fields LAST

Field LAST represents the last field position, -1

Constructor Detail

Fields

protected Fields(cascading.tuple.Fields.Kind kind)

Constructor Fields creates a new Fields instance.

Parameters:

kind - of type Kind

Fields

@ConstructorProperties(value="fields")
public Fields(Comparable... fields)

Constructor Fields creates a new Fields instance.

Parameters:

fields - of type Comparable...

Method Detail

fields

public static Fields[] fields(Fields... fields)

Method fields is a convenience method to create an array of Fields instances.

Parameters:

fields - of type Fields

Returns:

Fields[]

size

public static Fields size(int size)

Method size is a factory that makes new instances of Fields the given size.

Parameters:

size - of type int

Returns:

Fields

join

public static Fields join(Fields... fields)

Method join joins all given Fields instances into a new Fields instance.

Use caution with this method, it does not assume the given Fields are either selectors or declarators. Numeric position fields are left untouched.

Parameters:

fields - of type Fields

Returns:

Fields

join

public static Fields join(boolean maskDuplicateNames,
                          Fields... fields)

mask

public static Fields mask(Fields fields,
                          Fields mask)

merge

public static Fields merge(Fields... fields)

Method merge merges all given Fields instances into a new Fields instance where a merge is a set union of all the given Fields instances.

Thus duplicate positions or field names are allowed, they are subsequently discarded in favor of the first occurrence. That is, merging "a" and "a" would yield "a", not "a, a", yet merging "a,b" and "c" would yield "a,b,c".

Use caution with this method, it does not assume the given Fields are either selectors or declarators. Numeric position fields are left untouched.

Parameters:

fields - of type Fields

Returns:

Fields

copyComparators

public static Fields copyComparators(Fields toFields,
                                     Fields... fromFields)

offsetSelector

public static Fields offsetSelector(int size,
                                    int startPos)

Method offsetSelector is a factory that makes new instances of Fields the given size but offset by startPos. The result Fields instance can only be used as a selector.

Parameters:

size - of type int

startPos - of type int

Returns:

Fields

resolve

public static Fields resolve(Fields selector,
                             Fields... fields)

Method resolve returns a new selector expanded on the given field declarations

Parameters:

selector - of type Fields

fields - of type Fields

Returns:

Fields

asDeclaration

public static Fields asDeclaration(Fields fields)

Method asDeclaration returns a new Fields instance for use as a declarator based on the given fields value.

Typically this is used to convert a selector to a declarator. Simply, all numeric position fields are replaced by their absolute position.

Comparators are preserved in the result.

Parameters:

fields - of type Fields

Returns:

Fields

isUnOrdered

public boolean isUnOrdered()

Method isUnOrdered returns true if this instance is unordered. That is, it has relative numeric field positions. For example; [1,"a",2,-1]

Returns:

the unOrdered (type boolean) of this Fields object.

isOrdered

public boolean isOrdered()

Method isOrdered returns true if this instance is ordered. That is, all numeric field positions are absolute. For example; [0,"a",2,3]

Returns:

the ordered (type boolean) of this Fields object.

isDefined

public boolean isDefined()

Method isDefined returns true if this instance is not a field set like ALL or UNKNOWN.

Returns:

the defined (type boolean) of this Fields object.

isOutSelector

public boolean isOutSelector()

Method isOutSelector returns true if this instance is 'defined', or the field set ALL or RESULTS.

Returns:

the outSelector (type boolean) of this Fields object.

isArgSelector

public boolean isArgSelector()

Method isArgSelector returns true if this instance is 'defined' or the field set ALL, GROUP, or VALUES.

Returns:

the argSelector (type boolean) of this Fields object.

isDeclarator

public boolean isDeclarator()

Method isDeclarator returns true if this can be used as a declarator. Specifically if it is 'defined' or UNKNOWN, ALL, ARGS, GROUP, or VALUES.

Returns:

the declarator (type boolean) of this Fields object.

isNone

public boolean isNone()

Method isNone returns returns true if this instance is the NONE field set.

Returns:

the none (type boolean) of this Fields object.

isAll

public boolean isAll()

Method isAll returns true if this instance is the ALL field set.

Returns:

the all (type boolean) of this Fields object.

isUnknown

public boolean isUnknown()

Method isUnknown returns true if this instance is the UNKNOWN field set.

Returns:

the unknown (type boolean) of this Fields object.

isArguments

public boolean isArguments()

Method isArguments returns true if this instance is the ARGS field set.

Returns:

the arguments (type boolean) of this Fields object.

isValues

public boolean isValues()

Method isValues returns true if this instance is the VALUES field set.

Returns:

the values (type boolean) of this Fields object.

isResults

public boolean isResults()

Method isResults returns true if this instance is the RESULTS field set.

Returns:

the results (type boolean) of this Fields object.

isReplace

public boolean isReplace()

Method isReplace returns true if this instance is the REPLACE field set.

Returns:

the replace (type boolean) of this Fields object.

isSwap

public boolean isSwap()

Method isSwap returns true if this instance is the SWAP field set.

Returns:

the swap (type boolean) of this Fields object.

isGroup

public boolean isGroup()

Method isKeys returns true if this instance is the GROUP field set.

Returns:

the keys (type boolean) of this Fields object.

isSubstitution

public boolean isSubstitution()

Method isSubstitution returns true if this instance is a substitution fields set. Specifically if it is the field set ALL, ARGS, GROUP, or VALUES.

Returns:

the substitution (type boolean) of this Fields object.

get

public final Comparable get(int i)

Method get returns the field name or position at the given index i.

Parameters:

i - is of type int

Returns:

Comparable

getPos

public int[] getPos()

Method getPos returns the pos array of this Fields object.

Returns:

the pos (type int[]) of this Fields object.

getPos

public final int[] getPos(Fields fields)

getPos

public int getPos(Comparable fieldName)

Method getPos returns the index of the give field value in this Fields instance. The index corresponds to the Tuple value index in an associated Tuple instance.

Parameters:

fieldName - of type Comparable

Returns:

int

iterator

public Iterator iterator()

Method iterator return an unmodifiable iterator of field values. if isSubstitution() returns true, this iterator will be empty.

Specified by:

iterator in interface Iterable<Comparable>

Returns:

Iterator

select

public Fields select(Fields selector)

Method select returns a new Fields instance with fields specified by the given selector.

Parameters:

selector - of type Fields

Returns:

Fields

selectPos

public Fields selectPos(Fields selector)

Method selectPos returns a Fields instance with only positional fields, no field names.

Parameters:

selector - of type Fields

Returns:

Fields instance with only positions.

selectPos

public Fields selectPos(Fields selector,
                        int offset)

Method selectPos returns a Fields instance with only positional fields, offset by given offset value, no field names.

Parameters:

selector - of type Fields

offset - of type int

Returns:

Fields instance with only positions.

subtract

public Fields subtract(Fields fields)

Method subtract returns the difference between this instance and the given fields instance.

See append(Fields) for adding field names.

Parameters:

fields - of type Fields

Returns:

Fields

append

public Fields append(Fields[] fields)

Method is used for appending the given Fields instance to this instance, into a new Fields instance.

See subtract(Fields) for removing field names.

Parameters:

fields - of type Fields[]

Returns:

Fields

append

public Fields append(Fields fields)

Method is used for appending the given Fields instance to this instance, into a new Fields instance.

See subtract(Fields) for removing field names.

Parameters:

fields - of type Fields

Returns:

Fields

rename

public Fields rename(Fields from,
                     Fields to)

Method rename will rename the from fields to the values in to to fields. Fields may contain field names, or positions.

Using positions is useful to remove a field name put keep its place in the Tuple stream.

Parameters:

from - of type Fields

to - of type Fields

Returns:

Fields

project

public Fields project(Fields fields)

Method project will return a new Fields instance similar to the given fields instance except any absolute positional elements will be replaced by the current field names, if any.

Parameters:

fields - of type Fields

Returns:

Fields

verifyContains

public void verifyContains(Fields fields)

Method verifyContains tests if this instance contains the field names and positions specified in the given fields instance. If the test fails, a TupleException is thrown.

Parameters:

fields - of type Fields

Throws:

TupleException - when one or more fields are not contained in this instance.

contains

public boolean contains(Fields fields)

Method contains returns true if this instance contains the field names and positions specified in the given fields instance.

Parameters:

fields - of type Fields

Returns:

boolean

compareTo

public int compareTo(Fields other)

Method compareTo compares this instance to the given Fields instance.

Parameters:

other - of type Fields

Returns:

int

compareTo

public int compareTo(Object other)

Method compareTo implements Comparable.compareTo(Object).

Specified by:

compareTo in interface Comparable

Parameters:

other - of type Object

Returns:

int

print

public String print()

Method print returns a String representation of this instance.

Returns:

String

printVerbose

public String printVerbose()

Method printLong returns a String representation of this instance along with the size.

Returns:

String

toString

public String toString()

Overrides:

toString in class Object

size

public final int size()

Method size returns the number of field positions in this instance.

Returns:

int

setComparator

public void setComparator(Comparable fieldName,
                          Comparator comparator)

Method setComparator should be used to associate a Comparator with a given field name or position.
fieldName may optionally be a Fields instance. Only the first field name or position will be considered.

Parameters:

fieldName - of type Comparable

comparator - of type Comparator

setComparators

public void setComparators(Comparator... comparators)

Method setComparators sets all the comparators of this FieldsComparator object. The Comparator array must be the same length as the number for fields in this instance.

Parameters:

comparators - the comparators of this FieldsComparator object.

asFieldName

protected static Comparable asFieldName(Comparable fieldName)

getComparator

protected Comparator getComparator(Comparable fieldName)

getComparators

public Comparator[] getComparators()

Method getComparators returns the comparators of this Fields object.

Returns:

the comparators (type Comparator[]) of this Fields object.

hasComparators

public boolean hasComparators()

Method hasComparators test if this Fields instance has Comparators.

Returns:

boolean

compare

public int compare(Tuple lhs,
                   Tuple rhs)

Specified by:

compare in interface Comparator<Tuple>

equals

public boolean equals(Object object)

Specified by:

equals in interface Comparator<Tuple>

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object