Package com.saxonica.ee.stream.feed

## Class ItemFeed

- java.lang.Object
- - net.sf.saxon.event.Outputter
  - - net.sf.saxon.event.ProxyOutputter
    - - com.saxonica.ee.stream.feed.ItemFeed

- All Implemented Interfaces:
    `javax.xml.transform.Result`, `Receiver`
  Direct Known Subclasses:
    `ApplyTemplatesAction`, `ApplyTemplatesFeed`, `AtomicItemFeed`, `BooleanFnFeed`, `BufferingApplyTemplatesFeed`, `BufferingFeed`, `BufferingFilterExpressionFeed`, `BufferingForEachExpressionFeed`, `CallableFeed`, `CardinalityCheckingFeed`, `ComplexNodeEventFeed`, `ConditionalBlockAdjunct.ConditionalBlockFeed`, `DecomposingFeed`, `DelegatingFeed`, `ExistenceFeed`, `FeedToEventBuffer`, `ForEachAction`, `ForEachGroupPartitionAction`, `ForExpressionAdjunct.ForExpressionFeed`, `GroundedItemFeed`, `ItemCheckingFeed`, `LiteralAdjunct.LiteralItemFeed`, `MotionlessFeed`, `NextIterationFeed`, `NoCloseFeed`, `NoOpenFeed`, `NoOpenOrCloseFeed`, `ShallowCopyEventFeed`, `SimpleNodeConstructorFeed`, `SinkFeed`, `TryCatchAdjunct.TryCatchFeed`

      public abstract class ItemFeed
      extends ProxyOutputter

  An ItemFeed evaluates an expression in "composed push" mode. Its streaming input is supplied via a sequence of event calls (start element, end element, etc) that represent the value of the streamed operand of the expression; other operands are evaluated in pull mode in the usual way.

  Expressions are thus evaluated "bottom up": instead of a parent expression triggering the evaluation of its children, the appearance of data needed by a child expression causes evaluation of the child expression, which then triggers evaluation of its parent, and so on.

  One consequence of this is that special mechanisms are needed for error handling. In particular, it's not possible for a child expression to notify its parent expression of dynamic errors simply by throwing a Java exception: the error information needs to be passed up the pipeline in the same way as regular results.

  Some expressions (inspection expressions) are only interested in top-level events: for example `count()`, `exists`, and `instance of` only need to know about a `startElement` event, they are not interested in the content of the element, only in its existence. Other expressions (absorption expression) need access to the content of the element: in most cases, the typed value of the element, but in some cases (such as `copy-of()` or `snapshot()` a finer-grained representation of the content. In such cases the `startSelectedParentNode(FleetingParentNode, Location)` method (which is notified of a top-level event in the input stream) returns a `Receiver`, which is then notified of all the contained events up to the corresponding `endElement`.

  Some expressions (transmission expression) pass data on to their parent expressions directly, and in these cases the decision whether to ask for full details of the content is delegated to the parent expression, or beyond.

  An expression whose result is known before all the input is available (for example, `exists()` can call a supplied `Terminator` to indicate that no more input is required. In some cases (where the expression would otherwise read an entire document) this enables parsing of the streamed input file to be abandoned.

  The events passed up the pipeline will usually correspond to nodes in the streamed source document, or to atomic values computed from those nodes. In unusual edge cases, however, a consuming expression may generate new element or document nodes, which are still delivered incrementally because their content is established by streaming the source document. Events representing these constructed elements are passed up the pipeline as if they came from the source document. (Note, because this situation is unusual and somewhat contrived, it probably has incomplete test coverage and may not be fully implemented for all kinds of expression).

  The start of an element may be represented either as a single event containing all the attributes and namespaces, or as a sequence of separate events (start element, attributes, namespaces, then `startContent`). Events coming directly from parsing the streamed input will use the more efficient "bundled" form, but events representing constructed nodes may be "unbundled" because attributes and namespaces can be constructed incrementally as the streamed input is processed. An `ItemFeed` for a parent expression should therefore be prepared to accept either form.

- - ### Field Summary

    - ### Fields inherited from class net.sf.saxon.event.Outputter

      `pipelineConfiguration, systemId`

    - ### Fields inherited from interface javax.xml.transform.Result

      `PI_DISABLE_OUTPUT_ESCAPING, PI_ENABLE_OUTPUT_ESCAPING`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `ItemFeed​(ItemFeed result, XPathContext context)` |
    `ItemFeed​(Outputter result, XPathContext context, boolean thisIsAnExceptionalCase)` | Special constructor for the last ItemFeed in the pipeline, which feeds into an Outputter rather than into another ItemFeed.
    `ItemFeed​(Expression exp, ItemFeed result, XPathContext context)` |

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `abstract void` | `append​(Item item)` | Supply one item towards the streamed input of the expression
    `void` | `append​(Item item, Location locationId, int properties)` | Supply one item towards the streamed input of the expression.
    `void` | `close()` | Finish evaluating the expression.
    `void` | `dynamicError​(XPathException error)` | Report a dynamic error.
    `void` | `endSelectedParentNode​(Location locationId)` | Signal that the endElement event has occurred for the element whose startElement event caused the Watch to be activated.
    `XPathContext` | `getContext()` | Get the dynamic evaluation context
    `Expression` | `getExpression()` | Get the expression being evaluated by this ItemFeed.
    `ItemFeed` | `getResult()` | Get the result, that is, the ItemFeed to which the items in the result of the expression should be supplied
    `Terminator` | `getTerminator()` | Get the Terminator which can be used to request early termination of the Feed
    `boolean` | `hasFailed()` |
    `void` | `open​(Terminator terminator)` | Start evaluating the expression.
    `static void` | `processItems​(SequenceIterator iter, Outputter result)` | Convenience method to process all the items selected by an iterator and push them to the next feed in the push pipeline
    `void` | `setExpression​(Expression exp)` | Set the expression being evaluated by this ItemFeed
    `void` | `setHasFailed()` | Mark this feed as having failed (that is, as having detected and reported a dynamic error).
    `void` | `setTerminator​(Terminator terminator)` | Provide a callback that can be used to request early termination of the streaming of this input document
    `Receiver` | `startSelectedParentNode​(FleetingParentNode node, Location locationId)` | Signal that an element or document node has been found that matches the selection that this Watch is looking for.

    - ### Methods inherited from class net.sf.saxon.event.ProxyOutputter

      `attribute, characters, comment, endDocument, endElement, getNextOutputter, namespace, open, processingInstruction, setLocation, setUnparsedEntity, startContent, startDocument, startElement, startElement, usesTypeAnnotations`

    - ### Methods inherited from class net.sf.saxon.event.Outputter

      `getConfiguration, getPipelineConfiguration, getStringReceiver, getSystemId, namespaces, setPipelineConfiguration, setSystemId`

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

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

    - ### Methods inherited from interface net.sf.saxon.event.Receiver

      `handlesAppend`

- - ### Constructor Detail

    - #### ItemFeed

          public ItemFeed​(ItemFeed result,
                          XPathContext context)

    - #### ItemFeed

          public ItemFeed​(Expression exp,
                          ItemFeed result,
                          XPathContext context)

    - #### ItemFeed

          public ItemFeed​(Outputter result,
                          XPathContext context,
                          boolean thisIsAnExceptionalCase)

      Special constructor for the last ItemFeed in the pipeline, which feeds into an Outputter rather than into another ItemFeed. Note that the getResult() method in this situation will throw an exception.
      Parameters:
        `result` - the resulting outputter
        `context` - the dynamic evaluation context
        `thisIsAnExceptionalCase` - value is ignored; the parameter is there simply to flag this constructor as a special case

  - ### Method Detail

    - #### processItems

          public static void processItems​(SequenceIterator iter,
                                          Outputter result)
                                   throws XPathException

      Convenience method to process all the items selected by an iterator and push them to the next feed in the push pipeline
      Parameters:
        `iter` - iterator over the selected items
        `result` - the next feed in the pipeline
      Throws:
        `XPathException` - if any dynamic error occurs

    - #### setExpression

          public void setExpression​(Expression exp)

      Set the expression being evaluated by this ItemFeed
      Parameters:
        `exp` - the relevant expression

    - #### getExpression

          public Expression getExpression()

      Get the expression being evaluated by this ItemFeed. May be null if not known or not relevant
      Returns:
        the expression being evaluated

    - #### setTerminator

          public void setTerminator​(Terminator terminator)

      Provide a callback that can be used to request early termination of the streaming of this input document
      Parameters:
        `terminator` - the class that can be called to request termination

    - #### setHasFailed

          public void setHasFailed()

      Mark this feed as having failed (that is, as having detected and reported a dynamic error). Once the feed is marked as having failed, it should not attempt to process any further input.

    - #### getTerminator

          public Terminator getTerminator()

      Get the Terminator which can be used to request early termination of the Feed
      Returns:
        the Terminator that was passed to the open() call, or null if open() has not been called

    - #### getResult

          public ItemFeed getResult()

      Get the result, that is, the ItemFeed to which the items in the result of the expression should be supplied
      Returns:
        the Outputter that consumes the results of this expression

    - #### getContext

          public XPathContext getContext()

      Get the dynamic evaluation context
      Returns:
        the dynamic evaluation context

    - #### open

          public void open​(Terminator terminator)
                    throws XPathException

      Start evaluating the expression. The default implementation does nothing.
      Parameters:
        `terminator` - used to achieve early exit
      Throws:
        `XPathException` - if a dynamic error occurs

    - #### startSelectedParentNode

          public Receiver startSelectedParentNode​(FleetingParentNode node,
                                                  Location locationId)
                                           throws XPathException

      Signal that an element or document node has been found that matches the selection that this Watch is looking for. This method is called by the WatchManager while processing the startElement or startDocument event that matches the selection.
      Parameters:
        `node` - the element or document node whose start event has been matched
        `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

    - #### append

          public abstract void append​(Item item)
                               throws XPathException

      Supply one item towards the streamed input of the expression
      Specified by:
        `append` in interface `Receiver`
      Overrides:
        `append` in class `ProxyOutputter`
      Parameters:
        `item` - the item to be supplied
      Throws:
        `XPathException` - if the operation fails

    - #### append

          public final void append​(Item item,
                                   Location locationId,
                                   int properties)
                            throws XPathException

      Supply one item towards the streamed input of the expression. This implementation calls `append(Item)`, and it is final so subclasses do not have to cater for this event
      Specified by:
        `append` in interface `Receiver`
      Overrides:
        `append` in class `ProxyOutputter`
      Parameters:
        `item` - the item to be supplied
        `locationId` - the location of the calling instruction, for diagnostics
        `properties` - if the item is an element node, this indicates whether its namespaces need to be copied. Values are `ReceiverOption.ALL_NAMESPACES`; the default (0) means
      Throws:
        `XPathException` - if an error occurs

    - #### endSelectedParentNode

          public void endSelectedParentNode​(Location 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

      Finish evaluating the expression.
      Specified by:
        `close` in interface `Receiver`
      Overrides:
        `close` in class `ProxyOutputter`
      Throws:
        `XPathException` - if a dynamic error occurs

    - #### dynamicError

          public void dynamicError​(XPathException error)
                            throws XPathException

      Report a dynamic error. This requires searching up the "feed" pipeline to see if there is a try/catch expression interested in being notified of this error; if there is none, the error is thrown as an exception
      Parameters:
        `error` - the exception representing the dynamic error
      Throws:
        `XPathException` - if there is no try/catch expression wanting to catch this error

    - #### hasFailed

          public boolean hasFailed()