Interface Container

  • All Known Subinterfaces:
    Document, Element

    public interface 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.
      Container comment​(java.lang.CharSequence value)
      Add a comment node to the current element or document node.
      Element element​(java.lang.String name)
      Start an element node, with a specified local name.
      Element element​(QName name)
      Start an element node, with a specified prefix, namespace URI, and local name.
      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.
      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

        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

        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

        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

        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

        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