Package com.saxonica.ee.stream.feed

## Class AbsorptionFeed

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

- All Implemented Interfaces:
    `javax.xml.transform.Result`, `Receiver`
  Direct Known Subclasses:
    `CopyOfFeed`, `SimpleContentFeed`, `SnapshotFeed`, `StringValueFeed`, `TypedValueFeed`

      public abstract class AbsorptionFeed
      extends GroundedItemFeed

  This class is used as an abstract superclass for expressions where the consuming operand is absorbed by the expression: for example, data(), string(), or copy-of(). It handles the fact that the input can be crawling, which means that selected nodes can be nested. We therefore need to be collecting the result values of multiple nodes during the same pass of the input. Hence we maintain a stack of values-under-construction. Moreover, an inner value will be available before the outer value, but it follows the outer value in document order, so it needs to be held pending until the outer value is available. Hence we maintain a list of values that are ready to be output.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `static class` | `AbsorptionFeed.PendingItem` | A pending item represents a tree under construction.

  - ### 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
    --- | ---
    `AbsorptionFeed​(ItemFeed result, XPathContext context)` |

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `append​(Item item)` | Signal that a node (other than an element) that matches the selection has been found.
    `void` | `endSelectedParentNode​(Location locationId)` | Signal that the endElement event has occurred for the element whose startElement event caused the Watch to be activated.
    `protected abstract AbsorptionFeed.PendingItem` | `makePendingItem​(int sequenceNr, FleetingParentNode node)` | Create a pending item (appropriate to the subclass) containing the data needed to compute the result value for one node in the streamed input sequence
    `protected abstract Sequence` | `processGroundedItem​(Item item)` | Process a grounded item in the input sequence: either a streamed leaf node such as an attribute or text node, or an atomic value, or a non-streamed element or document node injected into the sequence for example by use of the comma operator.
    `void` | `setHasFailed()` | Mark this feed as having failed (that is, as having detected and reported a dynamic error).
    `Receiver` | `startSelectedParentNode​(FleetingParentNode node, Location locationId)` | Signal that an element has been found that matches the selection that this Watch is looking for.

    - ### Methods inherited from class com.saxonica.ee.stream.feed.GroundedItemFeed

      `attribute, characters, comment, endDocument, endElement, namespace, processingInstruction, setUnparsedEntity, startContent, startDocument, startElement, startElement`

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

      `append, close, dynamicError, getContext, getExpression, getResult, getTerminator, hasFailed, open, processItems, setExpression, setTerminator`

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

      `getNextOutputter, open, setLocation, 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

    - #### AbsorptionFeed

          public AbsorptionFeed​(ItemFeed result,
                                XPathContext context)

  - ### Method Detail

    - #### startSelectedParentNode

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

      Signal that an element has been found that matches the selection that this Watch is looking for.
      Overrides:
        `startSelectedParentNode` in class `ItemFeed`
      Parameters:
        `node` - the node that matches the selection
        `locationId` -
      Returns:
        a receiver that collects the contents of the selected node
      Throws:
        `ValidationException`
        `XPathException` - May be raised if a dynamic error occurs

    - #### makePendingItem

          protected abstract AbsorptionFeed.PendingItem makePendingItem​(int sequenceNr,
                                                                        FleetingParentNode node)
                                                                 throws XPathException

      Create a pending item (appropriate to the subclass) containing the data needed to compute the result value for one node in the streamed input sequence
      Parameters:
        `sequenceNr` - the sequence number of this node within a set of nested nodes
        `node` - the streamed input node
      Returns:
        the data needed to process this node
      Throws:
        `XPathException` - if a dynamic error is detected at this stage

    - #### endSelectedParentNode

          public final 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.
      Overrides:
        `endSelectedParentNode` in class `ItemFeed`
      Parameters:
        `locationId` - the location of the node in the source, or of the instruction that created it
      Throws:
        `XPathException` - if a dynamic error occurs

    - #### append

          public void append​(Item item)
                      throws XPathException

      Signal that a node (other than an element) that matches the selection has been found. This may be a leaf node in the streamed input, or it may be a grounded node or atomic value (of any kind) that has been mixed into the input sequence for example using a comma operator.
      Specified by:
        `append` in interface `Receiver`
      Specified by:
        `append` in class `ItemFeed`
      Parameters:
        `item` - the node or other item that was matched.
      Throws:
        `XPathException` - if the operation fails

    - #### processGroundedItem

          protected abstract Sequence processGroundedItem​(Item item)
                                                   throws XPathException

      Process a grounded item in the input sequence: either a streamed leaf node such as an attribute or text node, or an atomic value, or a non-streamed element or document node injected into the sequence for example by use of the comma operator.
      Parameters:
        `item` - the grounded item
      Returns:
        the result of processing the grounded item
      Throws:
        `XPathException` - if a dynamic error occurs

    - #### setHasFailed

          public void setHasFailed()

      Description copied from class: `ItemFeed`
      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.
      Overrides:
        `setHasFailed` in class `ItemFeed`