facets.util.datatree
Class XmlPolicy

java.lang.Object
  facets.util.Tracer
      facets.util.datatree.XmlPolicy

public class XmlPolicy
extends Tracer

Defines document and other policy for an XmlDocRoot, in particular XmlSpecifiers for loading and saving content.

For background to segregate methods see XmlDocRoot summary.

Field Summary

static java.lang.String	KEY_TITLE_ATTR_NAME_DEFAULT Key for storing default value in newTitleAttributeNames(String, String[]).
static java.lang.String	TYPE_SEGREGATED

Constructor Summary

XmlPolicy()

Method Summary

protected void	cleanUpSegregated(DataNode tree) After reading, clean up tree containing segregated text.
protected boolean	dataUsesAttributes() When writing, does the data specify element attributes?
XmlSpecifier[]	fileSpecifiers()
protected ValueNode	getTitleAttributeNames() When reading or writing, maps attribute names to StatefulCore.title()s.
protected boolean	handleReadExceptions() When reading, should read exceptions be thrown or handled?
protected boolean	isSegregated(DataNode node) When writing, may identify segregated text.
protected DataNode	newSegregated(java.lang.String[] lines) When reading, create a (possibly interim) node for segregated text.
protected static ValueNode	newTitleAttributeNames(java.lang.String defaultName, java.lang.String[] mappings) Creates mappings for return by getTitleAttributeNames().
protected java.lang.String	prettifyRawXML(java.lang.String raw) When writing, enhances readability of XML text.
protected boolean	segregateAll() When reading, should text be segregated even where the containing element has no attributes?
protected java.lang.String[]	textToValueLines(java.lang.String text) When reading, pre-process contents of XML text node.
protected boolean	titleAttributeKeyPairs() When reading, should names be included with attributes exposed in StatefulCore.title()s?
protected boolean	treeAsXmlRoot() After reading or before writing, is/should be tree rooted on the XML root node?
protected static java.lang.String[]	trimmedValueLines(java.lang.String text) Utility method used by textToValueLines(String).

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

TYPE_SEGREGATED

public static final java.lang.String TYPE_SEGREGATED

See Also:

Constant Field Values

KEY_TITLE_ATTR_NAME_DEFAULT

public static final java.lang.String KEY_TITLE_ATTR_NAME_DEFAULT

Key for storing default value in newTitleAttributeNames(String, String[]).

See Also:

Constant Field Values

Constructor Detail

XmlPolicy

public XmlPolicy()

Method Detail

fileSpecifiers

public XmlSpecifier[] fileSpecifiers()

treeAsXmlRoot

protected boolean treeAsXmlRoot()

After reading or before writing, is/should be tree rooted on the XML root node?

Returning true has the effect that

• in XmlDocRoot.readFromSource(Object) and providing they have the same type, the single child of tree is replaced with its own contents.
• in XmlDocRoot.writeToSink(Object) the XML root node is created from tree

Returns:

false by default

newSegregated

protected DataNode newSegregated(java.lang.String[] lines)

When reading, create a (possibly interim) node for segregated text.

Default is invalid stub.

Parameters:

lines - to be segregated, created by textToValueLines(String)

segregateAll

protected boolean segregateAll()

When reading, should text be segregated even where the containing element has no attributes?

Returns:

false by default

cleanUpSegregated

protected void cleanUpSegregated(DataNode tree)

After reading, clean up tree containing segregated text.

Default is invalid stub.

Parameters:

tree - contains nodes created by newSegregated(String[])

isSegregated

protected boolean isSegregated(DataNode node)

When writing, may identify segregated text.

Returns:

false unless node type is "_text"

dataUsesAttributes

protected boolean dataUsesAttributes()

When writing, does the data specify element attributes?

Return false to avoid text segregation issues when writing.

Returns:

true by default

getTitleAttributeNames

protected ValueNode getTitleAttributeNames()

When reading or writing, maps attribute names to StatefulCore.title()s.

Returns:

non-null node created using newTitleAttributeNames(String,String[]); by default a minimal node

newTitleAttributeNames

protected static ValueNode newTitleAttributeNames(java.lang.String defaultName,
                                                  java.lang.String[] mappings)

Creates mappings for return by getTitleAttributeNames().

Parameters:

defaultName - attribute name to be mapped to StatefulCore.title() in tags not specified by mappings; may be empty

mappings - in format tagName=attName, where

• tagName is an XML tag name (and TypedNode.type())
• attName names an attribute for tagName and will be mapped to StatefulCore.title() when reading or writing an element

titleAttributeKeyPairs

protected boolean titleAttributeKeyPairs()

When reading, should names be included with attributes exposed in StatefulCore.title()s?

Returns:

false by default

textToValueLines

protected java.lang.String[] textToValueLines(java.lang.String text)

When reading, pre-process contents of XML text node.

Parameters:

text - from text node

Returns:

strings to be stored as TypedNode.values(); storing any non-empty array from an element with attributes will require a valid implementation of newSegregated(String[]). Default returns trimmedValueLines(String).

trimmedValueLines

protected static java.lang.String[] trimmedValueLines(java.lang.String text)

Utility method used by textToValueLines(String).

Returns:

for blank text an empty array, otherwise lines split with blanks removed

prettifyRawXML

protected java.lang.String prettifyRawXML(java.lang.String raw)

When writing, enhances readability of XML text.

Called from XmlDocRoot.writeToSink(Object); default breaks lines after tag ends and attribute pairs.

Parameters:

raw - text returned by XmlDocRoot.newDocumentXml(Document)

handleReadExceptions

protected boolean handleReadExceptions()

When reading, should read exceptions be thrown or handled?

If handled, an ExceptionNode is added to the tree.

Returns:

true by default