Package 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 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