Class SMOutputContainer

java.lang.Object
org.codehaus.staxmate.out.SMOutputtable
org.codehaus.staxmate.out.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 final SMOutputContext
    Context of this node; defines things like the underlying stream writer and known namespaces.
    protected SMOutputtable
    First child node that has not yet been completely output to the underlying stream.
    protected SMOutputtable
    Last child node that has not been output to the underlying stream.
    Parent of this container; null for root-level entities, as well as not-yet-linked buffered containers.

    Fields inherited from class org.codehaus.staxmate.out.SMOutputtable

    _next
  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
     
  • Method Summary

    Modifier and Type
    Method
    Description
    abstract boolean
    Method called to figure out if we can just output a newly added child, without any buffering.
    protected abstract void
    Method called by a child, when it is released and neither is or contains any buffered entities.
    protected final boolean
    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 final boolean
    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 final void
     
    protected abstract void
    Method similar to SMOutputtable._output(org.codehaus.staxmate.out.SMOutputContext, boolean), except that this method will always succeed in doing the output.
    protected void
     
    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
     
    protected void
     
    protected final SMNamespace
    Method called to ensure that the passed-in namespace can be used for actual output operation.
    Method for appending specified buffered output element as child of this container, and releasing it if it is still buffered.
     
    void
    addCData(char[] buf, int offset, int len)
    Method for appending specified text as CDATA within this output container.
    void
    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
    Method for adding simple textual content to the xml output stream.
    void
    Method for appending specified comment within this output container.
    addElement(String localName)
    Convenience method (equivalent to addElement(null, localName);) for adding an element that is not in a namespace.
    addElement(SMNamespace ns, String localName)
    Method for adding specified element as a child of this container.
    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
    Method for appending specified entity reference this output container.
    void
    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.
    Method constructing a buffer element Contents of buffered elements are not immediately output to the underlying stream.
    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.
    Method for accessing output context (which encloses actual output stream).
    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).
    getNamespace(String uri, 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.
    Method to use for getting parent of this container, which is null for root-level containers (document, fragment).
    final String
    Method that can be called to get an XPath like description of the relative location of this output node, starting from root.
    abstract void
    Method that can be called to get an XPath like description of the relative location of this output node, starting from root.
    void
    setIndentation(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 org.codehaus.staxmate.out.SMOutputtable

    _linkNext, getNext

    Methods inherited from class java.lang.Object

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

    • _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 Details

  • Method Details

    • setIndentation

      public void setIndentation(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(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(String uri, 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(String text) throws 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:
      XMLStreamException
    • addCharacters

      public void addCharacters(char[] buf, int offset, int len) throws 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:
      XMLStreamException
    • addCData

      public void addCData(String text) throws 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:
      XMLStreamException
    • addCData

      public void addCData(char[] buf, int offset, int len) throws 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:
      XMLStreamException
    • addComment

      public void addComment(String text) throws 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:
      XMLStreamException
    • addEntityRef

      public void addEntityRef(String name) throws 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:
      XMLStreamException
    • addProcessingInstruction

      public void addProcessingInstruction(String target, String data) throws 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:
      XMLStreamException
    • addValue

      public void addValue(boolean value) throws 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:
      XMLStreamException
    • addValue

      public void addValue(int value) throws 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:
      XMLStreamException
    • addValue

      public void addValue(long value) throws 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:
      XMLStreamException
    • addValue

      public void addValue(double value) throws 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:
      XMLStreamException
    • addValue

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

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

      public SMOutputElement addElement(SMNamespace ns, String localName) throws 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:
      XMLStreamException
    • addElement

      public SMOutputElement addElement(String localName) throws 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:
      XMLStreamException
    • addElementWithCharacters

      public SMOutputElement addElementWithCharacters(SMNamespace ns, String localName, String text) throws 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:
      XMLStreamException
      Since:
      2.0
    • addBuffered

      public SMBufferable addBuffered(SMBufferable buffered) throws XMLStreamException
      Throws:
      XMLStreamException
    • addAndReleaseBuffered

      public SMBufferable addAndReleaseBuffered(SMBufferable buffered) throws 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:
      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, 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 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:
      XMLStreamException
    • _forceOutput

      protected abstract void _forceOutput(SMOutputContext ctxt) throws XMLStreamException
      Description copied from class: SMOutputtable
      Method similar to SMOutputtable._output(org.codehaus.staxmate.out.SMOutputContext, boolean), except that this method will always succeed in doing the output. Specifically, it will force all buffered nodes to be unbuffered, and then output.
      Specified by:
      _forceOutput in class SMOutputtable
      Throws:
      XMLStreamException
    • _childReleased

      protected abstract void _childReleased(SMOutputtable child) throws 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:
      XMLStreamException
    • _canOutputNewChild

      public abstract boolean _canOutputNewChild() throws 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:
      XMLStreamException
    • getPath

      public final 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(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 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:
      XMLStreamException
    • _closeAllButLastChild

      protected final boolean _closeAllButLastChild() throws 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:
      XMLStreamException
    • _forceChildOutput

      protected final void _forceChildOutput() throws XMLStreamException
      Throws:
      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()