Package com.yahoo.search.grouping.request

Class GroupingOperation

java.lang.Object

com.yahoo.search.grouping.request.GroupingNode

com.yahoo.search.grouping.request.GroupingOperation

Direct Known Subclasses:

AllOperation, EachOperation

public abstract class GroupingOperation
extends GroupingNode

This class represents a single node in a grouping operation tree. You may manually construct this tree, or you may use the fromString(String) method to generate one from a query-string. To execute, assign it to a GroupingRequest using the GroupingRequest.setRootOperation(GroupingOperation) method.

Author:

Simon Thoresen Hult

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	GroupingOperation(GroupingOperation parentOfCopy, java.lang.String image, java.lang.String label, java.util.List<GroupingExpression> orderBy, java.util.List<GroupingExpression> outputs, java.util.List<GroupingOperation> children, java.util.Map<java.lang.String,GroupingExpression> aliases, java.util.Set<java.lang.String> hints, GroupingExpression groupBy, java.lang.String where, boolean forceSinglePass, double accuracy, int precision, int level, int max)
protected	GroupingOperation(java.lang.String image, java.lang.String label)

Method Summary

Modifier and Type	Method	Description
GroupingOperation	addChild(GroupingOperation op)	Adds a child grouping node to this.
GroupingOperation	addChildren(java.util.List<GroupingOperation> lst)	Convenience method to call addChild(GroupingOperation) for each element in the given list.
GroupingOperation	addHint(java.lang.String hint)	Adds a hint to this.
GroupingOperation	addOrderBy(GroupingExpression exp)	Adds an expression to the order-by clause of this operation.
GroupingOperation	addOrderBy(java.util.List<GroupingExpression> list)	Convenience method to call addOrderBy(GroupingExpression) for each element in the given list.
GroupingOperation	addOutput(GroupingExpression exp)	Adds an expression to the output clause of this operation.
GroupingOperation	addOutputs(java.util.List<GroupingExpression> lst)	Convenience method to call addOutput(GroupingExpression) for each element in the given list.
boolean	containsHint(java.lang.String hint)	Returns whether or not the given hint has been added to this.
abstract GroupingOperation	copy(GroupingOperation parentOfCopy)	Returns a deep copy of this
static GroupingOperation	fromString(java.lang.String str)	Convenience method to call fromStringAsList(String) and assert that the list contains exactly one grouping operation.
static java.util.List<GroupingOperation>	fromStringAsList(java.lang.String string)	Parses the given string as a list of grouping operations.
double	getAccuracy()	Return the accuracy of this.
GroupingExpression	getAlias(java.lang.String id)	Returns the alias associated with the given name.
protected java.util.Map<java.lang.String,GroupingExpression>	getAliases()	Returns a direct, mutable copy of the aliases of this, never null
GroupingOperation	getChild(int i)	Returns the child operation at the given index.
java.util.List<GroupingOperation>	getChildren()	Returns an immutable view to the child list of this node.
boolean	getForceSinglePass()
GroupingExpression	getGroupBy()	Returns the expression assigned as the group-by clause of this.
java.util.Set<java.lang.String>	getHints()	Returns an immutable view to the hint list of this node.
int	getLevel()	Returns the conceptual level of this node.
static java.lang.String	getLevelDesc(int level)	Returns a description of the given level.
int	getMax()	Returns the max clause of this.
int	getNumChildren()	Returns the number of child operations of this.
int	getNumOrderBy()	Returns the number of expressions in the order-by clause of this.
int	getNumOutputs()	Returns the number of expressions in the output clause of this.
java.util.List<GroupingExpression>	getOrderBy()	Returns an immutable view to the order-by clause of this.
GroupingExpression	getOrderBy(int i)	Returns the group-by expression at the given index.
GroupingExpression	getOutput(int i)	Returns the output expression at the given index.
java.util.List<GroupingExpression>	getOutputs()	Returns an immutable view to the output clause of this.
protected GroupingOperation	getParent()	Returns the parent of this, or null if none
int	getPrecision()	Returns the precision clause of this.
java.lang.String	getWhere()	Returns the where clause assigned to this operation.
boolean	hasMax()	Indicates if the 'max' value has been set.
GroupingOperation	putAlias(java.lang.String id, GroupingExpression exp)	Registers an alias with this operation.
void	resolveLevel(int level)	Resolves the conceptual level of this operation.
GroupingOperation	setAccuracy(double accuracy)	Assigns an accuracy value for this.
GroupingOperation	setForceSinglePass(boolean forceSinglePass)
GroupingOperation	setGroupBy(GroupingExpression exp)	Assigns an expressions as the group-by clause of this operation.
GroupingOperation	setLabel(java.lang.String label)	Assigns a label to this grouping expression.
GroupingOperation	setMax(int max)	Assigns the max clause of this.
GroupingOperation	setPrecision(int precision)	Assigns the precision clause of this.
GroupingOperation	setWhere(java.lang.String string)	Assigns a string as the where clause of this operation.
java.lang.String	toString()
void	visitExpressions(ExpressionVisitor visitor)	Recursively calls GroupingExpression.visit(ExpressionVisitor) on all GroupingExpression objects in this operation and in all of its child operations.

Methods inherited from class com.yahoo.search.grouping.request.GroupingNode

getImage, getLabel

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

GroupingOperation

protected GroupingOperation(java.lang.String image,
                            java.lang.String label)

GroupingOperation

protected GroupingOperation(GroupingOperation parentOfCopy,
                            java.lang.String image,
                            java.lang.String label,
                            java.util.List<GroupingExpression> orderBy,
                            java.util.List<GroupingExpression> outputs,
                            java.util.List<GroupingOperation> children,
                            java.util.Map<java.lang.String,GroupingExpression> aliases,
                            java.util.Set<java.lang.String> hints,
                            GroupingExpression groupBy,
                            java.lang.String where,
                            boolean forceSinglePass,
                            double accuracy,
                            int precision,
                            int level,
                            int max)

Method Detail

copy

public abstract GroupingOperation copy(GroupingOperation parentOfCopy)

Returns a deep copy of this

putAlias

public GroupingOperation putAlias(java.lang.String id,
                                  GroupingExpression exp)

Registers an alias with this operation. An alias is made available to expressions in both this node and all child nodes.

Parameters:

id - The id of the alias to put.

exp - The expression to associate with the id.

Returns:

This, to allow chaining.

getAlias

public GroupingExpression getAlias(java.lang.String id)

Returns the alias associated with the given name. If no alias can be found in this node, this method queries its parent grouping node. If the alias still can not be found, this method returns null.

Parameters:

id - The id of the alias to return.

Returns:

The expression associated with the id.

getAliases

protected java.util.Map<java.lang.String,GroupingExpression> getAliases()

Returns a direct, mutable copy of the aliases of this, never null

addHint

public GroupingOperation addHint(java.lang.String hint)

Adds a hint to this.

Parameters:

hint - The hint to add.

Returns:

This, to allow chaining.

containsHint

public boolean containsHint(java.lang.String hint)

Returns whether or not the given hint has been added to this.

Parameters:

hint - The hint to check for.

Returns:

True if the hint has been added.

getHints

public java.util.Set<java.lang.String> getHints()

Returns an immutable view to the hint list of this node.

Returns:

The list.

addChild

public GroupingOperation addChild(GroupingOperation op)

Adds a child grouping node to this. This will also set the parent of the child so that it points to this node.

Parameters:

op - The child node to add.

Returns:

This, to allow chaining.

addChildren

public GroupingOperation addChildren(java.util.List<GroupingOperation> lst)

Convenience method to call addChild(GroupingOperation) for each element in the given list.

Parameters:

lst - The list of operations to add.

Returns:

This, to allow chaining.

getNumChildren

public int getNumChildren()

Returns the number of child operations of this.

Returns:

The child count.

getChild

public GroupingOperation getChild(int i)

Returns the child operation at the given index.

Parameters:

i - The index of the child to return.

Returns:

The child at the given index.

Throws:

java.lang.IndexOutOfBoundsException - If the index is out of range.

getChildren

public java.util.List<GroupingOperation> getChildren()

Returns an immutable view to the child list of this node.

Returns:

The list.

setGroupBy

public GroupingOperation setGroupBy(GroupingExpression exp)

Assigns an expressions as the group-by clause of this operation.

Parameters:

exp - The expression to assign to this.

Returns:

This, to allow chaining.

getGroupBy

public GroupingExpression getGroupBy()

Returns the expression assigned as the group-by clause of this.

Returns:

The expression.

getLevel

public int getLevel()

Returns the conceptual level of this node.

Returns:

The level, or -1 if not resolved.

See Also:

resolveLevel(int)

resolveLevel

public void resolveLevel(int level)

Resolves the conceptual level of this operation. This level represents the type of data that is consumed by this operation, where level 0 is a single hit, level 1 is a group, level 2 is a list of groups, and so forth. This method verifies the input level against the operation type, and recursively resolves the level of all argument expressions.

Parameters:

level - the level of the input data

Throws:

java.lang.IllegalArgumentException - thrown if a contained expression is invalid for the given level

getParent

protected GroupingOperation getParent()

Returns the parent of this, or null if none

setForceSinglePass

public GroupingOperation setForceSinglePass(boolean forceSinglePass)

getForceSinglePass

public boolean getForceSinglePass()

setMax

public GroupingOperation setMax(int max)

Assigns the max clause of this. This is the maximum number of groups to return for this operation.

Parameters:

max - The expression to assign to this.

Returns:

This, to allow chaining.

See Also:

setPrecision(int)

getMax

public int getMax()

Returns the max clause of this.

Returns:

The expression.

See Also:

setMax(int)

hasMax

public boolean hasMax()

Indicates if the 'max' value has been set.

Returns:

true if max value is set.

setAccuracy

public GroupingOperation setAccuracy(double accuracy)

Assigns an accuracy value for this. This is a number between 0 and 1 describing the accuracy of the result, which again determines the speed of the grouping request. A low value will make sure the grouping operation runs fast, at the sacrifice if a (possible) imprecise result.

Parameters:

accuracy - The accuracy to assign to this.

Returns:

This, to allow chaining.

Throws:

java.lang.IllegalArgumentException - If the accuracy is outside the allowed value range.

getAccuracy

public double getAccuracy()

Return the accuracy of this.

addOrderBy

public GroupingOperation addOrderBy(GroupingExpression exp)

Adds an expression to the order-by clause of this operation.

Parameters:

exp - the expressions to add to this

Returns:

this, to allow chaining

addOrderBy

public GroupingOperation addOrderBy(java.util.List<GroupingExpression> list)

Convenience method to call addOrderBy(GroupingExpression) for each element in the given list.

Parameters:

list - the list of expressions to add

Returns:

this, to allow chaining

getNumOrderBy

public int getNumOrderBy()

Returns the number of expressions in the order-by clause of this.

Returns:

the expression count

getOrderBy

public GroupingExpression getOrderBy(int i)

Returns the group-by expression at the given index.

Parameters:

i - the index of the expression to return

Returns:

the expression at the given index

Throws:

java.lang.IndexOutOfBoundsException - if the index is out of range

getOrderBy

public java.util.List<GroupingExpression> getOrderBy()

Returns an immutable view to the order-by clause of this.

Returns:

the expression list

addOutput

public GroupingOperation addOutput(GroupingExpression exp)

Adds an expression to the output clause of this operation.

Parameters:

exp - the expressions to add to this

Returns:

this, to allow chaining

addOutputs

public GroupingOperation addOutputs(java.util.List<GroupingExpression> lst)

Convenience method to call addOutput(GroupingExpression) for each element in the given list.

Parameters:

lst - the list of expressions to add

Returns:

this, to allow chaining

getNumOutputs

public int getNumOutputs()

Returns the number of expressions in the output clause of this.

Returns:

the expression count

getOutput

public GroupingExpression getOutput(int i)

Returns the output expression at the given index.

Parameters:

i - the index of the expression to return

Returns:

the expression at the given index

Throws:

java.lang.IndexOutOfBoundsException - If the index is out of range

getOutputs

public java.util.List<GroupingExpression> getOutputs()

Returns an immutable view to the output clause of this.

Returns:

the expression list

setPrecision

public GroupingOperation setPrecision(int precision)

Assigns the precision clause of this. This is the number of intermediate groups returned from each search-node during expression evaluation to give the dispatch-node more data to consider when selecting the N groups that are to be evaluated further.

Parameters:

precision - the precision to set

Returns:

this, to allow chaining

See Also:

setMax(int)

getPrecision

public int getPrecision()

Returns the precision clause of this.

setWhere

public GroupingOperation setWhere(java.lang.String string)

Assigns a string as the where clause of this operation.

Parameters:

string - the string to assign to this

Returns:

this, to allow chaining

getWhere

public java.lang.String getWhere()

Returns the where clause assigned to this operation.

Returns:

The where clause.

visitExpressions

public void visitExpressions(ExpressionVisitor visitor)

Recursively calls GroupingExpression.visit(ExpressionVisitor) on all GroupingExpression objects in this operation and in all of its child operations.

Parameters:

visitor - The visitor to call.

setLabel

public GroupingOperation setLabel(java.lang.String label)

Description copied from class: GroupingNode

Assigns a label to this grouping expression. The label is applied to the results of this expression so that they can be identified by the caller when processing the output.

Overrides:

setLabel in class GroupingNode

Parameters:

label - The label to assign to this.

Returns:

This, to allow chaining.

toString

public java.lang.String toString()

Overrides:

toString in class GroupingNode

getLevelDesc

public static java.lang.String getLevelDesc(int level)

Returns a description of the given level. This allows for more descriptive errors being passed back to the user.

Parameters:

level - The level to describe.

Returns:

A description of the given level.

fromString

public static GroupingOperation fromString(java.lang.String str)

Convenience method to call fromStringAsList(String) and assert that the list contains exactly one grouping operation.

Parameters:

str - the string to parse

Returns:

a grouping operation that corresponds to the string

Throws:

java.lang.IllegalArgumentException - thrown if the string could not be parsed as a single operation

fromStringAsList

public static java.util.List<GroupingOperation> fromStringAsList(java.lang.String string)

Parses the given string as a list of grouping operations. This method never returns null, it either returns a list of valid grouping requests or it throws an exception.

Parameters:

string - the string to parse

Returns:

a list of grouping operations that corresponds to the string

Throws:

java.lang.IllegalArgumentException - thrown if the string could not be parsed