Package net.sf.saxon.s9api

## Interface Destination

- All Known Implementing Classes:
    `AbstractDestination`, `DOMDestination`, `NullDestination`, `RawDestination`, `ReceivingDestination`, `SAXDestination`, `SchemaValidator`, `SchemaValidatorImpl`, `Serializer`, `TeeDestination`, `XdmDestination`, `XMLStreamWriterDestination`, `XQueryEvaluator`, `XsltTransformer`

      public interface Destination

  A `Destination` represents a place where XDM values can be sent. It is used, for example, to define the output of a transformation or query.

  A `Destination` is either a tree destination or a raw destination. A tree destination performs sequence normalization on the stream of events passed to it, to construct a tree rooted at a single XDM document node, as defined in the W3C serialization specification (even if the destination is not actually a serializer). A raw destination omits this step. Examples of tree destinations are those designed to accept XML: `DOMDestination`, `SAXDestination`, `XdmDestination`, `SchemaValidator`.

  The `Serializer` acts as a tree destination when the output methods XML, HTML, XHTML, or TEXT are used, but as a raw destination when the output method is JSON or ADAPTIVE.

  The interface `Destination` has some similarities with the JAXP `Result` class. It differs, however, in that implementations of this interface can be written by users or third parties to define new kinds of destination, and any such implementation can be supplied to the Saxon methods that take a `Destination` as an argument.

  Implementing a new `Destination` will generally require access to implementation-level classes and methods within the Saxon product. The only method that needs to be supplied is `getReceiver(net.sf.saxon.event.PipelineConfiguration, net.sf.saxon.serialize.SerializationProperties)`, which returns an instance of `Outputter`, and unless you use an existing implementation of `Receiver`, you will need to handle internal Saxon concepts such as name codes and name pools.

  In general a Destination is not thread-safe (cannot be used from more than one thread), and is not serially reusable. So a Destination should only be used once. A Destination supplied to Saxon may be modified by Saxon.

  The `close()` method is called by the system when it finishes writing the document, and this should cause all resources held by the Destination to be released.

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `close()` | Close the destination, allowing resources to be released.
    `void` | `closeAndNotify()` | Close the destination and notify all registered listeners that it has been closed.
    `java.net.URI` | `getDestinationBaseURI()` | Get the base URI of the resource being written to this destination
    `Receiver` | `getReceiver​(PipelineConfiguration pipe, SerializationProperties params)` | Return a `Receiver`.
    `void` | `onClose​(Action listener)` | Register a listener to be notified when a `Outputter` linked to this destination is closed.
    `void` | `setDestinationBaseURI​(java.net.URI baseURI)` | Set the base URI of the resource being written to this destination

- - ### Method Detail

    - #### setDestinationBaseURI

          void setDestinationBaseURI​(java.net.URI baseURI)

      Set the base URI of the resource being written to this destination
      Parameters:
        `baseURI` - the base URI to be used

    - #### getDestinationBaseURI

          java.net.URI getDestinationBaseURI()

      Get the base URI of the resource being written to this destination
      Returns:
        the baseURI, or null if none is known

    - #### getReceiver

          Receiver getReceiver​(PipelineConfiguration pipe,
                               SerializationProperties params)
                        throws SaxonApiException

      Return a `Receiver`. Saxon calls this method to obtain a Receiver, to which it then sends a sequence of events representing an XDM value. The method is intended primarily for internal use, and may give poor diagnostics if used incorrectly.

      This method is normally only called once. However, in the case where a stylesheet includes a call of `xsl:result-document` with no `href` attribute (or with an `href` attribute that resolves to the base output URI of the transformation), the method may be called a second time (with a potentially different set of serialization parameters, and perhaps a different validation request) to return a second `Outputter`, which will typically write to the same destination. The XSLT rules ensure that it is not possible to write principal and secondary output to the same destination, so only one of these Receivers will actually be used.

      Parameters:
        `pipe` - The pipeline configuration. This is supplied so that the destination can use information from the configuration (for example, a reference to the name pool) to construct or configure the returned Receiver.
        `params` - Serialization parameters known to the caller of the method; typically, output properties defined in a stylesheet or query. These will mainly be of interest if the destination is performing serialization, but some properties (such as `item-separator`) are also used in other situations. These properties are typically subordinate to any properties defined on the (serializer) destination itself: for example if `indent=yes` was explicitly specified on a `Serializer`, this takes precedence over `indent=no` defined in a query or stylesheet.

        The `SerializationProperties` object may also contain a factory object for generating a validator to add to the output pipeline. The `Destination` object is responsible for instantiating this validator and inserting it into the pipeline. In most cases this is done by invoking the helper method `SerializationProperties.makeSequenceNormalizer(Receiver)`. Validation can be skipped in the case of non-XML destinations.

      Returns:
        the Receiver to which events are to be sent.

        It is the caller's responsibility to initialize this Receiver with a `PipelineConfiguration` before calling its `open()` method.

        The `Receiver` is expected to handle a regular event sequence as defined in `RegularSequenceChecker`. It is the caller's responsibility to ensure that the sequence of calls to the `Receiver` satisfies these rules, and it is the responsibility of the implementation to accept any sequence conforming these rules; the implementation is not expected to check that the sequence is valid, but it can do so if it wishes by inserting a `RegularSequenceChecker` into the pipeline.

        The sequence of events passed to the `Receiver` represents the raw results of the query or transformation. If the `Destination` is to perform sequence normalization, this is typically done by returning a `SequenceNormalizer` as the result of this method.

        The returned `Receiver` is responsible for ensuring that when its `Outputter.close()` method is called, this results in all registered `onClose` actions being invoked. An implementation returning a `SequenceNormalizer` can achieve this by registering the actions with the `SequenceNormalizer.onClose(java.util.List<net.sf.saxon.s9api.Action>)` method.

        Only a single call on this method will be made during the lifetime of the `Destination` object, with the exception of the case noted above where a secondary result document is written to the same destination as the principal transformation result.

      Throws:
        `SaxonApiException` - if the Receiver cannot be created

    - #### onClose

          void onClose​(Action listener)

      Register a listener to be notified when a `Outputter` linked to this destination is closed.

      Example: `destination.onClose(() -> System.out.println("Finished writing to " + uri)`

      The method must be called before the call on `getReceiver(PipelineConfiguration, SerializationProperties)`; the effect of calling it after getting a `Receiver`, but before closing the `Outputter`, is undefined.

      Parameters:
        `listener` - an object to be notified when writing to the destination is successfully completed

    - #### closeAndNotify

          void closeAndNotify()
                       throws SaxonApiException

      Close the destination and notify all registered listeners that it has been closed. This method is intended for internal use by Saxon. The method first calls `close()` to close the destination, then it calls `Consumer.accept(T)` on each of the listeners in turn to notify the fact that it has been closed.
      Throws:
        `SaxonApiException` - if the close() method throws `SaxonApiException`.

    - #### close

          void close()
              throws SaxonApiException

      Close the destination, allowing resources to be released. Saxon calls this method when it has finished writing to the destination.

      The `close()` method should not cause any adverse effects if it is called more than once. If any other method is called after the `close()` call, the results are undefined. This means that a Destination is not, in general, serially reusable.

      If an `onClose(net.sf.saxon.s9api.Action)` action has been associated with the destination, this will be called after the destination is closed.

      Throws:
        `SaxonApiException` - if any failure occurs