cascading.tuple
Class Fields

java.lang.Object
  cascading.tuple.Fields

All Implemented Interfaces:

Serializable, Comparable, Iterable

public final class Fields
extends Object
implements Comparable, Iterable, Serializable

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.

Fields are used as both declarators and selectors. A declarator declares that a given Tap or BaseOperation 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 atleast 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 six predefined Fields sets used for different purposes; ALL, GROUP, VALUES, ARGS, RESULTS, and UNKNOWN.

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

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 postition, -1
static Fields	RESULTS Field RESULTS represents all fields returned by the current operation
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.
static Fields	asDeclaration(Fields fields) Method asDeclaration returns a new Fields instance for use as a declarator based on the given fields value.
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.
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.
int[]	getPos() Method getPos returns the pos array of this Fields object.
int	getPos(Comparable field) Method getPos returns the index of the give field value in this Fields instance.
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	isOrdered() Method isOrdered returns true if this instance is orderd.
boolean	isOutSelector() Method isOutSelector returns true if this instance is 'defined', or the field set ALL or RESULTS.
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	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(Fields... fields) Method join joins all given Fields instances into a new Fields instance.
Fields	minus(Fields fields) Method minus returns the difference between this instance and the given fields instance.
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.
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.
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.
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

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

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 postition, -1

Constructor Detail

Fields

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

Constructor Fields creates a new Fields instance.

Parameters:

kind - of type Kind

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

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.

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

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.

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 int getPos(Comparable field)

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:

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

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

minus

public Fields minus(Fields fields)

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

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.

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

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

equals

public boolean equals(Object object)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object