Package net.sf.saxon.s9api

## Interface Push.Container

- All Known Subinterfaces:
    `Push.Document`, `Push.Element`
  Enclosing interface:
    Push

      public static interface Push.Container

  The `Container` interface represents a document node or element node under construction; there are concrete subclasses representing document nodes and element nodes respectively.

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `close()` | Close the current document or element container.
    `Push.Container` | `comment​(java.lang.CharSequence value)` | Add a comment node to the current element or document node.
    `Push.Element` | `element​(java.lang.String name)` | Start an element node, with a specified local name.
    `Push.Element` | `element​(QName name)` | Start an element node, with a specified prefix, namespace URI, and local name.
    `Push.Container` | `processingInstruction​(java.lang.String name, java.lang.CharSequence value)` | Add a processing instruction node to the current element or document node.
    `void` | `setDefaultNamespace​(java.lang.String uri)` | Set the default namespace for a section of the document.
    `Push.Container` | `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).

- - ### Method Detail

    - #### setDefaultNamespace

          void setDefaultNamespace​(java.lang.String uri)

      Set the default namespace for a section of the document. This applies to all subsequent `element(String)` or #element(QName)} calls, and is inherited by inner elements unless overridden by another call that sets a different value.

      Setting the default namespace has the effect that within its scope, on any call on `element(String)`, the supplied string is taken as being a local name in the current default namespace. A default namespace declaration in the form `xmlns="uri"` will appear on any element where it is not redundant.

      If the method is called repeatedly on the same `Container`, then the most recent call applies.

      Parameters:
        `uri` - the namespace URI to be used as the default namespace for the subsequent elements. The value may be a zero-length string or null, indicating that the default within the scope of this call is for elements to be in no namespace.

    - #### element

          Push.Element element​(QName name)
                        throws SaxonApiException

      Start an element node, with a specified prefix, namespace URI, and local name.

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

      Parameters:
        `name` - The name of the element, as a non-null QName (which may contain prefix, namespace URI, and local name). An empty string as the prefix represents the default namespace; an empty string as the namespace URI represents no namespace. If the namespace is empty then the prefix must also be empty.

        A namespace declaration binding the prefix to the namespace URI will be generated unless it is redundant.

        If the prefix is empty and the namespace is not the default namespace established using `setDefaultNamespace(String)`, then the prefix will be substituted with a system-allocated prefix. The prefix and namespace URI used on this method call do not affect the namespace context for any elements other than this one.

      Returns:
        a new `Tag` representing the new element node
      Throws:
        `SaxonApiException` - if the specified constraints are violated, or if the implementation detects any problems

    - #### element

          Push.Element element​(java.lang.String name)
                        throws SaxonApiException

      Start an element node, with a specified local name. The element will be in the default namespace if one has been established; otherwise it will be in no namespace.

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

      Parameters:
        `name` - The local name of the element, as a non-null string. If a default namespace has been established by a call on `setDefaultNamespace(String)` then the element will be in that namespace; otherwise it will be in no namespace.
      Returns:
        a new `Tag` representing the new element node
      Throws:
        `SaxonApiException` - if the specified constraints are violated, or if the implementation detects any problems

    - #### text

          Push.Container text​(java.lang.CharSequence value)
                       throws SaxonApiException

      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")`.

      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.Container comment​(java.lang.CharSequence value)
                          throws SaxonApiException

      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`.

      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.Container processingInstruction​(java.lang.String name,
                                               java.lang.CharSequence value)
                                        throws SaxonApiException

      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`.

      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

    - #### close

          void close()
              throws SaxonApiException

      Close the current document or element container.

      Closing a container more than once has no effect.

      Adding any content to a node after it has been closed causes an exception.

      Closing a node implicitly closes any unclosed children of the node.

      Throws:
        `SaxonApiException` - if a downstream recipient of the data reports a failure