org.apache.sis.util.collection

Class TreeTableFormat

Object

Format

CompoundFormat<T>

TabularFormat<TreeTable>

TreeTableFormat

All Implemented Interfaces:

Serializable, Cloneable, Localized

public class TreeTableFormat
extends TabularFormat<TreeTable>

A parser and formatter for Tree­Table instances. This formatter is given an arbitrary number of Table­Columns to use during the formatting. The first column is taken as the node label. If a Tree­Table is formatted with only that column, then the String result is like the following example:

Node #1
  ├─Node #2
  │   └─Node #4
  └─Node #3

If the same Tree­Table is formatted with two columns, then the String result is like the following example:

Node #1……………………… More #1
  ├─Node #2…………… More #2
  │   └─Node #4… More #4
  └─Node #3…………… More #3

This representation can be printed to the console output (for example) if the stream uses a monospaced font and supports Unicode characters.

Customization

Some formatting characteristics (indentation width, column where to draw the vertical line below nodes) can be modified by calls to the setter methods defined in this formatter. In particular, the dots joining the node labels to their values can be specified by the column separator pattern. The default pattern is "?……[…] ", which means "If the next value is non-null, then insert the "……" string, repeat the '…' character as many time as needed (may be zero), and finally insert a space".

Safety against infinite recursivity

Some Tree­Table implementations generate the nodes dynamically as wrappers around Java objects. Such Java objects may contain cyclic associations (A contains B contains C contains A), which result in a tree of infinite depth. Some examples can been found in ISO 19115 metadata. This Tree­Table­Format class contains a safety against such cycles. The algorithm is based on the assumption that for each node, the values and children are fully determined by the user object, if non-null. Consequently for each node C to be formatted, if the user object of that node is the same instance (in the sense of the == operator) than the user object of a parent node A, then the children of the C node will not be formatted.

Since:

0.3

See Also:

Serialized Form

Defined in the sis-utility module

Nested Class Summary

Nested classes/interfaces inherited from class Format

Format.Field

Field Summary

Fields inherited from class TabularFormat

before­Fill, column­Separator, fill­Character, line­Separator, omit­Trailing­Nulls

Constructor Summary

Constructors

Constructor and Description
TreeTableFormat(Locale locale, TimeZone timezone) Creates a new tree table format.

Method Summary

Modifier and Type	Method and Description
TreeTableFormat	clone() Returns a clone of this format.
void	format(TreeTable tree, Appendable toAppendTo) Writes a graphical representation of the specified tree table in the given stream or buffer.
TableColumn<?>[]	getColumns() Returns the table columns to parse and format, or null for the default list of columns.
int	getIndentation() Returns the number of spaces to add on the left margin for each indentation level.
Class<TreeTable>	getValueType() Returns the type of objects formatted by this class.
int	getVerticalLinePosition() Returns the position of the vertical line, relative to the position of the root label.
TreeTable	parse(CharSequence text, ParsePosition pos) Creates a tree from the given character sequence, or returns null if the given text does not look like a tree for this method.
void	setColumns(TableColumn<?>... columns) Sets the table columns to parse and format.
void	setIndentation(int indentation) Sets the number of spaces to add on the left margin for each indentation level.
void	setVerticalLinePosition(int verticalLinePosition) Sets the position of the vertical line, relative to the position of the root label.

Methods inherited from class TabularFormat

get­Column­Separator­Matcher, get­Column­Separator­Pattern, get­Line­Separator, set­Column­Separator­Pattern, set­Line­Separator

Methods inherited from class CompoundFormat

create­Format, format, get­Format, get­Locale, get­Locale, get­Time­Zone, parse­Object, parse­Object

Methods inherited from class Format

format, format­To­Character­Iterator

Methods inherited from class Object

equals, finalize, get­Class, hash­Code, notify, notify­All, to­String, wait, wait, wait

Constructor Detail

TreeTableFormat

public TreeTableFormat(Locale locale,
                       TimeZone timezone)

Creates a new tree table format.

Parameters:

locale - the locale to use for numbers, dates and angles formatting, or null for the root locale.

timezone - the timezone, or null for UTC.

Method Detail

getValueType

public final Class<TreeTable> getValueType()

Returns the type of objects formatted by this class.

Specified by:

get­Value­Type in class Compound­Format<Tree­Table>

Returns:

Tree­Table.class

getColumns

public TableColumn<?>[] getColumns()

Returns the table columns to parse and format, or null for the default list of columns. The default is:

• On parsing, a single column containing the node label as a String.
• On formatting, all Tree­Table columns.

Returns:

the table columns to parse and format, or null for the default.

setColumns

public void setColumns(TableColumn<?>... columns)
                throws IllegalArgumentException

Sets the table columns to parse and format. A null value means to use the default list of columns, as defined in the get­Columns() method.

Parameters:

columns - the table columns to parse and format, or null for the default.

Throws:

Illegal­Argument­Exception - if the given array is empty, contains a null element or a duplicated value.

getIndentation

public int getIndentation()

Returns the number of spaces to add on the left margin for each indentation level. The default value is 4.

Returns:

the current indentation.

setIndentation

public void setIndentation(int indentation)
                    throws IllegalArgumentException

Sets the number of spaces to add on the left margin for each indentation level. If the new indentation is smaller than the vertical line position, then the later is also set to the given indentation value.

Parameters:

indentation - the new indentation.

Throws:

Illegal­Argument­Exception - if the given value is negative.

getVerticalLinePosition

public int getVerticalLinePosition()

Returns the position of the vertical line, relative to the position of the root label. The default value is 2, which means that the vertical line is drawn below the third letter of the root label.

Returns:

the current vertical line position.

setVerticalLinePosition

public void setVerticalLinePosition(int verticalLinePosition)
                             throws IllegalArgumentException

Sets the position of the vertical line, relative to the position of the root label. The given value can not be greater than the indentation.

Parameters:

vertical­Line­Position - the new vertical line position.

Throws:

Illegal­Argument­Exception - if the given value is negative or greater than the indentation.

parse

public TreeTable parse(CharSequence text,
                       ParsePosition pos)
                throws ParseException

Creates a tree from the given character sequence, or returns null if the given text does not look like a tree for this method. This method can parse the trees created by the format(…) methods defined in this class.

Parsing rules

• Each node shall be represented by a single line made of two parts, in that order:
  1. white spaces and tree drawing characters ('│', '├', '└' or '─');
  2. string representations of node values, separated by the colunm separator.
• The number of spaces and drawing characters before the node values determines the node indentation. This indentation does not need to be a factor of the get­Indentation() value, but must be consistent across all the parsed tree.
• The indentation determines the parent of each node.
• Parsing stops at first empty line (ignoring whitespaces), or at the end of the given text.

Error index

If the given text does not seem to be a tree table, then this method returns null. Otherwise if parsing started but failed, then:

• Parse­Position.get­Error­Index() will give the index at the beginning of line or beginning of cell where the error occurred, and
• Parse­Exception.get­Error­Offset() will give either the same value, or a slightly more accurate value inside the cell.

Specified by:

parse in class Compound­Format<Tree­Table>

Parameters:

text - the character sequence for the tree to parse.

pos - the position where to start the parsing.

Returns:

the parsed tree, or null if the given character sequence can not be parsed.

Throws:

Parse­Exception - if an error occurred while parsing a node value.

format

public void format(TreeTable tree,
                   Appendable toAppendTo)
            throws IOException

Writes a graphical representation of the specified tree table in the given stream or buffer. This method iterates recursively over all children. For each column to format in each node, this method gets a textual representation of the value in that column using the formatter obtained by a call to Compound­Format.get­Format(Class).

Specified by:

format in class Compound­Format<Tree­Table>

Parameters:

tree - the tree to format.

to­Append­To - where to format the tree.

Throws:

IOException - if an error occurred while writing to the given appendable.

See Also:

Tree­Tables.to­String(Tree­Table)

clone

public TreeTableFormat clone()

Returns a clone of this format.

Overrides:

clone in class Tabular­Format<Tree­Table>

Returns:

a clone of this format.