Class SMOutputContainer
- Direct Known Subclasses:
SMBufferedFragment
,SMOutputElement
,SMRootFragment
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
FieldsModifier and TypeFieldDescriptionprotected 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.protected SMOutputContainer
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 -
Method Summary
Modifier and TypeMethodDescriptionabstract boolean
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 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
_forceOutput
(SMOutputContext ctxt) Method similar toSMOutputtable._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.addAndReleaseBuffered
(SMBufferable buffered) Method for appending specified buffered output element as child of this container, and releasing it if it is still buffered.addBuffered
(SMBufferable 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
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.addElement
(String localName) Convenience method (equivalent toaddElement(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.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>
TaddValue
(byte[] value) Typed output method for outputting binary value (encoded using default Base64 encoding variant) as (textual) xml content.<T extends SMOutputContainer>
TaddValue
(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.createBufferedElement
(SMNamespace ns, String localName) 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.final SMOutputContext
Method for accessing output context (which encloses actual output stream).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).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.final SMOutputContainer
Method to use for getting parent of this container, which is null for root-level containers (document, fragment).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.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
-
Field Details
-
_context
Context of this node; defines things like the underlying stream writer and known namespaces. -
_parent
Parent of this container; null for root-level entities, as well as not-yet-linked buffered containers. -
_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
Last child node that has not been output to the underlying stream.
-
-
Constructor Details
-
SMOutputContainer
-
-
Method Details
-
setIndentation
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 argumentsstartOffset
- Initial character offset for the first level of indentation (current context; usually root context): basically, number of leading characters fromindentStr
to output.step
- Number of characters to add from the indentation String for each new level (and to subtract when closing levels).
-
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
Method for accessing output context (which encloses actual output stream).- Returns:
- Output context for this container
-
getNamespace
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). CallsSMOutputContext
to find the actual namespace instance.- Returns:
- Namespace object which is bound to given namespace URI for scope of this container
-
getNamespace
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
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
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
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
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
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
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
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
Typed output method for outputting boolean value as (textual) xml content. Equivalent to callingaddCharacters(String.valueOf(value))
but likely more efficient (with streams that support Typed Access API) as well as more explicit semantically.- Throws:
XMLStreamException
-
addValue
Typed output method for outputting integer value as (textual) xml content. Equivalent to callingaddCharacters(String.valueOf(value))
but likely more efficient (with streams that support Typed Access API) as well as more explicit semantically.- Throws:
XMLStreamException
-
addValue
Typed output method for outputting long integer value as (textual) xml content. Equivalent to callingaddCharacters(String.valueOf(value))
but likely more efficient (with streams that support Typed Access API) as well as more explicit semantically.- Throws:
XMLStreamException
-
addValue
Typed output method for outputting double value as (textual) xml content. Equivalent to callingaddCharacters(String.valueOf(value))
but likely more efficient (with streams that support Typed Access API) as well as more explicit semantically.- Throws:
XMLStreamException
-
addValue
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
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
Convenience method (equivalent toaddElement(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
- Throws:
XMLStreamException
-
addAndReleaseBuffered
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
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 callingSMBufferable.release()
method). -
createBufferedElement
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 callingSMBufferable.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 classSMOutputtable
- 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
Description copied from class:SMOutputtable
Method similar toSMOutputtable._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 classSMOutputtable
- Throws:
XMLStreamException
-
_childReleased
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
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
Method that can be called to get an XPath like description of the relative location of this output node, starting from root. -
getPath
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
-
_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.- Returns:
- True if all descendants (children, recursively) were succesfully output, possibly closing them first if necessary
- Throws:
XMLStreamException
-
_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).- Throws:
XMLStreamException
-
_forceChildOutput
- Throws:
XMLStreamException
-
_verifyNamespaceArg
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()
-