Package net.sf.saxon.sapling

Class 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
      void deliver​(Receiver receiver, ParseOptions options)
      Send a sequence of events representing this node to a supplied Receiver
      int getNodeKind()
      Get the kind of node (document, element, text, comment, or processing instruction)
      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.

      • deliver

        public void deliver​(Receiver receiver,
                    ParseOptions options)
             throws XPathException
        Description copied from class: SaplingNode
        Send a sequence of events representing this node to a supplied Receiver
        Specified by:
        deliver in class SaplingNode
        Parameters:
        receiver - the receiver to which the events are to be sent
        options - parse options (currently ignored)
        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