Package com.saxonica.ee.stream.adjunct

## Class StreamingAdjunct

- java.lang.Object
- - com.saxonica.ee.stream.adjunct.StreamingAdjunct

- Direct Known Subclasses:
    `ApplyImportsAdjunct`, `ApplyTemplatesAdjunct`, `AscentFunctionCallAdjunct`, `AtomicSequenceConverterAdjunct`, `AxisExpressionAdjunct`, `CallTemplateAdjunct`, `CodepointsToStringStreamer`, `ComposingAdjunct`, `ContextItemExprAdjunct`, `CopyAdjunct`, `CurrentGroupStreamer`, `DeepEqualStreamer`, `DistinctValuesStreamer`, `EmptyTextNodeRemoverAdjunct`, `FoldStreamer`, `ForExpressionAdjunct`, `ForkAdjunct`, `GeneralComparisonAdjunct`, `IndexOfStreamer`, `InspectionAdjunct`, `IsLastExprAdjunct`, `LastStreamer`, `LetExpressionAdjunct`, `LiteralAdjunct`, `MapEntryStreamer`, `MergeInstrAdjunct`, `MinimaxStreamer`, `NewMapStreamer`, `NextIterationAdjunct`, `NextMatchAdjunct`, `ParentConstructorAdjunct`, `ReverseStreamer`, `RootExpressionAdjunct`, `RootStreamer`, `SequenceInstrAdjunct`, `SimpleNodeConstructorAdjunct`, `SingletonAtomizerAdjunct`, `SortExpressionAdjunct`, `TransmissionAdjunct`, `UseAttributeSetAdjunct`, `UserFunctionCallAdjunct`, `XmlToJsonFnStreamer`

      public class StreamingAdjunct
      extends java.lang.Object

  This abstract class supplements an `Expression` with methods used at compile-time to support streaming, by generating a `Watch` that allows the expression to be evaluated in push mode.

  The default implementation is adequate only for expressions that take single items as their input. For other kinds of expression, either a WatchMaker or FeedMaker, or both, need to be supplied. If the input sequence is atomized (as with the sum() function), then only a FeedMaker is required; a TypedValueWatch will automatically be added to the Streaming Route to perform atomization of the supplied sequence. For expressions that do not perform atomization, both a WatchMaker (for use when the input is striding or consuming) and a FeedMaker (for use when it is climbing or grounded) need to be provided.

  Neither method should be called in cases where streamability analysis has decided that the expression is not streamable. In such cases the methods may throw an exception.

  There is a fallback implementation that allows any expression to be evaluated as a Feed, but it involves buffering the input in memory, and performing an implicit copy-of() to create a grounded copy, so it is only really suitable for the case where the input is a single atomic value.

- - ### Constructor Summary

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

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `PostureAndSweep` | `computeStreamability​(ContextItemStaticInfoEE contextInfo, java.util.List<java.lang.String> reasons)` | Compute the posture and sweep of this expression as defined in the W3C streamability specifications.
    `static int` | `findConsumingArg​(Expression expression, int knownConsumingArg)` | Find which operand of an expression is the consuming operand.
    `Configuration` | `getConfiguration()` | Get the Saxon Configuration
    `protected FeedMaker` | `getDefaultFeedMaker​(int arg)` | Get a FeedMaker which will generate a feed to handle streamed input of operand "arg".
    `Expression` | `getExpression()` | Get the expression being processed by this StreamingAdjunct
    `FeedMaker` | `getFeedMaker​(int arg)` | Get a FeedMaker, a factory class that creates a Feed to evaluate this expression in streaming mode.
    `WatchMaker` | `getWatchMaker​(boolean forGrouping)` | Get a WatchMaker, a factory class that creates a Watch to evaluate this expression in streaming mode.
    `static StreamingAdjunct` | `makeStreamingAdjunct​(Configuration config, Expression exp)` | Make a streaming adjunct for a particular expression.
    `void` | `setConfiguration​(Configuration config)` | Set the Saxon Configuration
    `void` | `setExpression​(Expression expression)` | Set the expression being processed by this StreamingAdjunct
    `Pattern` | `toStreamingPattern​(Configuration config)` | Convert this expression to a streaming pattern (a pattern used internally to match nodes during push processing of an event stream)

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

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

- - ### Constructor Detail

    - #### StreamingAdjunct

          public StreamingAdjunct()

  - ### Method Detail

    - #### makeStreamingAdjunct

          public static StreamingAdjunct makeStreamingAdjunct​(Configuration config,
                                                              Expression exp)

      Make a streaming adjunct for a particular expression.
      Parameters:
        `config` - the Saxon Configuration
        `exp` - the expression to be compiled
      Returns:
        the compiler for this kind of expression

    - #### setConfiguration

          public void setConfiguration​(Configuration config)

      Set the Saxon Configuration
      Parameters:
        `config` - the Configuration

    - #### getConfiguration

          public Configuration getConfiguration()

      Get the Saxon Configuration
      Returns:
        the configuration

    - #### setExpression

          public void setExpression​(Expression expression)

      Set the expression being processed by this StreamingAdjunct
      Parameters:
        `expression` - the expression being processed

    - #### getExpression

          public Expression getExpression()

      Get the expression being processed by this StreamingAdjunct
      Returns:
        the expression being processed

    - #### computeStreamability

          public PostureAndSweep computeStreamability​(ContextItemStaticInfoEE contextInfo,
                                                      java.util.List<java.lang.String> reasons)

      Compute the posture and sweep of this expression as defined in the W3C streamability specifications. This must be implemented in all subclasses that don't use the general streamability rules. The implementation should have the side-effect of computing the streamability of all subexpressions, recursively.
      Parameters:
        `contextInfo` - Information about the context item type and posture
        `reasons` - the caller may supply a list, in which case the implementation may add to this; the contents are human-readable messages explaining why the expression is not streamable.
      Returns:
        the posture and sweep of the expression

    - #### findConsumingArg

          public static int findConsumingArg​(Expression expression,
                                             int knownConsumingArg)
                                      throws XPathException

      Find which operand of an expression is the consuming operand. Helper method for use by subclasses
      Parameters:
        `expression` - the expression
        `knownConsumingArg` - index of the consuming operand if known, otherwise -1
      Returns:
        index identifying the consuming operand
      Throws:
        `XPathException` - if there is no consuming operand

    - #### toStreamingPattern

          public Pattern toStreamingPattern​(Configuration config)

      Convert this expression to a streaming pattern (a pattern used internally to match nodes during push processing of an event stream)
      Parameters:
        `config` - the Saxon configuration
      Returns:
        the equivalent pattern if conversion succeeds; otherwise null

    - #### getWatchMaker

          public WatchMaker getWatchMaker​(boolean forGrouping)
                                   throws XPathException

      Get a WatchMaker, a factory class that creates a Watch to evaluate this expression in streaming mode. This method will only be called if the getImplementationMethod() method of the expression includes the value `Expression.WATCH_METHOD`
      Parameters:
        `forGrouping` - true if the selected items are being grouped
      Returns:
        a Watchmaker to evaluate the expression, or null if it is not streamable with respect to the specificed argument.
      Throws:
        `XPathException` - in the event of a failure

    - #### getFeedMaker

          public FeedMaker getFeedMaker​(int arg)
                                 throws XPathException

      Get a FeedMaker, a factory class that creates a Feed to evaluate this expression in streaming mode. In many cases the StreamingAdjunct is itself a FeedMaker, in which case it returns itself. But where an expression has several operands, it will typically create different feeds depending on which argument is the streamed input, and in such cases the individual StreamingAdjunct makes the decision which feed to use, by returning an appropriate FeedMaker.
      Parameters:
        `arg` - identifies the argument with respect to which the expression is to be inverted: usually 0 to indicate the first argument is the value that is streamed. Argument numbering is the same as the sequence of arguments/operands returned by the method `Expression.operands()`
      Returns:
        a FeedMaker to evaluate the expression, or null if it is not streamable with respect to the specificed argument.
      Throws:
        `XPathException` - in the event of a failure

    - #### getDefaultFeedMaker

          protected FeedMaker getDefaultFeedMaker​(int arg)

      Get a FeedMaker which will generate a feed to handle streamed input of operand "arg".
      Parameters:
        `arg` - identifies which operand of the expression is the streamed (consuming) input
      Returns:
        a FeedMaker