Package org.apache.sis.util.collection

Class TreeTableFormat

java.lang.Object
java.text.Format
org.apache.sis.io.CompoundFormat<T>
org.apache.sis.io.TabularFormat<TreeTable>
org.apache.sis.util.collection.TreeTableFormat
All Implemented Interfaces:
Serializable, Cloneable, Localized
Direct Known Subclasses:
MetadataFormat
public class TreeTableFormat extends TabularFormat<TreeTable>
A parser and formatter for TreeTable instances. This formatter is given an arbitrary number of TableColumns to use during the formatting. The first column is taken as the node label. If a TreeTable is formatted with only that column, then the String result is like the following example: If the same TreeTable is formatted with two columns, then the String result is like the following example: 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 TreeTable 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 be found in ISO 19115 metadata. This TreeTableFormat 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
Version:
1.1
See Also:

  • Field Details

    • serialVersionUID

      private static final long serialVersionUID
      For cross-version compatibility.
      See Also:

    • INSTANCE

      static final TreeTableFormat INSTANCE
      Shared TreeTableFormat instance for DefaultTreeTable.toString() implementation. Usage of this instance shall be done in a synchronized block. Note that metadata objects defined as AbstractMetadata subclasses use their own format instance.

    • columnIndices

      private Map<TableColumn<?>,Integer> columnIndices
      The table columns to format, or null for formatting all of them. This map shall not be modified after creation, because it may be shared by many tables.
      See Also:

    • indentation

      private int indentation
      The number of characters to add on the left side for each indentation level. The default value is 4.
      See Also:

    • verticalLinePosition

      private int verticalLinePosition
      The position of the vertical line, relative to the position of the label of the parent node. The default value is 2, which means that the vertical line is drawn below the third letter of the node label.
      See Also:

    • treeBlank

      private transient String treeBlank
      The tree symbols to write in the left margin, or null if not yet computed. The default symbols are as below:
      • treeBlank = "    "
      • treeLine = "  │ "
      • treeCross = "  ├─"
      • treeEnd = "  └─"
      See Also:

    • treeLine

      private transient String treeLine
      The tree symbols to write in the left margin, or null if not yet computed. The default symbols are as below:
      • treeBlank = "    "
      • treeLine = "  │ "
      • treeCross = "  ├─"
      • treeEnd = "  └─"
      See Also:

    • treeCross

      private transient String treeCross
      The tree symbols to write in the left margin, or null if not yet computed. The default symbols are as below:
      • treeBlank = "    "
      • treeLine = "  │ "
      • treeCross = "  ├─"
      • treeEnd = "  └─"
      See Also:

    • treeEnd

      private transient String treeEnd
      The tree symbols to write in the left margin, or null if not yet computed. The default symbols are as below:
      • treeBlank = "    "
      • treeLine = "  │ "
      • treeCross = "  ├─"
      • treeEnd = "  └─"
      See Also:

    • nodeFilter

      private Predicate<TreeTable.Node> nodeFilter
      A filter for specifying whether a node should be formatted, or null if no filtering is applied. This is ignored at parsing time.
      See Also:

    • recursivityGuard

      private transient Set<TreeTable.Node> recursivityGuard
      The set to be given to TreeTableFormat.Writer constructor, created when first needed and reused for subsequent formatting.

    • adaptableFormat

      private transient DecimalFormat adaptableFormat
      A clone of the number format to be used with different settings (number of fraction digits, scientific notation). We use a clone for avoiding to change the setting of potentially user supplied number format. This is used only for floating point numbers, not for integers.

    • defaultPattern

      private transient String defaultPattern
      The default pattern used by adaptableFormat. Used for switching back to default mode after scientific notation.

    • usingScientificNotation

      private transient boolean usingScientificNotation
      Whether adaptableFormat is using scientific notation.

  • Constructor Details

    • 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 Details

    • clearTreeSymbols

      private void clearTreeSymbols()
      Clears the symbols used when writing the tree. They will be computed again when first needed.
      See Also:

    • getValueType

      public final Class<TreeTable> getValueType()
      Returns the type of objects formatted by this class.
      Specified by:
      getValueType in class CompoundFormat<TreeTable>
      Returns:
      TreeTable.class

    • getColumns

      public TableColumn<?>[] getColumns()
      Returns the table columns to parse and format, or null for the default list of columns. The default is:
      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 getColumns() method.
      Parameters:
      columns - the table columns to parse and format, or null for the default.
      Throws:
      IllegalArgumentException - 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 latter is also set to the given indentation value.
      Parameters:
      indentation - the new indentation.
      Throws:
      IllegalArgumentException - 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 cannot be greater than the indentation.
      Parameters:
      verticalLinePosition - the new vertical line position.
      Throws:
      IllegalArgumentException - if the given value is negative or greater than the indentation.

    • getNodeFilter

      public Predicate<TreeTable.Node> getNodeFilter()
      Returns the filter that specify whether a node should be formatted or ignored. This is the predicate specified in the last call to setNodeFilter(Predicate). If no filter has been set, then this method returns null.
      Returns:
      a filter for specifying whether a node should be formatted, or null if no filtering is applied.
      Since:
      1.0

    • setNodeFilter

      public void setNodeFilter(Predicate<TreeTable.Node> filter)
      Sets a filter specifying whether a node should be formatted or ignored. Filters are tested at formatting time for all children of the root node (but not for the root node itself). Filters are ignored at parsing time.
      Parameters:
      filter - filter for specifying whether a node should be formatted, or null for no filtering.
      Since:
      1.0

    • getDisplayLocale

      private Locale getDisplayLocale()
      Returns the locale to use for code lists, international strings and localized messages of exceptions.

    • getFormats

      final Format[] getFormats(TableColumn<?>[] columns, boolean mandatory) throws IllegalStateException
      Returns the formats to use for parsing and formatting the values of each column. The returned array may contain null elements, which means that the values in that column can be stored as Strings.
      Parameters:
      mandatory - true if an exception shall be thrown for unrecognized types, or false for storing a null value in the array instead.
      Throws:
      IllegalStateException - if mandatory is true and a column contains values of an unsupported type.

    • 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 getIndentation() 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:
      Specified by:
      parse in class CompoundFormat<TreeTable>
      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 cannot be parsed.
      Throws:
      ParseException - if an error occurred while parsing a node value.

    • parseValue

      private <V> void parseValue(TreeTable.Node node, TableColumn<V> column, Format format, String text) throws ParseException
      Parses the given string using a format appropriate for the type of values in the given column, and stores the value in the given node.

      This work is done in a separated method instead of inlined in the parse(…) method because of the <V> parametric value.

      Type Parameters:
      V - the type of values in the given column.
      Parameters:
      node - the node in which to set the value.
      column - the column in which to set the value.
      format - the format to use for parsing the value, or null.
      text - the textual representation of the value.
      Throws:
      ParseException - if an error occurred while parsing.
      ClassCastException - if the parsed value is not of the expected type.

    • createTreeSymbols

      private void createTreeSymbols()
      Computes the tree* fields from the indentation and verticalLinePosition current values.
      See Also:

    • getTreeSymbols

      final String getTreeSymbols(boolean isParent, boolean isLast)
      Returns the string to write before a node.
      Parameters:
      isParent - true for a parent node, or false for the actual node.
      isLast - true if the node is the last children of its parent node.

    • 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 CompoundFormat.getFormat(Class).
      Specified by:
      format in class CompoundFormat<TreeTable>
      Parameters:
      tree - the tree to format.
      toAppendTo - where to format the tree.
      Throws:
      IOException - if an error occurred while writing to the given appendable.
      See Also:

    • createFormat

      protected Format createFormat(Class<?> valueType)
      Creates a new format to use for parsing and formatting values of the given type. This method is invoked the first time that a format is needed for the given type. Subclasses can override this method if they want to configure the way dates, numbers or other objects are formatted. See parent class documentation for more information.

      The implementation in TreeTableFormat differs from the default implementation in the following aspects:

      Overrides:
      createFormat in class CompoundFormat<TreeTable>
      Parameters:
      valueType - the base type of values to parse or format.
      Returns:
      the format to use for parsing of formatting values of the given type, or null if none.

    • writeColumnSeparator

      protected void writeColumnSeparator(int nextColumn, TableAppender out)
      Writes characters between columns. The default implementation applies the configuration specified by TabularFormat.setColumnSeparatorPattern(String) as below:
      out.append(beforeFill); out.nextColumn(fillCharacter); out.append(columnSeparator);
      The output with default values is like below: Subclasses can override this method if different column separators are desired. Note however that doing so may prevent the parse(…) method to work.
      Parameters:
      nextColumn - zero-based index of the column to be written after the separator.
      out - where to write the column separator.
      Since:
      1.0
      See Also:

    • clone

      public TreeTableFormat clone()
      Returns a clone of this format.
      Overrides:
      clone in class TabularFormat<TreeTable>
      Returns:
      a clone of this format.