net.sf.saxon.s9api

## Interface Destination

- All Known Implementing Classes:
    DOMDestination, SAXDestination, SchemaValidator, Serializer, TeeDestination, XdmDestination, XMLStreamWriterDestination, XQueryEvaluator, XsltTransformer

      public interface Destination

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

  In general a `Destination` is designed to hold a single document. It should therefore not be used as the destination of a query that produces multiple documents. The effect of sending multiple documents to a `Destination` depends on the kind of `Destination`.

  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`, however, 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.Configuration)`, which returns an instance of `Receiver`, 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. The `close()` method is called by the system when it finishes writing the document, and this causes all resources held by the Destination to be released.

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `close()` Close the destination, allowing resources to be released.
    `Receiver` | `getReceiver(Configuration config)` Return a Receiver.

- - ### Method Detail

    - #### getReceiver

          Receiver getReceiver(Configuration config)
                               throws SaxonApiException

      Return a Receiver. Saxon calls this method to obtain a Receiver, to which it then sends a sequence of events representing the content of an XML document. The method is intended primarily for internal use, and may give poor diagnostics if used incorrectly.
      Parameters:
        `config` - The Saxon 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.
      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 caller is also responsible for ensuring that the sequence of events sent to the Receiver represents a well-formed document: in particular the event stream must include namespace events corresponding exactly to the namespace declarations that are required. If the calling code cannot guarantee this, it should insert a `NamespaceReducer` into the pipeline in front of the returned Receiver.
      Throws:
        `SaxonApiException` - if the Receiver cannot be created

    - #### 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.

      Throws:
        `SaxonApiException` - if any failure occurs

Copyright (c) 2004-2013 Saxonica Limited. All rights reserved.