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 Details

    • SaplingElement

      public SaplingElement(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:
      IllegalArgumentException - if the name contains a prefix but no URI

  • Method Details

    • 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:
      IllegalArgumentException - if any of the nodes supplied as an argument is a document node.

    • withText

      public SaplingElement withText(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(String name, 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, 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:
      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
      IllegalStateException - if the prefix/uri binding is incompatible with the existing prefix/uri bindings on the element

    • withNamespace

      public SaplingElement withNamespace(String prefix, 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:
      IllegalArgumentException - if the URI is empty and the prefix is not
      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