Module org.apache.sis.util
Package org.apache.sis.util.collection

Class TreeTables

Object
Static
TreeTables
public final class TreeTables extends Static
Static methods working on Tree­Table 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
BeforeAfter
   root
     ├─users
     │   └─alice
     │       ├─data
     │       │   └─mercator
     │       └─document
     └─lib
 
   root
     ├─users/alice
     │   ├─data/mercator
     │   └─document
     └─lib
There is no predefined 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: 
class MyClass {
    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 of 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:

  • Method Details

    • 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 Char­Sequence or String, converts the values to localized Strings. 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 International­String 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 Tree­Table­Format. This is okay for debugging or occasional usages. However for more extensive usages, developers are encouraged to create and configure their own Tree­Table­Format 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 sometimes useful for quick tests or debugging purposes. For more extensive use, consider using Tree­Table­Format instead.
      Parameters:
      tree - the string representation of the tree to parse.
      label­Column - the columns where to store the node labels. This is often Table­Column​.NAME.
      other­Columns - optional columns where to store the values, if any.
      Returns:
      a tree parsed from the given string.
      Throws:
      Parse­Exception - if an error occurred while parsing the tree.