Package org.simpleframework.xml.stream
Interface OutputNode
-
- All Superinterfaces:
Node
- All Known Implementing Classes:
OutputAttribute
,OutputDocument
,OutputElement
public interface OutputNode extends Node
TheOutputNode
object is used to represent a cursor which can be used to write XML elements and attributes. Each of the output node objects represents a element, and can be used to add attributes to that element as well as child elements.
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description void
commit()
Thecommit
method is used flush and commit any child nodes that have been created by this node.NodeMap<OutputNode>
getAttributes()
This returns aNodeMap
which can be used to add nodes to the element before that element has been committed.OutputNode
getChild(java.lang.String name)
This is used to create a child element within the element that this object represents.java.lang.String
getComment()
This is used to get the text comment for the element.Mode
getMode()
TheMode
is used to indicate the output mode of this node.NamespaceMap
getNamespaces()
This returns theNamespaceMap
for this node.OutputNode
getParent()
This is used to acquire theNode
that is the parent of this node.java.lang.String
getPrefix()
This is used to acquire the prefix for this output node.java.lang.String
getPrefix(boolean inherit)
This is used to acquire the prefix for this output node.java.lang.String
getReference()
This is used to acquire the namespace URI reference associated with this node.boolean
isCommitted()
This is used to determine whether the node has been committed.boolean
isRoot()
This method is used to determine if this node is the root node for the XML document.void
remove()
This is used to remove any uncommitted changes.OutputNode
setAttribute(java.lang.String name, java.lang.String value)
This method is used for convenience to add an attribute node to the attributeNodeMap
.void
setComment(java.lang.String comment)
This is used to set a text comment to the element.void
setData(boolean data)
This is used to set the output mode of this node to either be CDATA or escaped.void
setMode(Mode mode)
This is used to set the output mode of this node to either be CDATA, escaped, or inherited.void
setName(java.lang.String name)
This is used to change the name of an output node.void
setReference(java.lang.String reference)
This is used to set the reference for the node.void
setValue(java.lang.String value)
This is used to set a text value to the element.
-
-
-
Method Detail
-
isRoot
boolean isRoot()
This method is used to determine if this node is the root node for the XML document. The root node is the first node in the document and has no sibling nodes. This is false if the node has a parent node or a sibling node.- Returns:
- true if this is the root node within the document
-
getAttributes
NodeMap<OutputNode> getAttributes()
This returns aNodeMap
which can be used to add nodes to the element before that element has been committed. Nodes can be removed or added to the map and will appear as attributes on the written element when it is committed.- Returns:
- returns the node map used to manipulate attributes
-
getMode
Mode getMode()
TheMode
is used to indicate the output mode of this node. Three modes are possible, each determines how a value, if specified, is written to the resulting XML document. This is determined by thesetData
method which will set the output to be CDATA or escaped, if neither is specified the mode is inherited.- Returns:
- this returns the mode of this output node object
-
setMode
void setMode(Mode mode)
This is used to set the output mode of this node to either be CDATA, escaped, or inherited. If the mode is set to data then any value specified will be written in a CDATA block, if this is set to escaped values are escaped. If however this method is set to inherited then the mode is inherited from the parent node.- Parameters:
mode
- this is the output mode to set the node to
-
setData
void setData(boolean data)
This is used to set the output mode of this node to either be CDATA or escaped. If this is set to true the any value specified will be written in a CDATA block, if this is set to false the values is escaped. If however this method is never invoked then the mode is inherited from the parent.- Parameters:
data
- if true the value is written as a CDATA block
-
getPrefix
java.lang.String getPrefix()
This is used to acquire the prefix for this output node. If the output node is an element then this will search its parent nodes until the prefix that is currently in scope is found. If however this node is an attribute then the hierarchy of nodes is not searched as attributes to not inherit namespaces.- Returns:
- this returns the prefix associated with this node
-
getPrefix
java.lang.String getPrefix(boolean inherit)
This is used to acquire the prefix for this output node. If the output node is an element then this will search its parent nodes until the prefix that is currently in scope is found. If however this node is an attribute then the hierarchy of nodes is not searched as attributes to not inherit namespaces.- Parameters:
inherit
- if there is no explicit prefix then inherit- Returns:
- this returns the prefix associated with this node
-
getReference
java.lang.String getReference()
This is used to acquire the namespace URI reference associated with this node. Although it is recommended that the namespace reference is a URI it does not have to be, it can be any unique identifier that can be used to distinguish the qualified names.- Returns:
- this returns the namespace URI reference for this
-
setReference
void setReference(java.lang.String reference)
This is used to set the reference for the node. Setting the reference implies that the node is a qualified node within the XML document. Both elements and attributes can be qualified. Depending on the prefix set on this node or, failing that, any parent node for the reference, the element will appear in the XML document with that string prefixed to the node name.- Parameters:
reference
- this is used to set the reference for the node
-
getNamespaces
NamespaceMap getNamespaces()
This returns theNamespaceMap
for this node. Only an element can have namespaces, so if this node represents an attribute the elements namespaces will be provided when this is requested. By adding a namespace it becomes in scope for the current element all all child elements of that element.- Returns:
- this returns the namespaces associated with the node
-
getComment
java.lang.String getComment()
This is used to get the text comment for the element. This can be null if no comment has been set. If no comment is set on the node then no comment will be written to the resulting XML.- Returns:
- this is the comment associated with this element
-
setComment
void setComment(java.lang.String comment)
This is used to set a text comment to the element. This will be written just before the actual element is written. Only a single comment can be set for each output node written.- Parameters:
comment
- this is the comment to set on the node
-
setValue
void setValue(java.lang.String value)
This is used to set a text value to the element. This should be added to the element if the element contains no child elements. If the value cannot be added an exception is thrown.- Parameters:
value
- this is the text value to add to this element- Throws:
java.lang.Exception
- thrown if the text value cannot be added
-
setName
void setName(java.lang.String name)
This is used to change the name of an output node. This will only affect the name of the node if the node has not yet been committed. If the node is committed then this will not be reflected in the resulting XML generated.- Parameters:
name
- this is the name to change the node to
-
setAttribute
OutputNode setAttribute(java.lang.String name, java.lang.String value)
This method is used for convenience to add an attribute node to the attributeNodeMap
. The attribute added can be removed from the element by using the node map.- Parameters:
name
- this is the name of the attribute to be addedvalue
- this is the value of the node to be added- Returns:
- this returns the node that has just been added
-
getParent
OutputNode getParent()
This is used to acquire theNode
that is the parent of this node. This will return the node that is the direct parent of this node and allows for siblings to make use of nodes with their parents if required.
-
getChild
OutputNode getChild(java.lang.String name) throws java.lang.Exception
This is used to create a child element within the element that this object represents. When a new child is created with this method then the previous child is committed to the document. The createdOutputNode
object can be used to add attributes to the child element as well as other elements.- Parameters:
name
- this is the name of the child element to create- Throws:
java.lang.Exception
-
remove
void remove() throws java.lang.Exception
This is used to remove any uncommitted changes. Removal of an output node can only be done if it has no siblings and has not yet been committed. If the node is committed then this will throw an exception to indicate that it cannot be removed.- Throws:
java.lang.Exception
- thrown if the node cannot be removed
-
commit
void commit() throws java.lang.Exception
Thecommit
method is used flush and commit any child nodes that have been created by this node. This allows the output to be completed when building of the XML document has been completed. If output fails an exception is thrown.- Throws:
java.lang.Exception
- thrown if the node cannot be committed
-
isCommitted
boolean isCommitted()
This is used to determine whether the node has been committed. If the node has been committed, then this will return true. When committed the node can no longer produce chile nodes.- Returns:
- true if this node has already been committed
-
-