Package net.sf.saxon.sapling

## Class SaplingElement

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

-     public class SaplingElement
      extends SaplingNode

  An element node on a sapling tree. The node has the following properties:
  - A name. This is a QName, potentially containing a prefix, URI, and local-name.
  - An ordered list of children. The children may be elements, text nodes, comments, or processing instructions.
  - A set of attributes. An attribute has a name (which is a QName), and a string value; attribute names must be distinct. The prefix and URI of an attribute must either both be empty or both non-empty. Attributes in this model are not nodes, they are simply properties of an element node. Attributes for an element are unordered.
  - A set of namespace bindings (prefix/URI pairs, where the prefix may be empty, and the URI may be empty if and only if the prefix is empty). The namespace bindings implicitly include the prefix/URI combination for the element name, and the prefix/URI combinations for all attributes. They may also include additional namespace bindings. As far as the sapling tree is concerned, namespace bindings are not inherited from parent nodes; each element must contain all the namespace bindings that it needs. When a sapling tree is converted to a full tree, however, namespace bindings on a parent node will propagate to its children.

  Like all sapling nodes, a `SaplingElement` is immutable. All operations such as adding children or attributes deliver a new element 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)`.

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `SaplingElement​(java.lang.String name)` | Create an empty element, in no namespace
    `SaplingElement​(QName name)` | Create an empty element, with a name supplied as a QName.

  - ### 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)
    `protected void` | `sendTo​(Receiver receiver)` | Send a sequence of events representing this node to a supplied Receiver
    `NodeInfo` | `toNodeInfo​(Configuration config)` | Convert the sapling element to a regular element node, returning the `NodeInfo` object representing the parentless element node at the root of the resulting tree
    `XdmNode` | `toXdmNode​(Processor processor)` | Convert the sapling element to a regular element node, returning the `XdmNode` object representing the parentless element node at the root of the resulting tree
    `SaplingElement` | `withAttr​(java.lang.String name, java.lang.String value)` | Add or replace an attribute of the element node, returning a new element node with a modified set of attributes
    `SaplingElement` | `withAttr​(QName name, java.lang.String value)` | Add or replace an attribute of the element node, returning a new element node with a modified set of attributes
    `SaplingElement` | `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.
    `SaplingElement` | `withNamespace​(java.lang.String prefix, java.lang.String uri)` | Add a namespace binding for a prefix/URI pair.
    `SaplingElement` | `withText​(java.lang.String value)` | Add a text node as a child to this element, returning a new sapling element node.

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

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

- - ### Constructor Detail

    - #### SaplingElement

          public SaplingElement​(java.lang.String name)

      Create an empty element, in no namespace
      Parameters:
        `name` - the name of the element. This should take the form of an NCName, but the current implementation does not check this.

    - #### SaplingElement

          public SaplingElement​(QName name)

      Create an empty element, with a name supplied as a QName.
      Parameters:
        `name` - the name of the element, as a QName. If the prefix of the QName is non-empty, then the URI part must also be non-empty.
      Throws:
        `java.lang.IllegalArgumentException` - if the name contains a prefix but no URI

  - ### Method Detail

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

      Note: because adding a child always creates a new parent element, it is impossible to create cycles by adding a node to itself, directly or indirectly.

      Parameters:
        `children` - The nodes to be added as children. The supplied nodes are added in order after any existing children.
      Returns:
        the new parent element node
      Throws:
        `java.lang.IllegalArgumentException` - if any of the nodes supplied as an argument is a document node.

    - #### withText

          public SaplingElement withText​(java.lang.String value)

      Add a text node as a child to this element, returning a new sapling element node. This is a convenience method: `e.withText("value")` is equavalent to `e.withChild(text("value"))`
      Parameters:
        `value` - the string value of a new text node, which will be added as a child to this element after any existing children
      Returns:
        a new element node, identical to this element but with the new text node as an additional child

    - #### withAttr

          public SaplingElement withAttr​(java.lang.String name,
                                         java.lang.String value)

      Add or replace an attribute of the element node, returning a new element node with a modified set of attributes
      Parameters:
        `name` - the name of the attribute to be added or replaced; this represents the local part of a no-namespace QName. The name must be in the form of an NCName, but the current implementation does not check this.
        `value` - the (new) value of the attribute
      Returns:
        a new sapling element node, identical to the target node except for the added or replaced attribute

    - #### withAttr

          public SaplingElement withAttr​(QName name,
                                         java.lang.String value)

      Add or replace an attribute of the element node, returning a new element node with a modified set of attributes
      Parameters:
        `name` - the name of the attribute to be added or replaced, as a QName
        `value` - the (new) value of the attribute
      Returns:
        a new sapling element node, identical to the target node except for the added or replaced attribute
      Throws:
        `java.lang.IllegalArgumentException` - if the prefix of the attribute name is empty and the URI is not, or if the URI is empty and the prefix is not
        `java.lang.IllegalStateException` - if the prefix/uri binding is incompatible with the existing prefix/uri bindings on the element

    - #### withNamespace

          public SaplingElement withNamespace​(java.lang.String prefix,
                                              java.lang.String uri)

      Add a namespace binding for a prefix/URI pair. Namespace bindings are added automatically for prefixes used in element and attribute names; they only need to be added explicitly if the binding is additional to those in element and attribute names. A namespace binding for the XML namespace is implicitly present on every element.
      Parameters:
        `prefix` - the namespace prefix. This must either be a zero length string, or it must take the form of an NCName, but this constraint is not currently enforced.
        `uri` - the namespace URI. If this is the empty string, then (a) if the prefix is empty, the namespace binding is ignored; (b) otherwise, an exception is raised (namespace undeclarations are not permitted).
      Returns:
        a new element node, identical to the original except for the additional namespace binding
      Throws:
        `java.lang.IllegalArgumentException` - if the URI is empty and the prefix is not
        `java.lang.IllegalStateException` - if the element already has a namespace binding for this prefix, with a different URI.

    - #### sendTo

          protected 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 element to a regular element node, returning the `NodeInfo` object representing the parentless element node at the root of the resulting tree
      Parameters:
        `config` - the Saxon Configuration
      Returns:
        the parentless element 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 element to a regular element node, returning the `XdmNode` object representing the parentless element node at the root of the resulting tree
      Parameters:
        `processor` - the s9api Processor object that is to own the resulting tree
      Returns:
        the element 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