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 `&lt;foo bar="1"&gt;baz&lt;/foo&gt;`

  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

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `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` | `attribute​(QName name, java.lang.String value)` | Add an attribute to the current element, supplying its name as a QName.
    `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