Package net.sf.saxon.event

## Interface Receiver

- All Superinterfaces:
    `javax.xml.transform.Result`
  All Known Subinterfaces:
    `ReceiverWithOutputProperties`
  All Known Implementing Classes:
    `AbsorptionFeed`, `AbstractReceiver`, `AdaptiveEmitter`, `AllElementValidator`, `AnyTypeValidator`, `ApplyImportsAction`, `ApplyTemplatesAction`, `ApplyTemplatesFeed`, `AssertionTreeBuilder`, `AtomicItemFeed`, `AttributeInheritor`, `AttributeSorter`, `AttributeValidator`, `AxiomWriter`, `Base64BinaryEmitter`, `BinaryEmitter`, `BinaryTextDecoder`, `BooleanFnFeed`, `BooleanFnFeed.Negative`, `BooleanFnFeed.Positive`, `BufferingApplyTemplatesFeed`, `BufferingFeed`, `BufferingFilterExpressionFeed`, `BufferingForEachExpressionFeed`, `Builder`, `BuilderMonitor`, `CallableFeed`, `CardinalityCheckingFeed`, `CatchingReceiver`, `CDATAFilter`, `CharacterMapExpander`, `CheckSumFilter`, `CloseNotifier`, `CommentStripper`, `ComplexContentOutputter`, `ComplexContentValidator`, `ComplexNodeEventFeed`, `ConditionalBlockAdjunct.ConditionalBlockFeed`, `ConstraintChecker`, `ContentDetector`, `ContentHandlerProxy`, `ContentValidator`, `CopyOfFeed`, `CopyOfFeed.AccumulatorCopier`, `CountingFilter`, `DecomposingFeed`, `DelegatingFeed`, `DocumentInstrAdjunct.DocumentInstrFeed`, `DocumentValidator`, `DOM4JWriter`, `DominoTreeModel.DominoBuilder`, `DOMWriter`, `ElementCreatorFeed`, `Emitter`, `EmptyContentValidator`, `EntityValidator`, `Erector`, `EvaluationNuisance`, `EventBuffer`, `EventMonitor`, `ExistenceFeed`, `ExpressionPresenterToJson`, `FeedToEventBuffer`, `FieldChecker`, `FilteringFeed`, `ForEachAction`, `ForEachGroupParallelAction`, `ForEachGroupPartitionAction`, `ForExpressionAdjunct.ForExpressionFeed`, `GeneralComparisonFeed`, `GroundedItemFeed`, `HexBinaryEmitter`, `HTML40Emitter`, `HTML50Emitter`, `HTMLEmitter`, `HTMLIndenter`, `HTMLIndenterPE`, `HTMLURIEscaper`, `IDFilter`, `IdValidator`, `IgnorableWhitespaceStripper`, `ItemCheckingFeed`, `ItemFeed`, `ItemMappingFeed`, `IterateAction`, `JDOM2Writer`, `JsonReceiver`, `JSONSerializer`, `LaxValidator`, `LinkedBuilderMonitor`, `LinkedTreeBuilder`, `LiteralAdjunct.LiteralItemFeed`, `MessageEmitter`, `MessageWarner`, `MetaTagAdjuster`, `MotionlessFeed`, `NamePoolConverter`, `NamespaceDifferencer`, `NamespaceReducer`, `NextIterationFeed`, `NextMatchAction`, `NoCloseFeed`, `NoOpenFeed`, `NoOpenOrCloseFeed`, `OuterNewlineInserter`, `Outputter`, `OutputterEventBuffer`, `PackageInspector`, `PathMaintainer`, `PIGrabber`, `PrincipalOutputGatekeeper`, `Projector`, `ProxyOutputter`, `ProxyReceiver`, `ReceiverToXMLStreamWriter`, `RegularSequenceChecker`, `ResultDocumentAdjunct.ResultDocumentFeed`, `SchemaModelLoader`, `SequenceCollector`, `SequenceNormalizer`, `SequenceNormalizerWithItemSeparator`, `SequenceNormalizerWithSpaceSeparator`, `SequenceReceiver`, `SequenceWrapper`, `SequenceWriter`, `ShallowCopyEventFeed`, `SignificantItemDetector`, `SimpleContentFeed`, `SimpleContentValidator`, `SimpleNodeConstructorFeed`, `Sink`, `SinkFeed`, `SinkOutputter`, `SkipValidator`, `SnapshotFeed`, `StreamingSequenceWriter`, `StringValueFeed`, `StringValueGatherer`, `Stripper`, `TeeOutputter`, `TEXTEmitter`, `TinyBuilder`, `TinyBuilderCondensed`, `TinyBuilderMonitor`, `TracingFilter`, `TransformerReceiver`, `TreeReceiver`, `TryCatchAdjunct.TryCatchFeed`, `TypeCheckingFilter`, `TypedContentHandler`, `TypedValueFeed`, `UncommittedSerializer`, `UnicodeNormalizer`, `UseWhenFilter`, `ValidatingFilter`, `ValidationStack`, `Valve`, `VersionControlFilter`, `WatchManager`, `WherePopulatedOutputter`, `XHTML1Emitter`, `XHTML5Emitter`, `XHTMLPrefixRemover`, `XHTMLURIEscaper`, `XML10ContentChecker`, `XMLEmitter`, `XMLIndenter`, `XMLIndenterPE`, `XOMWriter`, `XQueryEmitter`, `XSIAttributeHandler`

      public interface Receiver
      extends javax.xml.transform.Result

  Receiver: This interface represents a recipient of XML tree-walking (push) events. It is based on SAX2's ContentHandler, but adapted to handle additional events. Namespaces and Attributes are handled by separate events following the startElement event. Schema types can be defined for elements and attributes.

  The Receiver interface is an important internal interface within Saxon, and provides a powerful mechanism for integrating Saxon with other applications. It has been designed with extensibility and stability in mind. However, it should be considered as an interface designed primarily for internal use, and not as a completely stable part of the public Saxon API.

  Since:
    8.0. Extended in 9.9 to support additional methods with default implementations. Changed in 10.0 to accept all the attributes and namespaces as part of the startElement event (thus eliminating the need for a separate startContent event).

- - ### Field Summary

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

      `PI_DISABLE_OUTPUT_ESCAPING, PI_ENABLE_OUTPUT_ESCAPING`

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `default void` | `append​(Item item)` | Append an arbitrary item (node, atomic value, or function) to the output.
    `default void` | `append​(Item item, Location locationId, int properties)` | Append an arbitrary item (node, atomic value, or function) to the output.
    `void` | `characters​(java.lang.CharSequence chars, Location location, int properties)` | Notify character data.
    `void` | `close()` | Notify the end of the event stream
    `void` | `comment​(java.lang.CharSequence content, Location location, int properties)` | Notify a comment.
    `void` | `endDocument()` | Notify the end of a document node
    `void` | `endElement()` | Notify the end of an element.
    `PipelineConfiguration` | `getPipelineConfiguration()` | Get the pipeline configuration
    `default boolean` | `handlesAppend()` | Ask whether this Receiver can handle arbitrary items in its `append(net.sf.saxon.om.Item, net.sf.saxon.s9api.Location, int)` and `append(Item, Location, int)` methods.
    `void` | `open()` | Notify the start of the event stream
    `void` | `processingInstruction​(java.lang.String name, java.lang.CharSequence data, Location location, int properties)` | Output a processing instruction
    `void` | `setPipelineConfiguration​(PipelineConfiguration pipe)` | Set the pipeline configuration
    `void` | `setSystemId​(java.lang.String systemId)` | Set the System ID of the tree represented by this event stream
    `void` | `setUnparsedEntity​(java.lang.String name, java.lang.String systemID, java.lang.String publicID)` | Notify an unparsed entity URI.
    `void` | `startDocument​(int properties)` | Notify the start of a document node
    `void` | `startElement​(NodeName elemName, SchemaType type, AttributeMap attributes, NamespaceMap namespaces, Location location, int properties)` | Notify the start of an element
    `default boolean` | `usesTypeAnnotations()` | Ask whether this Receiver (or the downstream pipeline) makes any use of the type annotations supplied on element and attribute events.

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

      `getSystemId`

- - ### Method Detail

    - #### setPipelineConfiguration

          void setPipelineConfiguration​(PipelineConfiguration pipe)

      Set the pipeline configuration
      Parameters:
        `pipe` - the pipeline configuration

    - #### getPipelineConfiguration

          PipelineConfiguration getPipelineConfiguration()

      Get the pipeline configuration
      Returns:
        the pipeline configuration

    - #### setSystemId

          void setSystemId​(java.lang.String systemId)

      Set the System ID of the tree represented by this event stream
      Specified by:
        `setSystemId` in interface `javax.xml.transform.Result`
      Parameters:
        `systemId` - the system ID (which is used as the base URI of the nodes if there is no xml:base attribute)

    - #### open

          void open()
             throws XPathException

      Notify the start of the event stream
      Throws:
        `XPathException` - if an error occurs

    - #### startDocument

          void startDocument​(int properties)
                      throws XPathException

      Notify the start of a document node
      Parameters:
        `properties` - bit-significant integer indicating properties of the document node. The definitions of the bits are in class `ReceiverOption`
      Throws:
        `XPathException` - if an error occurs

    - #### endDocument

          void endDocument()
                    throws XPathException

      Notify the end of a document node
      Throws:
        `XPathException` - if an error occurs

    - #### setUnparsedEntity

          void setUnparsedEntity​(java.lang.String name,
                                 java.lang.String systemID,
                                 java.lang.String publicID)
                          throws XPathException

      Notify an unparsed entity URI.
      Parameters:
        `name` - The name of the unparsed entity
        `systemID` - The system identifier of the unparsed entity
        `publicID` - The identifier of the unparsed entity
      Throws:
        `XPathException` - if an error occurs

    - #### startElement

          void startElement​(NodeName elemName,
                            SchemaType type,
                            AttributeMap attributes,
                            NamespaceMap namespaces,
                            Location location,
                            int properties)
                     throws XPathException

      Notify the start of an element
      Parameters:
        `elemName` - the name of the element.
        `type` - the type annotation of the element.
        `attributes` - the attributes of this element
        `namespaces` - the in-scope namespaces of this element: generally this is all the in-scope namespaces, without relying on inheriting namespaces from parent elements
        `location` - an object providing information about the module, line, and column where the node originated
        `properties` - bit-significant properties of the element node. If there are no relevant properties, zero is supplied. The definitions of the bits are in class `ReceiverOption`
      Throws:
        `XPathException` - if an error occurs

    - #### endElement

          void endElement()
                   throws XPathException

      Notify the end of an element. The receiver must maintain a stack if it needs to know which element is ending.
      Throws:
        `XPathException` - if an error occurs

    - #### characters

          void characters​(java.lang.CharSequence chars,
                          Location location,
                          int properties)
                   throws XPathException

      Notify character data. Note that some receivers may require the character data to be sent in a single event, but in general this is not a requirement.
      Parameters:
        `chars` - The characters
        `location` - provides information such as line number and system ID.
        `properties` - Bit significant value. The following bits are defined:
        DISABLE_ESCAPING
          Disable escaping for this text node
        USE_CDATA
          Output as a CDATA section
      Throws:
        `XPathException` - if an error occurs

    - #### processingInstruction

          void processingInstruction​(java.lang.String name,
                                     java.lang.CharSequence data,
                                     Location location,
                                     int properties)
                              throws XPathException

      Output a processing instruction
      Parameters:
        `name` - The PI name. This must be a legal name (it will not be checked).
        `data` - The data portion of the processing instruction
        `location` - provides information such as line number and system ID.
        `properties` - Additional information about the PI.
      Throws:
        `java.lang.IllegalArgumentException` - if the content is invalid for an XML processing instruction
        `XPathException` - if an error occurs

    - #### comment

          void comment​(java.lang.CharSequence content,
                       Location location,
                       int properties)
                throws XPathException

      Notify a comment. Comments are only notified if they are outside the DTD.
      Parameters:
        `content` - The content of the comment
        `location` - provides information such as line number and system ID.
        `properties` - Additional information about the comment.
      Throws:
        `java.lang.IllegalArgumentException` - if the content is invalid for an XML comment
        `XPathException` - if an error occurs

    - #### append

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

      Append an arbitrary item (node, atomic value, or function) to the output. The default implementation throws `UnsupportedOperationException`.
      Parameters:
        `item` - the item to be appended
        `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
        `java.lang.UnsupportedOperationException` - if this Receiver does not allow appending of items (at any time, or at this particular point in the sequence of events)

    - #### append

          default void append​(Item item)
                       throws XPathException

      Append an arbitrary item (node, atomic value, or function) to the output. By default, if the item is an element node, it is copied with all namespaces. The default implementation calls `append(Item, Location, int)`, whose default implementation throws `UnsupportedOperationException`
      Parameters:
        `item` - the item to be appended
      Throws:
        `XPathException` - if the operation fails

    - #### close

          void close()
              throws XPathException

      Notify the end of the event stream
      Throws:
        `XPathException` - if an error occurs

    - #### usesTypeAnnotations

          default boolean usesTypeAnnotations()

      Ask whether this Receiver (or the downstream pipeline) makes any use of the type annotations supplied on element and attribute events. The default implementation of this method returns false.
      Returns:
        true if the Receiver makes any use of this information. If false, the caller may supply untyped nodes instead of supplying the type annotation (or conversely, it may avoid stripping unwanted type annotations)

    - #### handlesAppend

          default boolean handlesAppend()

      Ask whether this Receiver can handle arbitrary items in its `append(net.sf.saxon.om.Item, net.sf.saxon.s9api.Location, int)` and `append(Item, Location, int)` methods. If it cannot, then calling these methods will raise an exception (typically but not necessarily an `UnsupportedOperationException`). The default implementation of this method returns false.
      Returns:
        true if the Receiver is able to handle items supplied to its `append(net.sf.saxon.om.Item, net.sf.saxon.s9api.Location, int)` and `append(Item, Location, int)` methods. A receiver that returns true may still reject some kinds of item, for example it may reject function items.