com.saxonica.stream.watch

## Class GroupingWatch

- java.lang.Object
- - com.saxonica.validate.AbstractWatch
  - - com.saxonica.stream.watch.EventPushingWatch
    - - com.saxonica.stream.watch.GroupingWatch

- All Implemented Interfaces:
    Watch
  Direct Known Subclasses:
    GroupAdjacentWatch, GroupEndingWatch, GroupStartingWatch

      public abstract class GroupingWatch
      extends EventPushingWatch

  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
    `GroupingWatch(GroupVariableReference expression, Feed out, Stack<XPathContext> contextStack)`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `close()` The close() method is called immediately before the Watch is destroyed, that is, when the element whose declaration scopes the constraint implemented by this Watch goes out of scope.
    `void` | `endSelectedParentNode(int locationId)` Signal that the endElement event has occurred for the element whose startElement event caused the Watch to be activated.
    `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
    `void` | `setWatchManager(WatchManager watchManager)`
    `Receiver` | `startSelectedParentNode(FleetingNode node, int locationId)` Supply one item towards the streamed input of the expression (that is, one item of the grouping population)

    - ### Methods inherited from class com.saxonica.stream.watch.EventPushingWatch

      `getContext, getContextStack, getExpression, getParentExpressionFeed, getResult, setParentExpressionFeed`

    - ### Methods inherited from class com.saxonica.validate.AbstractWatch

      `getAnchorNode, getNamespaceResolver, getPipelineConfiguration, getSelection, notifySelectedLeafNode, setAnchorNode, setNamespaceResolver, setPipelineConfiguration, setSelection`

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

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

- - ### Constructor Detail

    - #### GroupingWatch

          public GroupingWatch(GroupVariableReference expression,
                       Feed out,
                       Stack<XPathContext> contextStack)

  - ### Method Detail

    - #### setWatchManager

          public void setWatchManager(WatchManager watchManager)

    - #### 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 `Watch`
      Overrides:
        `open` in class `EventPushingWatch`
      Throws:
        `XPathException`

    - #### startSelectedParentNode

          public Receiver startSelectedParentNode(FleetingNode node,
                                         int locationId)
                                           throws XPathException

      Supply one item towards the streamed input of the expression (that is, one item of the grouping population)
      Parameters:
        `node` - the next item from the population
        `locationId` - the location associated with the element or document node (may be the location of the instruction that created it)
      Returns:
        a Receiver to be notified of all events starting with the startElement/startDocument event for the matched element, and ending with the endElement event for that element; or null if this feature is not required.
      Throws:
        `XPathException` - May be raised if a dynamic error occurs

    - #### endSelectedParentNode

          public void endSelectedParentNode(int locationId)
                                     throws XPathException

      Signal that the endElement event has occurred for the element whose startElement event caused the Watch to be activated.
      Parameters:
        `locationId` - the location of the element
      Throws:
        `XPathException` - May be raised if a constraint implemented by this Watch is violated

    - #### close

          public void close()
                     throws XPathException

      Description copied from class: `AbstractWatch`
      The close() method is called immediately before the Watch is destroyed, that is, when the element whose declaration scopes the constraint implemented by this Watch goes out of scope. The default implementation does nothing.
      Specified by:
        `close` in interface `Watch`
      Overrides:
        `close` in class `EventPushingWatch`
      Throws:
        `XPathException`

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