Package net.sf.saxon.expr.flwor

## Class GroupByClause

- java.lang.Object
- - net.sf.saxon.expr.flwor.Clause
  - - net.sf.saxon.expr.flwor.GroupByClause

-     public class GroupByClause
      extends Clause

  This class represents an "group by" clause in a FLWOR expression

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `static class` | `GroupByClause.ObjectToBeGrouped` | Inner class representing the contents of a tuple from the pre-grouping tuple stream; a set of such objects consitutes a group.
    `class` | `GroupByClause.TupleComparisonKey` | Inner class representing a tuple comparison key: that is, an arbitrary object whose equals() and hashCode() methods can be used to test whether two tuples have equivalent grouping keys

    - ### Nested classes/interfaces inherited from class net.sf.saxon.expr.flwor.Clause

      `Clause.ClauseName`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `GroupByClause​(Configuration config)` | Create a group-by clause

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `addToPathMap​(PathMap pathMap, PathMap.PathMapNodeSet pathMapNodeSet)` | Collect information about the navigation paths followed by this clause, for document projection purposes
    `boolean` | `containsNonInlineableVariableReference​(Binding binding)` | Determine whether the clause contains a reference to a local variable binding that cannot be inlined
    `GroupByClause` | `copy​(FLWORExpression flwor, RebindingMap rebindings)` | Create a copy of this clause
    `void` | `explain​(ExpressionPresenter out)` | Diagnostic print of expression structure.
    `Clause.ClauseName` | `getClauseKey()` | Get a keyword identifying what kind of clause this is
    `GroupByClause.TupleComparisonKey` | `getComparisonKey​(Tuple t, GenericAtomicComparer[] comparers)` | Callback to get the comparison key for a tuple.
    `TupleExpression` | `getGroupingTupleExpression()` | Get the tuple expression that evaluates all the grouping variables, returning the values these variables take in the input stream
    `TuplePull` | `getPullStream​(TuplePull base, XPathContext context)` | Get a tuple stream that implements the functionality of this clause, taking its input from another tuple stream which this clause modifies
    `TuplePush` | `getPushStream​(TuplePush destination, Outputter output, XPathContext context)` | Get a push-mode tuple stream that implements the functionality of this clause, supplying its output to another tuple stream
    `LocalVariableBinding[]` | `getRangeVariables()` | Get the variables bound by this clause
    `TupleExpression` | `getRetainedTupleExpression()` | Get the tuple expression that evaluates all the non-grouping variables, returning the values these variables take in the grouping input stream
    `void` | `initGroupingTupleExpression​(FLWORExpression flwor, TupleExpression expr)` | Initialize a tuple expression that evaluates all the grouping variables, returning the values these variables take in the input stream
    `void` | `initRetainedTupleExpression​(FLWORExpression flwor, TupleExpression expr)` | Initialize a tuple expression that evaluates all the non-grouping variables, returning the values these variables take in the grouping input stream
    `void` | `optimize​(ExpressionVisitor visitor, ContextItemStaticInfo contextItemType)` | Optimize any expressions contained within this clause
    `void` | `processGroup​(java.util.List<GroupByClause.ObjectToBeGrouped> group, XPathContext context)` | Process a group of tuples from the input stream to generate a single tuple in the output stream.
    `void` | `processOperands​(OperandProcessor processor)` | Process the subexpressions of this clause
    `void` | `setComparers​(GenericAtomicComparer[] comparers)` | Set the comparers used for the grouping keys.
    `void` | `setGroupingTupleExpression​(TupleExpression expr)` | Set a tuple expression that evaluates all the grouping variables, returning the values these variables take in the input stream
    `void` | `setRetainedTupleExpression​(TupleExpression expr)` | Set a tuple expression that evaluates all the non-grouping variables, returning the values these variables take in the grouping input stream
    `void` | `setVariableBindings​(LocalVariableBinding[] bindings)` | Set the bindings of new variables created by the grouping clause, which constitute the variables appearing in the output (post-grouping) tuple stream.
    `java.lang.String` | `toString()` |

    - ### Methods inherited from class net.sf.saxon.expr.flwor.Clause

      `gatherVariableReferences, getConfiguration, getLocation, getPackageData, getTraceInfo, isRepeated, refineVariableType, setLocation, setPackageData, setRepeated, toShortString, typeCheck`

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### GroupByClause

          public GroupByClause​(Configuration config)

      Create a group-by clause
      Parameters:
        `config` - the Saxon configuration

  - ### Method Detail

    - #### getClauseKey

          public Clause.ClauseName getClauseKey()

      Description copied from class: `Clause`
      Get a keyword identifying what kind of clause this is
      Specified by:
        `getClauseKey` in class `Clause`
      Returns:
        the kind of clause

    - #### containsNonInlineableVariableReference

          public boolean containsNonInlineableVariableReference​(Binding binding)

      Description copied from class: `Clause`
      Determine whether the clause contains a reference to a local variable binding that cannot be inlined
      Overrides:
        `containsNonInlineableVariableReference` in class `Clause`
      Parameters:
        `binding` - the binding for the local variable in question
      Returns:
        true if this clause uses the variable in a way that does not permit inlining

    - #### copy

          public GroupByClause copy​(FLWORExpression flwor,
                                    RebindingMap rebindings)

      Description copied from class: `Clause`
      Create a copy of this clause
      Specified by:
        `copy` in class `Clause`
      Parameters:
        `flwor` - the new FLWORExpression to contain the copied clause
      Returns:
        the copied clause

    - #### initRetainedTupleExpression

          public void initRetainedTupleExpression​(FLWORExpression flwor,
                                                  TupleExpression expr)

      Initialize a tuple expression that evaluates all the non-grouping variables, returning the values these variables take in the grouping input stream
      Parameters:
        `flwor` - the containing FLWORExpression
        `expr` - the tuple expression

    - #### setRetainedTupleExpression

          public void setRetainedTupleExpression​(TupleExpression expr)

      Set a tuple expression that evaluates all the non-grouping variables, returning the values these variables take in the grouping input stream
      Parameters:
        `expr` - the tuple expression

    - #### getRetainedTupleExpression

          public TupleExpression getRetainedTupleExpression()

      Get the tuple expression that evaluates all the non-grouping variables, returning the values these variables take in the grouping input stream
      Returns:
        the tuple expression

    - #### optimize

          public void optimize​(ExpressionVisitor visitor,
                               ContextItemStaticInfo contextItemType)
                        throws XPathException

      Description copied from class: `Clause`
      Optimize any expressions contained within this clause
      Overrides:
        `optimize` in class `Clause`
      Parameters:
        `visitor` - the ExpressionVisitor, providing access to static context information
        `contextItemType` - the type of the context item
      Throws:
        `XPathException` - if any error is detected

    - #### initGroupingTupleExpression

          public void initGroupingTupleExpression​(FLWORExpression flwor,
                                                  TupleExpression expr)

      Initialize a tuple expression that evaluates all the grouping variables, returning the values these variables take in the input stream
      Parameters:
        `flwor` - the containing FLWORExpression
        `expr` - the tuple expression

    - #### setGroupingTupleExpression

          public void setGroupingTupleExpression​(TupleExpression expr)

      Set a tuple expression that evaluates all the grouping variables, returning the values these variables take in the input stream
      Parameters:
        `expr` - the tuple expression

    - #### getGroupingTupleExpression

          public TupleExpression getGroupingTupleExpression()

      Get the tuple expression that evaluates all the grouping variables, returning the values these variables take in the input stream
      Returns:
        the tuple expression

    - #### setVariableBindings

          public void setVariableBindings​(LocalVariableBinding[] bindings)

      Set the bindings of new variables created by the grouping clause, which constitute the variables appearing in the output (post-grouping) tuple stream. There will be one of these for each variable in the input (pre-grouping) stream; by convention the bindings for grouping variables precede the bindings for non-grouping (retained) variables, and the order is preserved.
      Parameters:
        `bindings` - the bindings of the variables created in the output stream

    - #### getRangeVariables

          public LocalVariableBinding[] getRangeVariables()

      Get the variables bound by this clause
      Overrides:
        `getRangeVariables` in class `Clause`
      Returns:
        the variable bindings

    - #### setComparers

          public void setComparers​(GenericAtomicComparer[] comparers)

      Set the comparers used for the grouping keys. There is one comparer for each grouping variable
      Parameters:
        `comparers` - the comparers for grouping keys.

    - #### getPullStream

          public TuplePull getPullStream​(TuplePull base,
                                         XPathContext context)

      Get a tuple stream that implements the functionality of this clause, taking its input from another tuple stream which this clause modifies
      Specified by:
        `getPullStream` in class `Clause`
      Parameters:
        `base` - the input tuple stream
        `context` - the XPath dynamic evaluation context
      Returns:
        the output tuple stream

    - #### getPushStream

          public TuplePush getPushStream​(TuplePush destination,
                                         Outputter output,
                                         XPathContext context)

      Get a push-mode tuple stream that implements the functionality of this clause, supplying its output to another tuple stream
      Specified by:
        `getPushStream` in class `Clause`
      Parameters:
        `destination` - the output tuple stream
        `output` - the destination for the result
        `context` - the dynamic evaluation context
      Returns:
        the push tuple stream that implements the functionality of this clause of the FLWOR expression

    - #### processOperands

          public void processOperands​(OperandProcessor processor)
                               throws XPathException

      Process the subexpressions of this clause
      Specified by:
        `processOperands` in class `Clause`
      Parameters:
        `processor` - the expression processor used to process the subexpressions
      Throws:
        `XPathException` - if any error is detected

    - #### explain

          public void explain​(ExpressionPresenter out)

      Diagnostic print of expression structure. The abstract expression tree is written to the supplied output destination.
      Specified by:
        `explain` in class `Clause`
      Parameters:
        `out` - the expression presenter used to display the structure

    - #### toString

          public java.lang.String toString()

      Overrides:
        `toString` in class `java.lang.Object`

    - #### processGroup

          public void processGroup​(java.util.List<GroupByClause.ObjectToBeGrouped> group,
                                   XPathContext context)
                            throws XPathException

      Process a group of tuples from the input stream to generate a single tuple in the output stream. This method takes a group of tuples as input, and sets all the required variables in the local stack frame as required to deliver this group as the current tuple in the post-grouping stream
      Parameters:
        `group` - the group of input tuples
        `context` - the XPath dynamic evaluation context
      Throws:
        `XPathException` - if a dynamic error occurs

    - #### getComparisonKey

          public GroupByClause.TupleComparisonKey getComparisonKey​(Tuple t,
                                                                   GenericAtomicComparer[] comparers)

      Callback to get the comparison key for a tuple. Two tuples are equal if their comparison keys compare equal using the equals() method.
      Parameters:
        `t` - the tuple whose comparison key is required
      Returns:
        a comparison key suitable for comparing with other tuples

    - #### addToPathMap

          public void addToPathMap​(PathMap pathMap,
                                   PathMap.PathMapNodeSet pathMapNodeSet)

      Description copied from class: `Clause`
      Collect information about the navigation paths followed by this clause, for document projection purposes
      Specified by:
        `addToPathMap` in class `Clause`
      Parameters:
        `pathMap` - the path map in which the data is to be collected
        `pathMapNodeSet` - the path map node set representing the paths to the context item