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 inherited from class org.codehaus.staxmate.out.SMOutputtable

mNext

Constructor Summary

protected

SMOutputContainer(SMOutputContext ctxt)

Method Summary

SMBufferable	addAndReleaseBuffered(SMBufferable buffered)
SMBufferable	addBuffered(SMBufferable buffered)
void	addCData(char[] buf, int offset, int len)
void	addCData(java.lang.String text)
void	addCharacters(char[] buf, int offset, int len)
void	addCharacters(int value) Convenience method for adding value of an int as text
void	addCharacters(java.lang.String text)
void	addComment(java.lang.String text)
SMOutputElement	addElement(SMNamespace ns, java.lang.String localName)
SMOutputElement	addElement(java.lang.String localName) Convenience method (equivalent to addElement(null, localName);) for adding an element that is not in a namespace.
void	addEntityRef(java.lang.String name)
void	addProcessingInstruction(java.lang.String target, java.lang.String data)
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.
SMBufferedElement	createBufferedElement(SMNamespace ns, java.lang.String localName)
SMBufferedFragment	createBufferedFragment()
protected abstract boolean	doOutput(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	forceChildOutput()
protected abstract void	forceOutput(SMOutputContext ctxt) Method similar to SMOutputtable.doOutput(org.codehaus.staxmate.out.SMOutputContext, boolean), except that this method will always succeed in doing the output.
SMOutputContext	getContext()
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)
SMOutputContainer	getParent()
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)
protected void	linkNewChild(SMOutputtable n)
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.
protected void	throwBuffered()
protected void	throwClosed()
protected void	throwRelinking()

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

getNext, linkNext

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SMOutputContainer

protected SMOutputContainer(SMOutputContext ctxt)

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

getContext

public final SMOutputContext getContext()

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.

getNamespace

public final SMNamespace getNamespace(java.lang.String uri,
                                      java.lang.String prefPrefix)

addCharacters

public void addCharacters(java.lang.String text)
                   throws javax.xml.stream.XMLStreamException

Throws:

javax.xml.stream.XMLStreamException

addCharacters

public void addCharacters(char[] buf,
                          int offset,
                          int len)
                   throws javax.xml.stream.XMLStreamException

Throws:

javax.xml.stream.XMLStreamException

addCharacters

public void addCharacters(int value)
                   throws javax.xml.stream.XMLStreamException

Convenience method for adding value of an int as text

Throws:

javax.xml.stream.XMLStreamException

addCData

public void addCData(java.lang.String text)
              throws javax.xml.stream.XMLStreamException

Throws:

javax.xml.stream.XMLStreamException

addCData

public void addCData(char[] buf,
                     int offset,
                     int len)
              throws javax.xml.stream.XMLStreamException

Throws:

javax.xml.stream.XMLStreamException

addComment

public void addComment(java.lang.String text)
                throws javax.xml.stream.XMLStreamException

Throws:

javax.xml.stream.XMLStreamException

addEntityRef

public void addEntityRef(java.lang.String name)
                  throws javax.xml.stream.XMLStreamException

Throws:

javax.xml.stream.XMLStreamException

addProcessingInstruction

public void addProcessingInstruction(java.lang.String target,
                                     java.lang.String data)
                              throws javax.xml.stream.XMLStreamException

Throws:

javax.xml.stream.XMLStreamException

addElement

public SMOutputElement addElement(SMNamespace ns,
                                  java.lang.String localName)
                           throws javax.xml.stream.XMLStreamException

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

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

Throws:

javax.xml.stream.XMLStreamException

createBufferedFragment

public SMBufferedFragment createBufferedFragment()

createBufferedElement

public SMBufferedElement createBufferedElement(SMNamespace ns,
                                               java.lang.String localName)

doOutput

protected abstract boolean doOutput(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:

doOutput 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

forceOutput

protected abstract void forceOutput(SMOutputContext ctxt)
                             throws javax.xml.stream.XMLStreamException

Description copied from class: SMOutputtable

Method similar to SMOutputtable.doOutput(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:

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)

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

throwClosed

protected void throwClosed()

throwRelinking

protected void throwRelinking()

throwBuffered

protected void throwBuffered()