cascading.tuple
Class Fields

java.lang.Object
  extended by 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.
  Fields(Comparable[] fields, Type[] types)
           
  Fields(Comparable field, Type type)
           
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 suitable for use as a field declaration.
 Fields append(Fields[] fields)
          Deprecated. 
 Fields appendSelector(Fields fields)
          Method is used for appending the given Fields instance to this instance, into a new Fields instance suitable for use as a field selector.
 Fields applyType(Comparable fieldName, Type type)
          Method applyType should be used to associate a Type with a given field name or position.
 Fields applyTypes(Fields fields)
          Method applyType should be used to associate Type with a given field name or position as declared in the given Fields parameter.
 Fields applyTypes(Type... types)
          Method applyTypes returns a new Fields instance with the given types, replacing any existing type information within the new 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)
           
 boolean equalsFields(Fields fields)
          Method equalsFields compares only the internal field names and postions only between this and the given Fields instance.
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)
           
 Type getType(Comparable fieldName)
          Returns the Type at the given position or having the fieldName.
 Type getType(int pos)
           
 Class getTypeClass(Comparable fieldName)
          Returns the Class for the given position value.
 Class getTypeClass(int pos)
           
 Type[] getTypes()
          Returns a copy of the current types Type[] if any, else null.
 Class[] getTypesClasses()
          Returns a copy of the current types Class[] if any, else null.
 boolean hasComparators()
          Method hasComparators test if this Fields instance has Comparators.
 int hashCode()
           
 boolean hasTypes()
          Returns true if there are types associated with this instance.
 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 Comparable[] names(Comparable... names)
           
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 Fields object.
protected  void setType(int pos, Type type)
           
 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.
static Fields size(int size, Type type)
          Method size is a factory that makes new instances of Fields the given size with every field of the given type.
 Fields subtract(Fields fields)
          Method subtract returns the difference between this instance and the given fields instance.
 String toString()
           
static Type[] types(Type... types)
           
 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...

Fields

public Fields(Comparable field,
              Type type)

Fields

public Fields(Comparable[] fields,
              Type[] types)
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[]

names

public static Comparable[] names(Comparable... names)

types

public static Type[] types(Type... types)

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

size

public static Fields size(int size,
                          Type type)
Method size is a factory that makes new instances of Fields the given size with every field of the given type.

Parameters:
size - of type int
type - of type Type
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.

If the resulting set of fields and ordinals is length zero, NONE will be returned.

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

@Deprecated
public Fields append(Fields[] fields)
Deprecated. 

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

See subtract(Fields) for removing field names.

This method has been deprecated, see join(Fields...)

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 suitable for use as a field declaration.

That is, any positional elements (including relative positions like -1, will be ignored during the append. For example, the second 0 position is lost in the result.

assert new Fields( 0, "a" ).append( new Fields( 0, "b" ).equals( new Fields( 0, "a", 2, "b" )

See subtract(Fields) for removing field names.

Parameters:
fields - of type Fields
Returns:
Fields

appendSelector

public Fields appendSelector(Fields fields)
Method is used for appending the given Fields instance to this instance, into a new Fields instance suitable for use as a field selector.

That is, any positional elements will be retained during the append. For example, the 5 and 0 are retained in the result.

assert new Fields( 5, "a" ).append( new Fields( 0, "b" ).equals( new Fields( 5, "a", 0, "b" )

Note any relative positional elements are retained, thus appending two Fields each declaring -1 position will result in a TupleException noting duplicate fields.

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

applyType

public Fields applyType(Comparable fieldName,
                        Type type)
Method applyType should be used to associate a Type with a given field name or position. A new instance of Fields will be returned, this instance will not be modified.

fieldName may optionally be a Fields instance. Only the first field name or position will be considered.

Parameters:
fieldName - of type Comparable
type - of type Type

applyTypes

public Fields applyTypes(Fields fields)
Method applyType should be used to associate Type with a given field name or position as declared in the given Fields parameter.

A new instance of Fields will be returned, this instance will not be modified.

Parameters:
fields - of type Fields

applyTypes

public Fields applyTypes(Type... types)
Method applyTypes returns a new Fields instance with the given types, replacing any existing type information within the new instance.

The Class array must be the same length as the number for fields in this instance.

Parameters:
types - the class types of this Fields object.
Returns:
returns a new instance of Fields with this instances field names and the given types

getType

public Type getType(Comparable fieldName)
Returns the Type at the given position or having the fieldName.

Parameters:
fieldName - of type String or Number
Returns:
the Type

getType

public Type getType(int pos)

getTypeClass

public Class getTypeClass(Comparable fieldName)
Returns the Class for the given position value.

If the underlying value is of type CoercibleType, the result of CoercibleType.getCanonicalType() will returned.

Parameters:
fieldName - of type String or Number
Returns:
type Class

getTypeClass

public Class getTypeClass(int pos)

setType

protected void setType(int pos,
                       Type type)

getTypes

public Type[] getTypes()
Returns a copy of the current types Type[] if any, else null.

Returns:
of type Type[]

getTypesClasses

public Class[] getTypesClasses()
Returns a copy of the current types Class[] if any, else null.

If any underlying value is of type CoercibleType, the result of CoercibleType.getCanonicalType() will returned.

Returns:
of type Class

hasTypes

public final boolean hasTypes()
Returns true if there are types associated with this instance.

Returns:
boolean

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 Fields object. The Comparator array must be the same length as the number for fields in this instance.

Parameters:
comparators - the comparators of this Fields 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

equalsFields

public boolean equalsFields(Fields fields)
Method equalsFields compares only the internal field names and postions only between this and the given Fields instance. Type information is ignored.

Parameters:
fields - of type int
Returns:
true if this and the given instance have the same positions and/or field names.

hashCode

public int hashCode()
Overrides:
hashCode in class Object


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