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 and Description
SaplingElement(QName name) Create an empty element, with a name supplied as a QName.
SaplingElement(java.lang.String name) Create an empty element, in no namespace

Method Summary

Modifier and Type	Method and 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(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	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	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