com.saxonica.stream.feed

## Class GroupingFeed

- java.lang.Object
- - com.saxonica.stream.feed.ItemFeed
  - - com.saxonica.stream.feed.GroupingFeed

- All Implemented Interfaces:
    Feed
  Direct Known Subclasses:
    GroupAdjacentFeed, GroupEndingFeed, GroupStartingFeed

      public abstract class GroupingFeed
      extends ItemFeed

  This feed supports xsl:for-each-group in streaming mode. It is supplied with all the nodes selected by the xsl:for-each-group instruction (in composed form); it decides whether a node is the first in a new group, and if so, triggers the start/end-of-group actions. It also feeds every node into a push pipeline that reflects the processing of the "current-group" variable. The items received by this Feed will generally be supplied by a CopyOfWatch. There is scope for future optimization to prevent the selected nodes being unnecessarily composed in memory. There are thus two destinations into which this class feeds. The first, identified by the usual result variable, receives every item in the group, and is notified of the start and end of a group by calling its open() and close() methods. This destination processes the instructions within the for-each-group instruction before and after the reference to the grouping variable. The second destination, identified by the variable outerFeed, has its open() method called at the beginning of processing the population, and its close() method called at the end of processing the population; its append() method is called with the items that result from evaluation of the for-each-group body.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `GroupingFeed(GroupVariableReference expression, Feed result, Stack<XPathContext> contextStack)`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `append(Item item)` Supply one item towards the streamed input of the expression (that is, one item of the grouping population)
    `void` | `close()` Finish evaluating the expression.
    `ForEachGroup` | `getControllingExpression()`
    `protected XPathContext` | `getLocalContext()`
    `protected abstract boolean` | `isStartOfNewGroup(boolean atStart, XPathContext context)` Determine whether the current item is the start of a new group
    `void` | `open()` Called at the start of the for-each-group instruction
    `void` | `setControllingExpression(ForEachGroup controllingExpression)`
    `void` | `setOuterFeed(Feed out)` Set the outer feed; the feed to be notified (via its open() and close() methods) of the start of the grouping population and the end of the grouping population

    - ### Methods inherited from class com.saxonica.stream.feed.ItemFeed

      `getContext, getContextStack, getExpression, getPipelineConfiguration, getResult, setPipelineConfiguration`

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

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

- - ### Constructor Detail

    - #### GroupingFeed

          public GroupingFeed(GroupVariableReference expression,
                      Feed result,
                      Stack<XPathContext> contextStack)

  - ### Method Detail

    - #### setOuterFeed

          public void setOuterFeed(Feed out)

      Set the outer feed; the feed to be notified (via its open() and close() methods) of the start of the grouping population and the end of the grouping population
      Parameters:
        `out` - the outer feed

    - #### getLocalContext

          protected XPathContext getLocalContext()

    - #### setControllingExpression

          public void setControllingExpression(ForEachGroup controllingExpression)

    - #### getControllingExpression

          public ForEachGroup getControllingExpression()

    - #### open

          public void open()
                    throws XPathException

      Called at the start of the for-each-group instruction
      Specified by:
        `open` in interface `Feed`
      Overrides:
        `open` in class `ItemFeed`
      Throws:
        `XPathException`

    - #### append

          public void append(Item item)
                      throws XPathException

      Supply one item towards the streamed input of the expression (that is, one item of the grouping population)
      Specified by:
        `append` in interface `Feed`
      Specified by:
        `append` in class `ItemFeed`
      Parameters:
        `item` - the next item from the population
      Throws:
        `XPathException` - to report any failure

    - #### close

          public void close()
                     throws XPathException

      Description copied from class: `ItemFeed`
      Finish evaluating the expression. The default implementation does nothing.
      Specified by:
        `close` in interface `Feed`
      Overrides:
        `close` in class `ItemFeed`
      Throws:
        `XPathException` - if a dynamic error occurs

    - #### isStartOfNewGroup

          protected abstract boolean isStartOfNewGroup(boolean atStart,
                                  XPathContext context)
                                                throws XPathException

      Determine whether the current item is the start of a new group
      Parameters:
        `atStart` - true if this item is the first in the population
        `context` - the evaluation context. The item in question will be the context item
      Returns:
        true if this item is to be the first in a new group
      Throws:
        `XPathException` - if a dynamic error occurs

Copyright (c) 2004-2013 Saxonica Limited. All rights reserved.