facets.util.datatree
Class XmlDocRoot

java.lang.Object
  facets.util.Tracer
      facets.util.datatree.Nodes.TreeRoot
          facets.util.datatree.XmlDocRoot

public final class XmlDocRoot
extends Nodes.TreeRoot

Reads and writes a DataNode tree as an XML document.

DataNodes are written as XML elements, their titles and keypair values as attributes, other stringified values as text nodes (but see Text segregation below). Nodes to be written need only fulfil the DataNode contract; elements are read as ValueNodes to allow the retrieval and setting of attributes as keypairs.

To separate mechanism from policy, Nodes.TreeRoot is declared final and document-specific values are provided by a XmlPolicy passed to the constructor.

Unless XmlPolicy.treeAsXmlRoot() returns true, the root of the DataNode tree is assumed to represent the XML document itself and the first child only of this root is rendered as the XML root element. While it may appear cumbersome that the tree root wrapped is not by default the XML root, this approach has advantages:

• The tree root exists in advance of any attempt to read into it.
• The tree root can define properties of the XML document eg file information.
• If the type of the tree root is known in advance of reading the XML root, it is simple to check that the type of the XML root is as expected.

StatefulCore.title()s can be mapped to attribute names using XmlPolicy.getTitleAttributeNames().

Text segregation

Since ValueNode stores XML attributes as keypairs which cannot be distinguished from text matching Nodes.isKeyPair(String), XmlDocRoot enforces segregation of text from elements with attributes:

• In readFromSource(Object) text from an element with attributes other than that mapped to StatefulCore.title() (or all elements if XmlPolicy.segregateAll() returns true) is wrapped in a node created by XmlPolicy.newSegregated(String[]). As this node may need to be interim to avoid name collisions, the complete tree can be tidied up as required in XmlPolicy.cleanUpSegregated(DataNode).
• In writeToSink(Object) (unless XmlPolicy.dataUsesAttributes() returns false) values matching Nodes.isKeyPair(String) are set as element attributes and no other values from the same node can be written; nodes identified by XmlPolicy.isSegregated(DataNode) are written as text nodes.

Field Summary

static java.lang.String

SHEBANG

Fields inherited from class facets.util.datatree.Nodes.TreeRoot

tree

Constructor Summary

XmlDocRoot(DataNode node, XmlPolicy p)
Unique constructor.

Method Summary

static TextLines	newDocumentXml(org.w3c.dom.Document document) Creates XML text from a Document.
static org.w3c.dom.Document	newXmlDocument(TextLines xml) Reads XML text into a Document.
static java.lang.String	newXmlTop(java.lang.String encoding)
void	readFromSource(java.lang.Object src) Reads an XML document from text.
void	writeToSink(java.lang.Object sink) Creates XML document text.

Methods inherited from class facets.util.Tracer

trace, trace, trace, trace, trace, traceDebug, traceDebug, traceObjectText, traceOutput, traceOutputWithClass

Methods inherited from class java.lang.Object

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

Field Detail

SHEBANG

public static final java.lang.String SHEBANG

See Also:

Constant Field Values

Constructor Detail

XmlDocRoot

public XmlDocRoot(DataNode node,
                  XmlPolicy p)

Unique constructor.

Parameters:

node - passed to superclass

p - defines detail behaviour

Method Detail

readFromSource

public void readFromSource(java.lang.Object src)
                    throws java.io.IOException

Reads an XML document from text.

Text obtained from src is read as follows:

• parsed as an XML document whose root element is set as the contents of the node wrapped (except where XmlPolicy.treeAsXmlRoot() returns true)
• any parse exception wrapped in an ExceptionNode set as the contents of the node.

Each XML element is read into a ValueNode with:

• its name returned as type
• child elements returned in children
• attributes handled as documented for XmlPolicy.newTitleAttributeNames(String, String[]);
• text split into line values and possibly segregated (see class summary)

Specified by:

readFromSource in class Nodes.TreeRoot

Parameters:

src - must be either a File or a TextLines

Throws:

java.io.IOException

writeToSink

public void writeToSink(java.lang.Object sink)
                 throws java.io.IOException

Creates XML document text.

XML text that renders the DataNode tree wrapped is written to sink, with members of the tree rendered as XML elements, except for those identified by XmlPolicy.isSegregated(DataNode) which are rendered as text nodes.

For other nodes the type is used as the element name and any title other than TypedNode.UNTITLED is rendered by an attribute as documented in XmlPolicy.newTitleAttributeNames(String,String[]).

Stringified values are rendered as follows:

• if XmlPolicy.dataUsesAttributes() returns true and all values are keypairs, as attributes
• otherwise, as a text node

Specified by:

writeToSink in class Nodes.TreeRoot

Parameters:

sink - must be either a File or a TextLines

Throws:

java.io.IOException

newXmlDocument

public static org.w3c.dom.Document newXmlDocument(TextLines xml)
                                           throws javax.xml.parsers.ParserConfigurationException,
                                                  org.xml.sax.SAXException,
                                                  java.io.IOException

Reads XML text into a Document.

Called internally by readFromSource(Object); exposed to enable creation of Documents from text rather than a stream.

Parameters:

xml - loaded with XML text

Throws:

javax.xml.parsers.ParserConfigurationException

org.xml.sax.SAXException

java.io.IOException

newDocumentXml

public static TextLines newDocumentXml(org.w3c.dom.Document document)
                                throws javax.xml.transform.TransformerFactoryConfigurationError,
                                       javax.xml.transform.TransformerConfigurationException,
                                       javax.xml.transform.TransformerException

Creates XML text from a Document.

Used internally by writeToSink(Object) to enable post-processing of XML text in XmlPolicy.prettifyRawXML(String); exposed to enable temporary storage of a Documents as text.

Returns:

a TextLines.newBuffer(String[]) loaded with XML text

Throws:

javax.xml.transform.TransformerFactoryConfigurationError

javax.xml.transform.TransformerConfigurationException

javax.xml.transform.TransformerException

newXmlTop

public static final java.lang.String newXmlTop(java.lang.String encoding)