org.codehaus.staxmate.out

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

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

_next

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	SMOutputContainer(SMOutputContext ctxt)

Method Summary

Methods

Modifier and Type	Method and 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(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(String text) Method for adding simple textual content to the xml output stream.
void	addComment(String text) Method for appending specified comment within this output container.
SMOutputElement	addElement(SMNamespace ns, String localName) Method for adding specified element as a child of this container.
SMOutputElement	addElement(String localName) Convenience method (equivalent to addElement(null, localName);) for adding an element that is not in a namespace.
SMOutputElement	addElementWithCharacters(SMNamespace ns, String localName, 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(String name) Method for appending specified entity reference this output container.
void	addProcessingInstruction(String target, 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, 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(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(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.
SMOutputContainer	getParent() Method to use for getting parent of this container, which is null for root-level containers (document, fragment).
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(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(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 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

SMOutputContainer

protected SMOutputContainer(SMOutputContext ctxt)

Method Detail

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()