Package net.sf.saxon.sapling

## Class SaplingDocument

- java.lang.Object
- - net.sf.saxon.sapling.SaplingNode
  - - net.sf.saxon.sapling.SaplingDocument

- All Implemented Interfaces:
    `javax.xml.transform.Source`

      public class SaplingDocument
      extends SaplingNode
      implements javax.xml.transform.Source

  A document node in a sapling tree. A document node may have a sequence of children, each of which is an element, text, comment, or processing-instruction node. A document node has an optional base URI.

  Like all sapling nodes, a `SaplingDocument` is immutable. All operations such as adding children deliver a new document node. A sapling node generally exists only transiently during tree construction; to make use of the constructed tree, it will usually be converted to a regular tree when construction is complete, using `toXdmNode(Processor)` or `toNodeInfo(Configuration)`.

  `SaplingDocument` implements `Source`, and a sapling document can therefore be supplied in most Saxon interfaces that expect a Source. However, third-party software that expects a `Source` as input is unlikely to recognize this class, unless explicitly stated to the contrary.

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `SaplingDocument()` | Create a sapling document node with no children and no base URI
    `SaplingDocument​(java.lang.String baseUri)` | Create a sapling document node with no children, having a specified base URI

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `int` | `getNodeKind()` | Get the kind of node (document, element, text, comment, or processing instruction)
    `java.lang.String` | `getSystemId()` | Get the system identifier.
    `void` | `send​(Processor processor, Destination destination)` | Send the document to an arbitrary destination
    `void` | `sendTo​(Receiver receiver)` | Send a sequence of events representing this node to a supplied Receiver
    `void` | `serialize​(Serializer serializer)` | Serialize the document
    `void` | `setSystemId​(java.lang.String systemId)` | Set the system identifier for this Source.
    `NodeInfo` | `toNodeInfo​(Configuration config)` | Convert the sapling document to a regular document, returning the `NodeInfo` object representing the document node of the resulting tree
    `XdmNode` | `toXdmNode​(Processor processor)` | Convert the sapling document to a regular document, returning the `XdmNode` object representing the document node of the resulting tree
    `SaplingDocument` | `withChild​(SaplingNode... children)` | Add a number of child nodes to a document node, returning a new document node with additional children beyond those already present.

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

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

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

      `isEmpty`

- - ### Constructor Detail

    - #### SaplingDocument

          public SaplingDocument()

      Create a sapling document node with no children and no base URI

    - #### SaplingDocument

          public SaplingDocument​(java.lang.String baseUri)

      Create a sapling document node with no children, having a specified base URI
      Parameters:
        `baseUri` - the base URI of the document node

  - ### Method Detail

    - #### setSystemId

          public void setSystemId​(java.lang.String systemId)

      Set the system identifier for this Source. This method is provided because it is needed to satisfy the `Source` interface; however it always throws an exception, because `SaplingDocument` is immutable.
      Specified by:
        `setSystemId` in interface `javax.xml.transform.Source`
      Parameters:
        `systemId` - The system identifier as a URL string.
      Throws:
        `java.lang.UnsupportedOperationException` - always

    - #### getSystemId

          public java.lang.String getSystemId()

      Get the system identifier. This implementation of the method returns the base URI.
      Specified by:
        `getSystemId` in interface `javax.xml.transform.Source`
      Returns:
        The base URI of the document.

    - #### getNodeKind

          public int getNodeKind()

      Description copied from class: `SaplingNode`
      Get the kind of node (document, element, text, comment, or processing instruction)
      Specified by:
        `getNodeKind` in class `SaplingNode`
      Returns:
        the kind of node, for example `Type.ELEMENT` for an element node.

    - #### withChild

          public SaplingDocument withChild​(SaplingNode... children)

      Add a number of child nodes to a document node, returning a new document node with additional children beyond those already present. The target document is not modified, neither are the added children.
      Parameters:
        `children` - The nodes to be added as children. The supplied nodes are added in order after any existing children.
      Returns:
        the new parent document node
      Throws:
        `java.lang.IllegalArgumentException` - if any of the nodes supplied as an argument is a document node.

    - #### sendTo

          public void sendTo​(Receiver receiver)
                      throws XPathException

      Description copied from class: `SaplingNode`
      Send a sequence of events representing this node to a supplied Receiver
      Specified by:
        `sendTo` in class `SaplingNode`
      Parameters:
        `receiver` - the receiver to which the events are to be sent
      Throws:
        `XPathException` - if the receiver throws an exception

    - #### toNodeInfo

          public NodeInfo toNodeInfo​(Configuration config)
                              throws XPathException

      Convert the sapling document to a regular document, returning the `NodeInfo` object representing the document node of the resulting tree
      Parameters:
        `config` - the Saxon Configuration
      Returns:
        the document node at the root of the constructed tree. The implementation model for the tree will be the default tree model of the Configuration
      Throws:
        `XPathException` - if construction fails; this could happen if constraints have been violated

    - #### toXdmNode

          public XdmNode toXdmNode​(Processor processor)
                            throws SaxonApiException

      Convert the sapling document to a regular document, returning the `XdmNode` object representing the document node of the resulting tree
      Parameters:
        `processor` - the s9api Processor object that is to own the resulting tree
      Returns:
        the document node at the root of the constructed tree. The implementation model for the tree will be the default tree model of the Processor's Configuration
      Throws:
        `SaxonApiException` - if construction fails; this could happen if constraints have been violated

    - #### serialize

          public void serialize​(Serializer serializer)
                         throws SaxonApiException

      Serialize the document
      Parameters:
        `serializer` - the serializer to be used; the serialized representation of the node will be written to the serializer's destination.
      Throws:
        `SaxonApiException` - if anything goes wrong

    - #### send

          public void send​(Processor processor,
                           Destination destination)
                    throws SaxonApiException

      Send the document to an arbitrary destination
      Parameters:
        `processor` - the s9api processor
        `destination` - the destination to which the document will be copied.
      Throws:
        `SaxonApiException` - if anything goes wrong