Package org.apache.sis.util.collection

## Class TreeTables

- Object
- - Static
  - - TreeTables

-     public final class TreeTables
      extends Static

  Static methods working on `TreeTable` objects and their nodes. This class provides methods for some tasks considered generic enough, and example codes for more specialized tasks that developers can customize.

  The remaining of this class javadoc contains example codes placed in public domain. Developers can copy and adapt those examples as they see fit.

  Example 1: Reduce the depth of a tree
  For every branch containing exactly one child, the following method concatenates in-place that branch and its child together. This method can be used for simplifying depth trees into something less verbose. For example given the tree on the left side, this method transforms it into the tree on the right side:

  Example of tree depth reduction
  Before | After
  --- | ---
  >     root
  >       ├─users
  >       │   └─alice
  >       │       ├─data
  >       │       │   └─mercator
  >       │       └─document
  >       └─lib
  >     root
  >       ├─users/alice
  >       │   ├─data/mercator
  >       │   └─document
  >       └─lib

  There is no pre-defined method for this task because there is too many parameters that developers may want to customize (columns to merge, conditions for accepting the merge, kind of objects to merge, name separator, etc.). In the following code snippet, the content of the `NAME` columns are concatenated only if the `VALUE` column has no value (for avoiding data lost when the node is discarded) and use the system file separator as name separator:

  >     final TableColumn columnToProtect = TableColumn.VALUE;
  >     final TableColumn columnToConcatenate = TableColumn.NAME;

  >     TreeTable.Node concatenateSingletons(final TreeTable.Node node) {
  >         // This simple example is restricted to nodes which are known to handle
  >         // their children in a list instead than some other kind of collection.
  >         final List<TreeTable.Node> children = (List<TreeTable.Node>) node.getChildren();
  >         final int size = children.size();
  >         for (int i=0; i<size; i++) {
  >             children.set(i, concatenateSingletons(children.get(i)));
  >         }
  >         if (size == 1) {
  >             final TreeTable.Node child = children.get(0);
  >             if (node.getValue(columnToProtect) == null) {
  >                 children.remove(0);
  >                 child.setValue(columnToConcatenate,
  >                         node .getValue(columnToConcatenate) + File.separator +
  >                         child.getValue(columnToConcatenate));
  >                 return child;
  >             }
  >         }
  >         return node;
  >     }

  Since:
    0.3
  See Also:
    `TreeTable`

  Defined in the `sis-utility` module

- - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static TreeTable.Node` | `nodeForPath​(TreeTable.Node from, TableColumn<? super String> column, File path)` | Finds the node for the given file, or creates a new node if none exists.
    `static TreeTable.Node` | `nodeForPath​(TreeTable.Node from, TableColumn<? super String> column, Path path)` | Finds the node for the given path, or creates a new node if none exists.
    `static TreeTable` | `parse​(String tree, TableColumn<?> labelColumn, TableColumn<?>... otherColumns)` | Parses the given string as tree.
    `static int` | `replaceCharSequences​(TreeTable table, Locale locale)` | For every columns having values of type `CharSequence` or `String`, converts the values to localized `String`s.
    `static String` | `toString​(TreeTable table)` | Returns a string representation of the given tree table.

    - ### Methods inherited from class Object

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

- - ### Method Detail

    - #### nodeForPath

          public static TreeTable.Node nodeForPath​(TreeTable.Node from,
                                                   TableColumn<? super String> column,
                                                   Path path)

      Finds the node for the given path, or creates a new node if none exists. First, this method searches in the node children collection for the root element of the given path. If no such node is found, a new child is created. Then this method repeats the process (searching in the children of the child for the second path element), until the last path element is reached.

      For example if the given path is `"users/alice/data"`, then this method finds or creates the nodes for the following tree, where `"from"` is the node given in argument to this method:

      >     from
      >       └─users
      >           └─alice
      >               └─data

      Parameters:
        `from` - the root node from which to start the search.
        `column` - the column containing the file name.
        `path` - the path for which to find or create a node.
      Returns:
        the node for the given path, either as an existing node or a new node.

    - #### nodeForPath

          public static TreeTable.Node nodeForPath​(TreeTable.Node from,
                                                   TableColumn<? super String> column,
                                                   File path)

      Finds the node for the given file, or creates a new node if none exists. This method performs the same work than the above variant, but working on `File` instances rather than `Path`.
      Parameters:
        `from` - the root node from which to start the search.
        `column` - the column containing the file name.
        `path` - the file for which to find or create a node.
      Returns:
        the node for the given file, either as an existing node or a new node.

    - #### replaceCharSequences

          public static int replaceCharSequences​(TreeTable table,
                                                 Locale locale)

      For every columns having values of type `CharSequence` or `String`, converts the values to localized `String`s. During conversions, this method also replaces duplicated `String` instances by references to the same singleton instance.

      This method may be invoked before to serialize the table in order to reduce the serialization stream size.

      Parameters:
        `table` - the table in which to replace values by their string representations.
        `locale` - the locale to use when replacing `InternationalString` instances. Can be `null`.
      Returns:
        number of replacements done.

    - #### toString

          public static String toString​(TreeTable table)

      Returns a string representation of the given tree table. The current implementation uses a shared instance of `TreeTableFormat`. This is okay for debugging or occasional usages. However for more extensive usages, developers are encouraged to create and configure their own `TreeTableFormat` instance.
      Parameters:
        `table` - the tree table to format.
      Returns:
        a string representation of the given tree table.

    - #### parse

          public static TreeTable parse​(String tree,
                                        TableColumn<?> labelColumn,
                                        TableColumn<?>... otherColumns)
                                 throws ParseException

      Parses the given string as tree. This helper method is sometime useful for quick tests or debugging purposes. For more extensive use, consider using `TreeTableFormat` instead.
      Parameters:
        `tree` - the string representation of the tree to parse.
        `labelColumn` - the columns where to store the node labels. This is often `TableColumn​.NAME`.
        `otherColumns` - optional columns where to store the values, if any.
      Returns:
        a tree parsed from the given string.
      Throws:
        `ParseException` - if an error occurred while parsing the tree.