Class SMOutputContainer

  • Direct Known Subclasses:
    SMBufferedFragment, SMOutputElement, SMRootFragment

    public abstract class SMOutputContainer
    extends SMOutputtable
    Intermediate abstract output class for StaxMate, which is used as the base for all output nodes that can contain other nodes. Both buffered and unbuffered classes exists, as well as root-level and branch containers. All output by sub-classes is using by the underlying XMLStreamWriter, using the context (SMOutputContext).

    Whether writes are buffered or not generally depends on buffering states of preceding nodes (elements, fragments), in document order: if an ancestor (parent, grand-parent) or a preceding sibling is buffered, so is this fragment, until all such nodes have been released.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected SMOutputContext _context
      Context of this node; defines things like the underlying stream writer and known namespaces.
      protected SMOutputtable _firstChild
      First child node that has not yet been completely output to the underlying stream.
      protected SMOutputtable _lastChild
      Last child node that has not been output to the underlying stream.
      protected SMOutputContainer _parent
      Parent of this container; null for root-level entities, as well as not-yet-linked buffered containers.
    • Method Summary

      All Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      abstract boolean _canOutputNewChild()
      Method called to figure out if we can just output a newly added child, without any buffering.
      protected abstract void _childReleased​(SMOutputtable child)
      Method called by a child, when it is released and neither is or contains any buffered entities.
      protected boolean _closeAllButLastChild()
      Method that will try to close and output all children except for the last, and if that succeeds, output last child if it need not be closed (true for non-element/simple children).
      protected boolean _closeAndOutputChildren()
      Method that will try to close and output all child nodes that can be (ones that are not buffered), and returns true if that succeeds; or false if there was at least one buffered descendant.
      protected void _forceChildOutput()  
      protected abstract void _forceOutput​(SMOutputContext ctxt)
      Method similar to SMOutputtable._output(org.codehaus.staxmate.out.SMOutputContext, boolean), except that this method will always succeed in doing the output.
      protected void _linkNewChild​(SMOutputtable n)  
      protected abstract boolean _output​(SMOutputContext ctxt, boolean canClose)
      Method called to request that the entity output itself; either as much as it can without closing, or as much as it can if it is to get closed.
      protected void _throwClosed()  
      protected void _throwRelinking()  
      protected SMNamespace _verifyNamespaceArg​(SMNamespace ns)
      Method called to ensure that the passed-in namespace can be used for actual output operation.
      SMBufferable addAndReleaseBuffered​(SMBufferable buffered)
      Method for appending specified buffered output element as child of this container, and releasing it if it is still buffered.
      SMBufferable addBuffered​(SMBufferable buffered)  
      void addCData​(char[] buf, int offset, int len)
      Method for appending specified text as CDATA within this output container.
      void addCData​(java.lang.String text)
      Method for appending specified text as CDATA within this output container.
      void addCharacters​(char[] buf, int offset, int len)
      Method for adding simple textual content to the xml output stream.
      void addCharacters​(java.lang.String text)
      Method for adding simple textual content to the xml output stream.
      void addComment​(java.lang.String text)
      Method for appending specified comment within this output container.
      SMOutputElement addElement​(java.lang.String localName)
      Convenience method (equivalent to addElement(null, localName);) for adding an element that is not in a namespace.
      SMOutputElement addElement​(SMNamespace ns, java.lang.String localName)
      Method for adding specified element as a child of this container.
      SMOutputElement addElementWithCharacters​(SMNamespace ns, java.lang.String localName, java.lang.String text)
      Convenience method for adding a child element (that has no attributes) to this container, and adding specified text as child of that child element.
      void addEntityRef​(java.lang.String name)
      Method for appending specified entity reference this output container.
      void addProcessingInstruction​(java.lang.String target, java.lang.String data)
      Method for appending specified processing instruction within this output container.
      void addValue​(boolean value)
      Typed output method for outputting boolean value as (textual) xml content.
      <T extends SMOutputContainer>
      T
      addValue​(byte[] value)
      Typed output method for outputting binary value (encoded using default Base64 encoding variant) as (textual) xml content.
      <T extends SMOutputContainer>
      T
      addValue​(byte[] value, int offset, int length)
      Typed output method for outputting binary value (encoded using default Base64 encoding variant) as (textual) xml content.
      void addValue​(double value)
      Typed output method for outputting double value as (textual) xml content.
      void addValue​(int value)
      Typed output method for outputting integer value as (textual) xml content.
      void addValue​(long value)
      Typed output method for outputting long integer value as (textual) xml content.
      SMBufferedElement createBufferedElement​(SMNamespace ns, java.lang.String localName)
      Method constructing a buffer element Contents of buffered elements are not immediately output to the underlying stream.
      SMBufferedFragment createBufferedFragment()
      Method constructing a fragment ("invisible" container that is not directly represented by any xml construct and that can contain other output objects) that is buffered: that is, contents of which are not immediately output to the underlying stream.
      SMOutputContext getContext()
      Method for accessing output context (which encloses actual output stream).
      SMNamespace getNamespace​(java.lang.String uri)
      Convenience method for getting namespace instance that uniquely represents the specified URI (uniquely meaning that for a given output context there are never more than one instances for a given URI; which means that identity comparison is enough to check for equality of two namespaces).
      SMNamespace getNamespace​(java.lang.String uri, java.lang.String prefPrefix)
      Method for getting namespace instance that represents the specified URI, and if it is not yet bound, tries to bind it to given prefix.
      SMOutputContainer getParent()
      Method to use for getting parent of this container, which is null for root-level containers (document, fragment).
      java.lang.String getPath()
      Method that can be called to get an XPath like description of the relative location of this output node, starting from root.
      abstract void getPath​(java.lang.StringBuilder sb)
      Method that can be called to get an XPath like description of the relative location of this output node, starting from root.
      void setIndentation​(java.lang.String indentStr, int startOffset, int step)
      This method can be called to enable or disable heuristic indentation for the output done using this output context.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • _context

        protected final SMOutputContext _context
        Context of this node; defines things like the underlying stream writer and known namespaces.
      • _parent

        protected SMOutputContainer _parent
        Parent of this container; null for root-level entities, as well as not-yet-linked buffered containers.
      • _firstChild

        protected SMOutputtable _firstChild
        First child node that has not yet been completely output to the underlying stream. This may be due to a blocking condition (parent blocked, children blocked, or the child itself being buffered). May be null if no children have been added, or if all have been completely output.
      • _lastChild

        protected SMOutputtable _lastChild
        Last child node that has not been output to the underlying stream.
    • Constructor Detail

    • Method Detail

      • setIndentation

        public void setIndentation​(java.lang.String indentStr,
                                   int startOffset,
                                   int step)
        This method can be called to enable or disable heuristic indentation for the output done using this output context.

        Here are some example calls:

        context.setIndentation("\n ", 1, 2); // indent by lf and 2 spaces per level context.setIndentation(null, 0, 0); // disable indentation context.setIndentation("\r\n\t\t\t\t\t\t\t\t", 2, 1); // indent by windows lf and 1 tab per level
        Parameters:
        indentStr - String to use for indentation; if non-null, will enable indentation, if null, will disable it. Used in conjunction with the other arguments
        startOffset - Initial character offset for the first level of indentation (current context; usually root context): basically, number of leading characters from indentStr to output.
        step - Number of characters to add from the indentation String for each new level (and to subtract when closing levels).
      • getParent

        public final SMOutputContainer getParent()
        Method to use for getting parent of this container, which is null for root-level containers (document, fragment).
        Returns:
        Parent container of this container, if any; null for root-level containers
      • getContext

        public final SMOutputContext getContext()
        Method for accessing output context (which encloses actual output stream).
        Returns:
        Output context for this container
      • getNamespace

        public final SMNamespace getNamespace​(java.lang.String uri)
        Convenience method for getting namespace instance that uniquely represents the specified URI (uniquely meaning that for a given output context there are never more than one instances for a given URI; which means that identity comparison is enough to check for equality of two namespaces). Calls SMOutputContext to find the actual namespace instance.
        Returns:
        Namespace object which is bound to given namespace URI for scope of this container
      • getNamespace

        public final SMNamespace getNamespace​(java.lang.String uri,
                                              java.lang.String prefPrefix)
        Method for getting namespace instance that represents the specified URI, and if it is not yet bound, tries to bind it to given prefix. Note however that actual prefix used may be different due to conflicts: most important thing is that the specified URI will be bound to a valid prefix. Actual prefix can be checked by looking at returned namespace object
        Returns:
        Namespace object which is bound to given namespace URI for scope of this container
      • addCharacters

        public void addCharacters​(java.lang.String text)
                           throws javax.xml.stream.XMLStreamException
        Method for adding simple textual content to the xml output stream. Content added will be escaped by the underlying stream, as necessary.

        Will buffer content in cases where necessary (when content gets added to buffered container that has not yet been released: the purposes of which is to allow out-of-order addition of content).

        Throws:
        javax.xml.stream.XMLStreamException
      • addCharacters

        public void addCharacters​(char[] buf,
                                  int offset,
                                  int len)
                           throws javax.xml.stream.XMLStreamException
        Method for adding simple textual content to the xml output stream. Content added will be escaped by the underlying stream, as necessary.

        Will buffer content in cases where necessary (when content gets added to buffered container that has not yet been released: the purposes of which is to allow out-of-order addition of content).

        Throws:
        javax.xml.stream.XMLStreamException
      • addCData

        public void addCData​(java.lang.String text)
                      throws javax.xml.stream.XMLStreamException
        Method for appending specified text as CDATA within this output container.

        Note: for buffered (and not-yet-released) containers, will hold contents buffered until release of container.

        Throws:
        javax.xml.stream.XMLStreamException
      • addCData

        public void addCData​(char[] buf,
                             int offset,
                             int len)
                      throws javax.xml.stream.XMLStreamException
        Method for appending specified text as CDATA within this output container.

        Note: for buffered (and not-yet-released) containers, will hold contents buffered until release of container.

        Throws:
        javax.xml.stream.XMLStreamException
      • addComment

        public void addComment​(java.lang.String text)
                        throws javax.xml.stream.XMLStreamException
        Method for appending specified comment within this output container.

        Note: for buffered (and not-yet-released) containers, will hold contents buffered until release of container.

        Throws:
        javax.xml.stream.XMLStreamException
      • addEntityRef

        public void addEntityRef​(java.lang.String name)
                          throws javax.xml.stream.XMLStreamException
        Method for appending specified entity reference this output container.

        Note: for buffered (and not-yet-released) containers, will hold contents buffered until release of container.

        Parameters:
        name - Name of the entity to reference: should not contain the leading '&' character (which will get properly prepended by the stream writer)
        Throws:
        javax.xml.stream.XMLStreamException
      • addProcessingInstruction

        public void addProcessingInstruction​(java.lang.String target,
                                             java.lang.String data)
                                      throws javax.xml.stream.XMLStreamException
        Method for appending specified processing instruction within this output container.

        Note: for buffered (and not-yet-released) containers, will hold contents buffered until release of container.

        Throws:
        javax.xml.stream.XMLStreamException
      • addValue

        public void addValue​(boolean value)
                      throws javax.xml.stream.XMLStreamException
        Typed output method for outputting boolean value as (textual) xml content. Equivalent to calling addCharacters(String.valueOf(value)) but likely more efficient (with streams that support Typed Access API) as well as more explicit semantically.
        Throws:
        javax.xml.stream.XMLStreamException
      • addValue

        public void addValue​(int value)
                      throws javax.xml.stream.XMLStreamException
        Typed output method for outputting integer value as (textual) xml content. Equivalent to calling addCharacters(String.valueOf(value)) but likely more efficient (with streams that support Typed Access API) as well as more explicit semantically.
        Throws:
        javax.xml.stream.XMLStreamException
      • addValue

        public void addValue​(long value)
                      throws javax.xml.stream.XMLStreamException
        Typed output method for outputting long integer value as (textual) xml content. Equivalent to calling addCharacters(String.valueOf(value)) but likely more efficient (with streams that support Typed Access API) as well as more explicit semantically.
        Throws:
        javax.xml.stream.XMLStreamException
      • addValue

        public void addValue​(double value)
                      throws javax.xml.stream.XMLStreamException
        Typed output method for outputting double value as (textual) xml content. Equivalent to calling addCharacters(String.valueOf(value)) but likely more efficient (with streams that support Typed Access API) as well as more explicit semantically.
        Throws:
        javax.xml.stream.XMLStreamException
      • addValue

        public <T extends SMOutputContainer> T addValue​(byte[] value)
                                                 throws javax.xml.stream.XMLStreamException
        Typed output method for outputting binary value (encoded using default Base64 encoding variant) as (textual) xml content.
        Throws:
        javax.xml.stream.XMLStreamException
        Since:
        2.2
      • addValue

        public <T extends SMOutputContainer> T addValue​(byte[] value,
                                                        int offset,
                                                        int length)
                                                 throws javax.xml.stream.XMLStreamException
        Typed output method for outputting binary value (encoded using default Base64 encoding variant) as (textual) xml content.
        Throws:
        javax.xml.stream.XMLStreamException
        Since:
        2.2
      • addElement

        public SMOutputElement addElement​(SMNamespace ns,
                                          java.lang.String localName)
                                   throws javax.xml.stream.XMLStreamException
        Method for adding specified element as a child of this container.
        Parameters:
        ns - Namespace for the element (may be null if element is not to belong to a namespace)
        localName - Local name part of the element name; may not be null or empty
        Throws:
        javax.xml.stream.XMLStreamException
      • addElement

        public SMOutputElement addElement​(java.lang.String localName)
                                   throws javax.xml.stream.XMLStreamException
        Convenience method (equivalent to addElement(null, localName);) for adding an element that is not in a namespace.

        Note: this is NOT the same as outputting an element that simply has no prefix (ie. one that would belong to whatever is the current default namespace).

        Throws:
        javax.xml.stream.XMLStreamException
      • addElementWithCharacters

        public SMOutputElement addElementWithCharacters​(SMNamespace ns,
                                                        java.lang.String localName,
                                                        java.lang.String text)
                                                 throws javax.xml.stream.XMLStreamException
        Convenience method for adding a child element (that has no attributes) to this container, and adding specified text as child of that child element. This is functionally equivalent to calling:
           container.addElement(ns, localName).addCharacters(text);
        

        Note: no attributes can be added to the returned child element, because textual content has already been added.

        Throws:
        javax.xml.stream.XMLStreamException
        Since:
        2.0
      • addBuffered

        public SMBufferable addBuffered​(SMBufferable buffered)
                                 throws javax.xml.stream.XMLStreamException
        Throws:
        javax.xml.stream.XMLStreamException
      • addAndReleaseBuffered

        public SMBufferable addAndReleaseBuffered​(SMBufferable buffered)
                                           throws javax.xml.stream.XMLStreamException
        Method for appending specified buffered output element as child of this container, and releasing it if it is still buffered. This allows for its contents to be output to the underlying stream unless there are preceding buffered containers that are not yet released. This is functionally equivalent to calling:
           container.addBuffered(buffered).release();
        
        Parameters:
        buffered - Buffered container to append and release
        Throws:
        javax.xml.stream.XMLStreamException
      • createBufferedFragment

        public SMBufferedFragment createBufferedFragment()
        Method constructing a fragment ("invisible" container that is not directly represented by any xml construct and that can contain other output objects) that is buffered: that is, contents of which are not immediately output to the underlying stream. This allows for buffered fragments to be appended out-of-order, and only output when released (by calling SMBufferable.release() method).
      • createBufferedElement

        public SMBufferedElement createBufferedElement​(SMNamespace ns,
                                                       java.lang.String localName)
        Method constructing a buffer element Contents of buffered elements are not immediately output to the underlying stream. This allows for buffered elements to be appended out-of-order, and only output when released (by calling SMBufferable.release() method).
      • _output

        protected abstract boolean _output​(SMOutputContext ctxt,
                                           boolean canClose)
                                    throws javax.xml.stream.XMLStreamException
        Description copied from class: SMOutputtable
        Method called to request that the entity output itself; either as much as it can without closing, or as much as it can if it is to get closed. In both cases output can fail or be only a partial one: buffered nodes will not be output at all, and nodes with buffered children can only be partially output.
        Specified by:
        _output in class SMOutputtable
        Parameters:
        ctxt - Output context to use for outputting this node (and its contents)
        canClose - If true, indicates that the node can (and should) be fully closed if possible. This (passing true) is usually done when a new sibling is added after a node (element/fragment); if so, current one should be recursively closed. If false, should only try to output as much as can be done without forcing closures.
        Returns:
        True if the whole node could be output, ie. neither it nor its children are buffered.
        Throws:
        javax.xml.stream.XMLStreamException
      • _childReleased

        protected abstract void _childReleased​(SMOutputtable child)
                                        throws javax.xml.stream.XMLStreamException
        Method called by a child, when it is released and neither is or contains any buffered entities. This should indicate that it can be output unless one of its parents or preceding siblings is buffered. Container is expected to update its own state, and then inform its own parent (if necesary) about release; this may cascade output from parents up the container stack.
        Parameters:
        child - Child node that now neither is nor contains any buffered nodes.
        Throws:
        javax.xml.stream.XMLStreamException
      • _canOutputNewChild

        public abstract boolean _canOutputNewChild()
                                            throws javax.xml.stream.XMLStreamException
        Method called to figure out if we can just output a newly added child, without any buffering. It will request container to close and output all non-buffered children it has, if any; and indicate whether it was fully succesful or not.
        Returns:
        True if all children (if any) were completely output; false if there was at least one buffered child that couldn't be output.
        Throws:
        javax.xml.stream.XMLStreamException
      • getPath

        public final java.lang.String getPath()
        Method that can be called to get an XPath like description of the relative location of this output node, starting from root.
      • getPath

        public abstract void getPath​(java.lang.StringBuilder sb)
        Method that can be called to get an XPath like description of the relative location of this output node, starting from root. Path will be appended to given StringBuilder.
      • _linkNewChild

        protected void _linkNewChild​(SMOutputtable n)
      • _closeAndOutputChildren

        protected final boolean _closeAndOutputChildren()
                                                 throws javax.xml.stream.XMLStreamException
        Method that will try to close and output all child nodes that can be (ones that are not buffered), and returns true if that succeeds; or false if there was at least one buffered descendant.
        Returns:
        True if all descendants (children, recursively) were succesfully output, possibly closing them first if necessary
        Throws:
        javax.xml.stream.XMLStreamException
      • _closeAllButLastChild

        protected final boolean _closeAllButLastChild()
                                               throws javax.xml.stream.XMLStreamException
        Method that will try to close and output all children except for the last, and if that succeeds, output last child if it need not be closed (true for non-element/simple children).
        Throws:
        javax.xml.stream.XMLStreamException
      • _forceChildOutput

        protected final void _forceChildOutput()
                                        throws javax.xml.stream.XMLStreamException
        Throws:
        javax.xml.stream.XMLStreamException
      • _verifyNamespaceArg

        protected final SMNamespace _verifyNamespaceArg​(SMNamespace ns)
        Method called to ensure that the passed-in namespace can be used for actual output operation. It converts nulls to the proper "no namespace" instance, and ensures that (so far) unbound namespaces are properly bound (including declaring them as needed).
      • _throwRelinking

        protected void _throwRelinking()
      • _throwClosed

        protected void _throwClosed()