Package com.saxonica.ee.stream

## Class Inversion

- java.lang.Object
- - com.saxonica.ee.stream.Inversion

-     public class Inversion
      extends java.lang.Object

  This class represents an expression that has been "inverted" (in the Jackson sense) so that its execution is push-driven, that is, driven by events from the streamed document. The route taken by these events through the expressions in the expression tree is the "streaming route". Currently this class is simply a wrapper around the `Inversion` object that represents the path through the expression tree containing expressions that are evaluated in push mode, that is, those that perform downward navigation in the streamed document input.

  The expression inversion is represented by a "streaming route", which is the path of nodes in the expression tree, from the root to a leaf, being evaluated in streaming mode. The streaming route starts with a Watch, which is notified by the parser of interesting events. It then proceeds through a series of Feeds which process these events (or items composed from these events) before finally being output to a Receiver which handles the transformation result.

  The list of actions is "outermost expression first". This is the opposite of the order in which the events actually pass through the pipeline.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `static class` | `Inversion.PushAction` | A PushAction is a collection of data that together represents the strategy for how an expression should be evaluated in push mode.

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `Inversion()` |

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `append​(Inversion.PushAction action)` | Add an action to the end of the streaming route (a subexpression of the currently-last expression, which is therefore first to receive events from the parser)
    `Inversion` | `copy()` | Create a copy of this inverted expression
    `void` | `explain​(Configuration config)` |
    `void` | `explain​(ExpressionPresenter out)` | Display the streaming route for diagnostic purposes
    `java.util.List<Inversion.PushAction>` | `getRoute()` | Get the list of push actions making up the streaming route
    `Trigger` | `getWatch​(WatchManager watchManager, ItemFeed parentFeed, XPathContext context)` | Make a Watch to represent this streaming route.
    `static Inversion` | `invertExpression​(Expression exp, boolean forGrouping)` | Compute the Jackson inversion of an expression.
    `void` | `prepend​(Inversion.PushAction action)` | Add an action to the start of this streaming route (a parent of the currently-first expression, which is therefore last to receive events from the parser)

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

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

- - ### Constructor Detail

    - #### Inversion

          public Inversion()

  - ### Method Detail

    - #### invertExpression

          public static Inversion invertExpression​(Expression exp,
                                                   boolean forGrouping)
                                            throws XPathException

      Compute the Jackson inversion of an expression. The effect is (a) to determine whether the expression is streamable (throwing an exception if not), and (b) to construct the "Streaming route", that is, the path through the expression tree containing expressions that perform downward navigation within the streamed document
      Parameters:
        `exp` - the expression to be inverted
        `forGrouping` - true if the expression is the body of a for-each-group that is to be inverted with respect to the grouping variable rather than the context item
      Returns:
        the inverted expression
      Throws:
        `XPathException` - if the expression is not streamable

    - #### copy

          public Inversion copy()

      Create a copy of this inverted expression
      Returns:
        the copy

    - #### append

          public void append​(Inversion.PushAction action)

      Add an action to the end of the streaming route (a subexpression of the currently-last expression, which is therefore first to receive events from the parser)
      Parameters:
        `action` - the action to be appended

    - #### prepend

          public void prepend​(Inversion.PushAction action)

      Add an action to the start of this streaming route (a parent of the currently-first expression, which is therefore last to receive events from the parser)
      Parameters:
        `action` - the action to be prepended

    - #### getRoute

          public java.util.List<Inversion.PushAction> getRoute()

      Get the list of push actions making up the streaming route
      Returns:
        the list of push actions

    - #### getWatch

          public Trigger getWatch​(WatchManager watchManager,
                                  ItemFeed parentFeed,
                                  XPathContext context)
                           throws XPathException

      Make a Watch to represent this streaming route. The Watch is registered with the WatchManager so it can be notified of events that cause it to be activated
      Parameters:
        `watchManager` - the WatchManager (which is known to each Watch under its control)
        `parentFeed` - Maybe null. The destination of events after processing by this Watch
        `context` - XPath context object
      Returns:
        the Watch
      Throws:
        `XPathException` - if an error occurs, e.g. if streaming is not possible.

    - #### explain

          public void explain​(Configuration config)

    - #### explain

          public void explain​(ExpressionPresenter out)

      Display the streaming route for diagnostic purposes
      Parameters:
        `out` - the display destination