Class 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 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:
    Tree­Table

    Defined in the sis-utility module

    • 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 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 sometime 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.