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
SaplingElementis 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, usingtoXdmNode(Processor)ortoNodeInfo(Configuration).
-
-
Constructor Summary
Constructors Constructor Description SaplingElement(java.lang.String name)Create an empty element, in no namespaceSaplingElement(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 intgetNodeKind()Get the kind of node (document, element, text, comment, or processing instruction)protected voidsendTo(Receiver receiver)Send a sequence of events representing this node to a supplied ReceiverNodeInfotoNodeInfo(Configuration config)Convert the sapling element to a regular element node, returning theNodeInfoobject representing the parentless element node at the root of the resulting treeXdmNodetoXdmNode(Processor processor)Convert the sapling element to a regular element node, returning theXdmNodeobject representing the parentless element node at the root of the resulting treeSaplingElementwithAttr(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 attributesSaplingElementwithAttr(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 attributesSaplingElementwithChild(SaplingNode... children)Add a number of child nodes to a document node, returning a new document node with additional children beyond those already present.SaplingElementwithNamespace(java.lang.String prefix, java.lang.String uri)Add a namespace binding for a prefix/URI pair.SaplingElementwithText(java.lang.String value)Add a text node as a child to this element, returning a new sapling element node.
-
-
-
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:SaplingNodeGet the kind of node (document, element, text, comment, or processing instruction)- Specified by:
getNodeKindin classSaplingNode- Returns:
- the kind of node, for example
Type.ELEMENTfor 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 toe.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 QNamevalue- 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 notjava.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 notjava.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:SaplingNodeSend a sequence of events representing this node to a supplied Receiver- Specified by:
sendToin classSaplingNode- 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 theNodeInfoobject 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 theXdmNodeobject 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
-
-