net.sf.saxon.s9api

Interface Push.Element

All Superinterfaces:

Push.Container

Enclosing interface:

Push

public static interface Push.Element
extends Push.Container

A Push.Container representing an element node.

The permitted sequence of events for an element node is (ATTRIBUTE | NAMESPACE)* (COMMENT | PI | TEXT | ELEMENT)* CLOSE?.

The methods for events other than child elements return the element container to while they are applied, so methods can be chained: for example element("foo").attribute("bar", "1").text("baz").close() generates the XML content <foo bar="1">baz</foo>

Closing an element is optional; it is automatically closed when another event is applied to its parent container, or when the parent container is closed.

Method Summary

Modifier and Type	Method and Description
Push.Element	attribute(QName name, java.lang.String value) Add an attribute to the current element, supplying its name as a QName.
Push.Element	attribute(java.lang.String name, java.lang.String value) Add an attribute to the current element, supplying its name as a string.
Push.Element	comment(java.lang.CharSequence value) Add a comment node to the current element or document node.
Push.Element	namespace(java.lang.String prefix, java.lang.String uri) Add an namespace binding to the current element.
Push.Element	processingInstruction(java.lang.String name, java.lang.CharSequence value) Add a processing instruction node to the current element or document node.
Push.Element	text(java.lang.CharSequence value) Add text content to the current element node (or, in the case of a non-well-formed document, as a child of the document node).

Methods inherited from interface net.sf.saxon.s9api.Push.Container

close, element, element, setDefaultNamespace

Method Detail

attribute

Push.Element attribute(QName name,
                       java.lang.String value)
                throws SaxonApiException

Add an attribute to the current element, supplying its name as a QName.

The level of validation applied to the supplied names is implementation-defined.

This method call is allowed in state START_TAG, and it leaves the state unchanged.

Parameters:

name - The name of the attribute, as a QName (which may contain prefix, namespace URI, and local name). The prefix and namespace URI must either both be empty, or both be non-empty.

A namespace declaration binding the prefix to the namespace URI will be generated unless it is redundant. An exception is thrown if the binding is incompatible with other bindings already established for the same prefix.

value - The value of the attribute. If the value is null, then no attribute is written.

Returns:

the Tag to which the method is applied. This is to allow chained method calls, of the form tag.element("a").attribute("x", "1").attribute("y", "2")

Throws:

SaxonApiException - if the specified constraints are violated, or if the implementation detects any problems

attribute

Push.Element attribute(java.lang.String name,
                       java.lang.String value)
                throws SaxonApiException

Add an attribute to the current element, supplying its name as a string.

The level of validation applied to the supplied name is implementation-defined.

This method call is allowed in state START_TAG, and it leaves the state unchanged.

Parameters:

name - The name of the attribute, as a string. The attribute will be in no namespace.

value - The value of the attribute. If the value is null, then no attribute is written.

Returns:

the Tag to which the method is applied. This is to allow chained method calls, of the form tag.element("a").attribute("x", "1").attribute("y", "2")

Throws:

SaxonApiException - if the specified constraints are violated, or if the implementation detects any problems

namespace

Push.Element namespace(java.lang.String prefix,
                       java.lang.String uri)
                throws SaxonApiException

Add an namespace binding to the current element.

It is never necessary to use this call to establish bindings for prefixes used in element or attribute names; it is needed only when there is a requirement to declare a namespace for use in other contexts, for example in the value of an xsi:type attribute.

This method is not used to declare a default namespace; that is done using Push.Container.setDefaultNamespace(String).

The level of validation applied to the supplied names is implementation-defined.

This method call is allowed in state START_TAG, and it leaves the state unchanged.

An exception is thrown if the binding is incompatible with other bindings already established on the current element for the same prefix, including any binding established using Push.Container.setDefaultNamespace(String)

Parameters:

prefix - The namespace prefix. This must not be a zero-length string.

uri - The namespace URI. This must not be a zero-length string.

Returns:

the Tag to which the method is applied. This is to allow chained method calls, of the form tag.element("a").namespace("xs", XS_SCHEMA).attribute("type", "xs:string")

Throws:

SaxonApiException - if the specified constraints are violated, or if the implementation detects any problems

text

Push.Element text(java.lang.CharSequence value)
           throws SaxonApiException

Description copied from interface: Push.Container

Add text content to the current element node (or, in the case of a non-well-formed document, as a child of the document node).

Multiple consecutive calls on text() generate a single text node with concatenated content: that is, text("one).text("two") is equivalent to text("onetwo").

Specified by:

text in interface Push.Container

Parameters:

value - the content of the text node. Supplying a zero-length string or null is permitted, but has no effect.

Returns:

the Container to which the method is applied. This is to allow chained method calls, of the form tag.element("a").text("content").close()

Throws:

SaxonApiException - if the specified constraints are violated, or if the implementation detects any problems

comment

Push.Element comment(java.lang.CharSequence value)
              throws SaxonApiException

Description copied from interface: Push.Container

Add a comment node to the current element or document node.

The method call is allowed in states START_TAG, CONTENT, and NON_TEXT_CONTENT, and it sets the state to CONTENT.

Specified by:

comment in interface Push.Container

Parameters:

value - the content of the comment node. The value should not contain the string "--"; it is implementation-defined whether this causes an exception, or whether some recovery action is taken such as replacing the string by "- -". If the value is null, no comment node is written.

Returns:

the Container to which the method is applied. This is to allow chained method calls, of the form tag.element("a").comment("optional").close()

Throws:

SaxonApiException - if the specified constraints are violated, or if the implementation detects any problems

processingInstruction

Push.Element processingInstruction(java.lang.String name,
                                   java.lang.CharSequence value)
                            throws SaxonApiException

Description copied from interface: Push.Container

Add a processing instruction node to the current element or document node.

The method call is allowed in states START_TAG, CONTENT, and NON_TEXT_CONTENT, and it sets the state to CONTENT.

Specified by:

processingInstruction in interface Push.Container

Parameters:

name - the name ("target") of the processing instruction. The level of validation applied to the supplied name is implementation-defined. Must not be null.

value - the content ("data") of the processing instruction node. The value should not contain the string "?>"; it is implementation-defined whether this causes an exception, or whether some recovery action is taken such as replacing the string by "? >". If the value is null, no processing instruction node is written.

Returns:

the Container to which the method is applied. This is to allow chained method calls, of the form tag.element("a").processing-instruction("target", "data").close()

Throws:

SaxonApiException - if the specified constraints are violated, or if the implementation detects any problems