Package net.sf.saxon.s9api

## Class XdmDestination

- java.lang.Object
- - net.sf.saxon.s9api.AbstractDestination
  - - net.sf.saxon.s9api.XdmDestination

- All Implemented Interfaces:
    `Destination`

      public class XdmDestination
      extends AbstractDestination

  An `XdmDestination` is a `Destination` in which an `XdmNode` is constructed to hold the output of a query or transformation: that is, a tree using Saxon's implementation of the XDM data model

  No data needs to be supplied to the `XdmDestination` object. The query or transformation populates an `XdmNode`, which may then be retrieved using the `getXdmNode` method.

  An `XdmDestination` is designed to hold a single tree rooted at a document node. If the result of a query is an arbitrary sequence, it will be normalized according to the rules of the "sequence normalization" operation described in the W3C XSLT/XQuery Serialization Recommendation, which results in either a single document node, or an error.

  An XdmDestination can be reused to hold the results of a second query or transformation only if the `reset()` method is first called to reset its state.

  If an XDM tree is to be built from a lexical XML document, or programmatically from the application by writing a sequence of events, the recommended mechanism is to use a `DocumentBuilder` rather than this class.

  Since:
    9.1. Changed in 9.9 to perform sequence normalization, so the result is always a single document node. To get the raw results of a query or stylesheet without sequence normalization, use a `RawDestination`.

- - ### Field Summary

    - ### Fields inherited from class net.sf.saxon.s9api.AbstractDestination

      `helper`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `XdmDestination()` |

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `close()` | Close the destination, allowing resources to be released.
    `java.net.URI` | `getBaseURI()` | Get the base URI that will be used for the document node when the XdmDestination is written to.
    `Receiver` | `getReceiver​(PipelineConfiguration pipe, SerializationProperties params)` | Return a Receiver.
    `TreeModel` | `getTreeModel()` | Get the tree model to be used for documents constructed using this XdmDestination.
    `XdmNode` | `getXdmNode()` | Return the node at the root of the tree, after it has been constructed.
    `void` | `reset()` | Allow the `XdmDestination` to be reused, without resetting other properties of the destination.
    `void` | `setBaseURI​(java.net.URI baseURI)` | Set the base URI for the document node that will be created when the XdmDestination is written to.
    `void` | `setDestinationBaseURI​(java.net.URI baseURI)` | Set the base URI of the resource being written to this destination
    `void` | `setTreeModel​(TreeModel model)` | Set the tree model to be used for documents constructed using this XdmDestination.

    - ### Methods inherited from class net.sf.saxon.s9api.AbstractDestination

      `closeAndNotify, getDestinationBaseURI, onClose`

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

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

- - ### Constructor Detail

    - #### XdmDestination

          public XdmDestination()

  - ### Method Detail

    - #### setBaseURI

          public void setBaseURI​(java.net.URI baseURI)

      Set the base URI for the document node that will be created when the XdmDestination is written to. If used, this method must be called before writing to the destination; it has no effect on any XdmNode that has already been constructed.

      If no base URI is set, nodes written to this destination will typically take their base URI from the location of the event that created the node. For a node written by a query or stylesheet, this will typically be the static base URI of the instruction that created the node. For a node written by a schema validator, it will typically be the base URI of the node being validated in the source document.

      Parameters:
        `baseURI` - the base URI for the node that will be constructed when the XdmDestination is written to. This must be an absolute URI
      Throws:
        `java.lang.IllegalArgumentException` - if the baseURI supplied is not an absolute URI
      Since:
        9.1

    - #### setDestinationBaseURI

          public void setDestinationBaseURI​(java.net.URI baseURI)

      Description copied from class: `AbstractDestination`
      Set the base URI of the resource being written to this destination
      Specified by:
        `setDestinationBaseURI` in interface `Destination`
      Overrides:
        `setDestinationBaseURI` in class `AbstractDestination`
      Parameters:
        `baseURI` - the base URI to be used

    - #### getBaseURI

          public java.net.URI getBaseURI()

      Get the base URI that will be used for the document node when the XdmDestination is written to.
      Returns:
        the base URI that will be used for the node that is constructed when the XdmDestination is written to.
      Since:
        9.1

    - #### setTreeModel

          public void setTreeModel​(TreeModel model)

      Set the tree model to be used for documents constructed using this XdmDestination. By default, the TinyTree is used.
      Parameters:
        `model` - typically one of the constants `TreeModel.TINY_TREE`, `TreeModel.TINY_TREE_CONDENSED`, or `TreeModel.LINKED_TREE`. However, in principle a user-defined tree model can be used.
      Since:
        9.2

    - #### getTreeModel

          public TreeModel getTreeModel()

      Get the tree model to be used for documents constructed using this XdmDestination. By default, the TinyTree is used.
      Returns:
        the tree model in use: typically one of the constants `TreeModel.TINY_TREE`, `TreeModel.TINY_TREE_CONDENSED`, or `TreeModel.LINKED_TREE`. However, in principle a user-defined tree model can be used.
      Since:
        9.2

    - #### getReceiver

          public Receiver getReceiver​(PipelineConfiguration pipe,
                                      SerializationProperties params)

      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.
      Parameters:
        `pipe` - 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.
        `params` - The serialization properties requested. Largely irrelevant for this `Destination`, except perhaps for `item-separator`.
      Returns:
        the Receiver to which events are to be sent.

    - #### close

          public void close()

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

    - #### getXdmNode

          public XdmNode getXdmNode()

      Return the node at the root of the tree, after it has been constructed.

      This method should not be called while the tree is under construction.

      Returns:
        the root node of the tree (always a document or element node); or null if nothing is written to the tree (for example, the result of a query that returns the empty sequence)
      Throws:
        `java.lang.IllegalStateException` - if called during the execution of the process that is writing the tree.

    - #### reset

          public void reset()

      Allow the `XdmDestination` to be reused, without resetting other properties of the destination.