Package Torello.Java

Class FileNode

  • All Implemented Interfaces:
    java.io.Serializable, java.lang.CharSequence, java.lang.Cloneable, java.lang.Comparable<FileNode>
    public final class FileNode
extends java.lang.Object
implements java.lang.CharSequence, java.lang.Comparable<FileNode>, java.io.Serializable, java.lang.Cloneable
    One of the flagship classes of Java HTML, FileNode loads a directory or directory-tree from a File-System into memory, and provides a thorough API for listing and analyzing its contents.

    This loads the UNIX or MS-DOS file-system tree into Java Memory. It can be a very useful utility class. Both directory-filters and file-filters may be used to eliminate or include certain files. It uses a simple (obvious) recursive method to load all files and sub-directories into a tree which can be traversed or flattened.

    No Method within This Class Performs File-System Writes!

    Writes may only be performed after retrieving a file-name list, and invoking some other mechanism, for instance: FileTransfer, FileRW or java.io.File
    This class builds an in memory node-tree that is loaded from disk, and mirrors the directory tree from which it was loaded. The contents of these 'nodes' are nothing more than java.lang.String's, and a few other pieces of data including a 'fileSize' field, and a 'lastModified' field. (At present, there is no attributes field). As nothing more than a String-Tree, experiments with the features of the class are harmless - since only Java Memory will be modified!

    It is possible to use this class to modify files and directories on disk, but it requires additional classes / code to do so. Some suggestions include:

    • Use class FileTransfer, to move copy or delete files.

    • Retrieve File-Names from a FileNode-Tree, and use Java's standard java.io.* package to modify file(s) contents, using your own code that your trust.

    • There are numerous methods, provided here, for retrieving lists of file-names, and much can be done with a list of files, once retrieved, using any utside library.


    Load a Tree:
    There are numerous methods provided for loading the contents of the file-system into a FileNode tree. These methods offer different ways of limiting which files will be inserted and read when reading from disk. The Java FunctionalInterface structure is used via interface FileNodeFilter. These filters can be built with standard lambda-expressions, or by implementing the functional-interface.


    Flatten a Tree:
    It is important to note that the primary purpose of the Vector<FileNode> flatten(...) methods are such that lists of files can be used, printed, looked-at, etc... by the programmer. The individual instances of FileNode are saved to a single list by flatten(...) methods, which makes working with the actual operating-system file, itself, quick and easy.


    Print a Tree:
    There are three methods for printing various branches of the tree provided by this class.


    These concepts are illustrated in the example code, below:

    Example:
    // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
// Printing Example
// *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
// 
// Prints all ".java" source-files in your directory hierarchy

FileNode.createRoot("MyJavaPackages/")
        .loadTree(-1, (f, name) -> name.endsWith(".java"), null)
        .printTree(); 


// *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
// Flatten Example
// *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
// 
// NOTE: This ought to produce the same output as the previous example,
// except showing ".class" files instead of ".java" files

FileNode.createRoot("MyJavaPackages/")
        .loadTree()
        .flatten(-1, (FileNode fn) -> fn.name.endsWith(".class"), true, null, true)
        .forEach((FileNode fn)     -> System.out.println(fn.getFullPathName()));

 
// *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
// Num Children Example
// *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

FileNode fn = FileNode.createRoot("etc/").loadTree();
System.out.println("There are precisely " + fn.numDirChildren() + " sub-directories in etc/");
System.out.println("There are precisely " + fn.numFileChildren() + " files in etc/");


// *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
// Print the subdirectories of a particular nodes
// *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

FileNode fn = FileNode.createRoot("users/");
fn.loadTree();

System.out.println("The directory 'users/' has the following sub-directories:");
Iterator&lt;FileNode&gt; iter = fn.getDirContentsDirs(FileNode.RetTypeChoice.ITERATOR);
while (iter.hasNext()) System.out.println(iter.next().name);

System.out.println("And the following files:");
iter = fn.getDirContentsFiles();
while (iter.hasNext()) System.out.println(iter.next().name);
    See Also:
    Serialized Form


    • Field Detail

      • serialVersionUID

        🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static final long serialVersionUID
        This fulfils the SerialVersion UID requirement for all classes that implement Java's interface java.io.Serializable. Using the Serializable Implementation offered by java is very easy, and can make saving program state when debugging a lot easier. It can also be used in place of more complicated systems like "hibernate" to store data as well.
        See Also:
        Constant Field Values
        Code:
        Exact Field Declaration Expression:
         public static final long serialVersionUID = 1;

      • VERBOSE

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static boolean VERBOSE
        When this variable is TRUE debug and status information will be sent to Standard-Output.
        Code:
        Exact Field Declaration Expression:
         public static boolean VERBOSE = false;

      • name

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final java.lang.String name
        The name of the file or directory is saved/stored here
        Code:
        Exact Field Declaration Expression:
         public final String name;

      • isDirectory

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final boolean isDirectory
        If 'this' class-instance represents a directory in the BASH/UNIX or MS-DOS file system, this variable will be TRUE. When this field is set to FALSE, it means that 'this' instance is a file.
        Code:
        Exact Field Declaration Expression:
         public final boolean isDirectory;

      • parent

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        protected FileNode parent
        The parent/container 'FileNode' directory is saved here - like a pointer "tree".
        Code:
        Exact Field Declaration Expression:
         protected FileNode parent;

      • fileSize

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final long fileSize
        When a tree is loaded into memory, the size of each file is saved in this variable. It can be retrieved (and even changed).
        Code:
        Exact Field Declaration Expression:
         public final long fileSize;

      • lastModified

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final long lastModified
        When a tree is loaded into memory, the file-date of the file is saved in this variable. It can be retrieved. If the SecurityManager.checkRead(fileName) denies read access to the file, this field will equal zero.

        Time in Milli-Seconds: This field is a Java simple-type 'long' which represents the time the file was last modified, measured in Milli-Seconds since the epoch (00:00:00 GMT, January 1, 1970).
        Code:
        Exact Field Declaration Expression:
         public final long lastModified;

      • children

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        protected final java.util.Vector<FileNode> children
        This variable remains null for all instances of this class which represent 'files' on the underlying Operating-System, rather than 'directories.'

        On the other hand, if 'this' instance of FileNode represents an MS-DOS, Unix, or Apple File-System directory, then this field will be constructed / instantiated and hold all file and sub-directory FileNode-instances which contained by this directory.
        Code:
        Exact Field Declaration Expression:
         protected final Vector<FileNode> children;

      • HTML_FILES

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static final java.io.FilenameFilter HTML_FILES
        Implements the interface java.io.FilenameFilte, and can therefore be used within the loadTree method.

        Selects for files whose name ends with '.html', and is case-insensitive. This Predicate will match files ending in '.html', '.HTML', or even '.hTmL'.
        Code:
        Exact Field Declaration Expression:
         public static final FilenameFilter HTML_FILES = (File f, String name) ->
         StrCmpr.endsWithIgnoreCase(name, ".html");

      • CSS_FILES

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static final java.io.FilenameFilter CSS_FILES
        Implements the interface java.io.FilenameFilte, and can therefore be used within the loadTree method.

        Selects for files whose name ends with '.css', and is case-insensitive. This Predicate will match files ending in '.css', '.CSS', or even '.CsS'.
        Code:
        Exact Field Declaration Expression:
         public static final FilenameFilter CSS_FILES = (File f, String name) ->
         StrCmpr.endsWithIgnoreCase(name, ".css");

      • JAVA_FILES

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static final java.io.FilenameFilter JAVA_FILES
        Implements the interface java.io.FilenameFilte, and can therefore be used within the loadTree method.

        Selects for files whose name ends with '.java'. This particular filter is case-sensitive.
        Code:
        Exact Field Declaration Expression:
         public static final FilenameFilter JAVA_FILES = (File f, String name) ->
         name.endsWith(".java");

      • CLASS_FILES

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static final java.io.FilenameFilter CLASS_FILES
        Implements the interface java.io.FilenameFilte, and can therefore be used within the loadTree method.

        Selects for files whose name ends with '.class'. This particular filter is case-sensitive.
        Code:
        Exact Field Declaration Expression:
         public static final FilenameFilter CLASS_FILES = (File f, String name) ->
         name.endsWith(".class");

      • JSON_FILES

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static final java.io.FilenameFilter JSON_FILES
        Implements the interface java.io.FilenameFilte, and can therefore be used within the loadTree method.

        Selects for files whose name ends with '.json'. This particular filter is case-insensitive. This Predicate will match files ending in '.json', '.JSON', or even '.JsOn'.
        Code:
        Exact Field Declaration Expression:
         public static final FilenameFilter JSON_FILES = (File f, String name) ->
         StrCmpr.endsWithIgnoreCase(name, ".json");

      • SKIP_DIR_ON_SECURITY_EXCEPTION

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static boolean SKIP_DIR_ON_SECURITY_EXCEPTION
        Directories on a UNIX platform that were inaccessible didn't seem to throw a SecurityException, instead, a null-array was returned. However, in the case that Java's java.lang.SecurityManager is catching attempts to access restricted dirtectories and throwing exceptions (which is likely a rare case) - this boolean flag can inform the internal directory-scanner logic to catch these SecurityException's.

        If "catching and skipping" exceptions has been choosen, then any directory that is scanned and would throw an exception, instead is left empty by this class' tree-loading logic.

        Thread-Safety: This flag is a non-Thread-Safe feature, because it is a static-Field Flag that is applied to all instances of class FileNode.
        Code:
        Exact Field Declaration Expression:
         public static boolean SKIP_DIR_ON_SECURITY_EXCEPTION = false;

      • comp2

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static final java.util.Comparator<FileNode> comp2
        This is an "alternative Comparitor" that can be used for sorting instances of this class. It should work with the Collections.sort(List, Comparator) method in the standard JDK package java.util.*;

        Comparison Heuristic:
        This version utilizes the standard JDK String.compareToIgnoreCase(String) method.
        See Also:
        getFullPathName()
        Code:
        Exact Field Declaration Expression:
         public static final Comparator<FileNode> comp2 = (FileNode fn1, FileNode fn2) ->
         fn1.getFullPathName().compareToIgnoreCase(fn2.getFullPathName());

    • Constructor Detail

      • FileNode

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        protected FileNode​(java.lang.String name,
                   FileNode parent,
                   long lastModified)
        This constructor builds a FileNode object - which must be a FileNode-Directory instance and may not be a FileNode-File instance.

        FileNode-Directory:
        This instance will have a fileSize field whose value equals '0', and an isDirectory value set to FALSE.

        Directory-Name validity checks are not performed here. This constructor has a 'protected' access level, and is only called internally when a directory has been found by getter-calls to java.io.File (and therefore are extremely unlikely to be invalid).
        Parameters:
        name - The name of 'this' FileNode.
        parent - This is the parent or "container-directory" of 'this' FileNode. If a FileNode that is not a directory itself is passed as the parent, then an exception will be thrown.
        lastModified - This must be a long value indicating when the file was last modified - according to the Operating-System. This value may be '0', and if so, it indicates that this information was either not available, or a read of the value was not allowed by the Operating-System Security-Manager.

        Exact Method Body:
         this.name            = name;  
 this.parent          = parent;
 this.isDirectory     = true;
 this.fileSize        = 0;
 this.lastModified    = lastModified;
 this.children        = new Vector<>();

      • FileNode

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        protected FileNode​(java.lang.String name,
                   FileNode parent,
                   long fileSize,
                   long lastModified)
        This constructor builds a FileNode object which must be a FileNode-File instance - and may not be a FileNode-Directory instance.

        FileNode-File:
        The node that is instantiated will have an isDirectory value of FALSE.

        File-Name validity checks are not performed here. This constructor has a 'protected' access level, and is only called internally when a file has been found by getter-calls to java.io.File (and therefore are extremely unlikely to be invalid).
        Parameters:
        name - The name of 'this' FileNode
        parent - This is the parent or "container-directory" of 'this' FileNode. If a FileNode that is not a directory itself is passed as the parent, then an exception will be thrown.
        fileSize - The size of this file - in bytes.
        lastModified - This must be a long value indicating when the file was last modified - according to the Operating-System. This value may be '0', and if so, it indicates that this information was either not available, or a read of the value was not allowed by the Operating-System security manager.

        Exact Method Body:
         this.name            = name;  
 this.parent          = parent;
 this.isDirectory     = false;
 this.fileSize        = fileSize;
 this.lastModified    = lastModified;
 this.children        = null;

      • FileNode

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        protected FileNode​(java.lang.String name)
        This constructor builds a 'ROOT' FileNode instance. These instances are FileNode-Directories, but they do not have a parent / container FileNode.

        They function indentically to Directory-FileNode's in all other aspects.
        Parameters:
        name - The name of 'this' FileNode

    • Method Detail

      • createRoot

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static FileNode createRoot​(java.lang.String name)
        This is the "Factory Method" for this class. The String name parameter is intended to be the root directory-name from which the Complete FileNode-Tree should be built / constructed.

        The 'name' parameter passed to this method must be the actual name of an actual directory on the File-System.

        Load-Tree Methods:
        Once this Root-Node for a tree has been built (by invoking this method), the next thing to do is read any / all files & directories that reside on the File-System inside the directory into memory. This class provides several methods for both total and partial reads of a directory's contents.

        In the example below, the standard Tree-Loading method loadTree() is invoked in order to to read the entire contents of the specified File-System Directory into a FileNode-Tree in Java Memory.

        Example:
         FileNode fn = FileNode
      .createRoot("etc/MyDataFiles/user123/")
      .loadTree();
        Returns:
        An instance of this class from which a FileNode tree may be instantiated.
        Code:
        Exact Method Body:
         return new FileNode(name);

      • loadTree

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public FileNode loadTree​(boolean includeFiles,
                         boolean includeDirectories)
        Convenience Method
        Invokes: loadTree(int, FilenameFilter, FileFilter)
        Passes: 'includeFiles' as a Predicate to parameter 'fileFilter'
        Passes: 'includeDirectories' (as Predicate) to 'directoryFilter'
        Throws: IllegalArgumentException If both boolean parameters are FALSE
        Code:
        Exact Method Body:
         if ((! includeFiles) && (! includeDirectories)) throw new IllegalArgumentException(
     "loadTree(boolean, boolean) has been invoked with both search criteria booleans set " +
     "to FALSE.  This means that there is nothing for the method to do."
 );

 return loadTree
     (-1, (File dir, String name) -> includeFiles, (File file) -> includeDirectories);

      • loadTreeJustDirs

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public FileNode loadTreeJustDirs​(int maxTreeDepth,
                                 java.io.FileFilter directoryFilter)
        Convenience Method
        Invokes: loadTree(int, FilenameFilter, FileFilter)
        Passes: 'Always False' Predicate to parameter 'fileFilter'
        Accepts: A 'directoryFilter' and 'maxTreeDepth'
        Code:
        Exact Method Body:
         // Set the return value of the 'fileFilter' predicate to ALWAYS return FALSE.
 return loadTree(maxTreeDepth, (File dir, String name) -> false, directoryFilter);

      • loadTree

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public FileNode loadTree​(int maxTreeDepth,
                         java.io.FilenameFilter fileFilter,
                         java.io.FileFilter directoryFilter)
        This populates 'this' FileNode tree with the contents of the File-System directory represented by 'this'.

        Directory-FileNode: This method can only be invoked on an instance of 'FileNode' which represents a directory on the UNIX or MS-DOS File-System. A DirExpectedException shall throw if this method is invoked on a FileNode instance that represents a file.

        The following example was used to help search for a local copy of the Google Chrome Binaries on an instance of Google Cloud Server.

        Note that although the standard Shell instance on Google Cloud Server apparently does not have a copy of the chrome in its 'Headless' format, a lot of information can be viewed about a file-system's contents using the code below.

        Example:
        FileNode

    // Inside Google Cloud Shell, mostly a UNIX Platform, the Root UNIX directory is simply named
    // "/" (which happens to be the name of the System's File Separator).  Note that on MS-DOS
    // Systems, the root directory is named after the drive-letter.

    .createRoot(java.io.File.separator)


    // The directory tree takes several minutes to load, as the files-system actually contains
    // hundreds of thousands (if not millions) of files.
    //
    // This Line Provides Three Restrictions:
    //      - DO NOT GO MORE THAN SIX DIRECTORIES DEEP
    //      - DO NOT LOOK FOR ANY FILES - ONLY DIRECTORIES WHEN LOADING THIS TREE
    //      - ELIMINATE ANY DIRECTORIES NAMED "chrome-trace-event"

    .loadTreeJustDirs(6, f -> ! f.getName().contains("chrome-trace-event"))


    // Build a java.util.stream.Stream<String> containing the full-path name of each of these
    // directory names (as a java.lang.String)

    .flattenJustDirs(RetTypeChoice.FULLPATH_STREAM)

    // Filter all directories that are inside the Stream which do not contain the string "chrome"
    .filter(s -> s.contains("chrome"))

    // Print those directories to the terminal
    .forEach((String fileName) -> System.out.println(fileName));
        Parameters:
        maxTreeDepth - The value passed to 'maxTreeDepth' should be set to the maximum number of tree branches to follow, recursively, when traversing the the operating-system's directory-tree / file-system.
        'maxTreeDepth' Value Meaning
        (Any) Negative Integer Visit the directory-tree to its maximum depth; visit all leaf nodes (files).
        '0' (zero) Visit each branch (directory) and leaf node (file) of 'this' instance of FileNode, but do not enter any sub-directories.
        '1' (one) Visit each branch (directory) and leaf node (file) of 'this' instance of FileNode, and enter - recursively - any sub-directories that are found. Visit the contents of each of these branches - their files & directories - but do not enter any of those sub-directory tree-branches
        '2' ... 'n' Visit the children (both files & directories) of 'this' instance of FileNode, and enter - recursively - any sub-directories found. Apply this process, recursively, n-times.
        fileFilter - This is an interface from the java.io.* library. It can be used here to filter which files (not directories) are loaded into the tree.

        The public interface java.io.FilenameFilter has a method with this signature:

        Java Method Signature:
        public boolean test(File dir, String name)

        Where:

        • The File dir parameter represents the containing/parent directory.
        • The String name parameter represents the simple-name of the file not including the full path, or parent-directory.

        Note Regardig 'null': If this filter parameter is passed null, the parameter is ignored - and all files shall be included in the result, with no filtering applied.

        Furthermore: Consistent with other Java 'filter' mechanisms, the filter that is provided should be a lambda-expression or method that returns FALSE if the file should be skipped. If the file needs to be included - or 'kept' (and subsequently loaded into the tree), then your filter should return TRUE.
        .
        directoryFilter - This is an interface from the java.io.* library as well. It can be used here to filter which directories are visited by the recursion algorithm (it ignores files). If a directory fails the "boolean test" method here, that branch of the tree will not be included in this object.

        The public interface java.io.FileFilter has a method signature of:

        Java Method Signature:
        public boolean test(File file)

        Where:

        • File file parameter represents an actual UNIX (or MS-DOS) file.

        Note regarding null: If this filter parameter is null, the parameter is ignored - and all sub-directories are visited.

        The filter used should return FALSE if the passed directory should be skipped. The filter must return TRUE if the directory needs to be included, or 'kept', (and subsequently visited and loaded into the tree).
        Returns:
        a reference to 'this' FileNode, for convenience only. It's tree branches (directories) and leaf nodes (files) will be populated, as per the above parameter specification-criteria.
        Throws:
        DirExpectedException - This method will only execute if the instance of 'this' is a directory. Files on the File-System are leaves, not branches - so they do not have contents to load.
        java.lang.SecurityException - The method java.io.File.listFiles() is used to retrieve the list of files for each directory. That method asserts that the Java Security Managaer java.lang.SecurityManager may throw this exception if a restricted directory is accessed by 'listFiles()'.

        By-Pass Note: Those most common behavior for restricted directories has been for the listFiles() to simply return null, which is handled easily by this code. If this exception is throwing, one may use the internal (static flag) SKIP_DIR_ON_SECURITY_EXCEPTION. When this static-flag is used, SecurityExceptions are caught, and the contents of those directories will simply be ignored and eliminated from the tree.
        See Also:
        loadTree(), DirExpectedException.check(FileNode), SKIP_DIR_ON_SECURITY_EXCEPTION
        Code:
        Exact Method Body:
         DirExpectedException.check(this);

 loadTreeINTERNAL(maxTreeDepth, fileFilter, directoryFilter);

 return this;

      • numChildren

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public int numChildren()
        This returns the number of Child-Nodes in 'this' instance of FileNode.

        Non-Recursive: This method is not 'recursive', which means that the integer returned by this method is only a count of the number of direct-descendants of 'this' instance.

        Another way of saying this is that all it returns is the size of the internal children Vector. It doesn't actually enter any sub-directories to perform this count.
        Throws:
        DirExpectedException - If 'this' instance of FileNode is not a directory, but rather a file, then this exception is thrown. (Files may not have child-nodes, only directories may have them).
        See Also:
        numDirChildren(), numFileChildren(), children
        Code:
        Exact Method Body:
         DirExpectedException.check(this); return children.size();

      • numDirChildren

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public int numDirChildren()
        This returns the exact number of Child-Nodes of 'this' instance of FileNode which are directories.

        Non-Recursive: This method is not 'recursive', which means that the integer returned by this method is only a count of the number of direct-descendants of 'this' instance.

        This method performs a count on the elements of the internal children Vector to see how many elements have an isDirectory field set to TRUE.
        Throws:
        DirExpectedException - If 'this' instance of FileNode is not a directory, but rather a file, then this exception is thrown. (Files may not have child-nodes, only directories may have them).
        See Also:
        numFileChildren(), numChildren(), children
        Code:
        Exact Method Body:
         DirExpectedException.check(this);

 int dirCount = 0;

 for (int i=0; i < children.size(); i++) if (children.elementAt(i).isDirectory) dirCount++;

 return dirCount;

      • numFileChildren

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public int numFileChildren()
        This returns the exact number of Child-Nodes of 'this' instance of FileNode which are files.

        Non-Recursive: This method is not 'recursive', which means that the integer returned by this method is only a count of the number of direct-descendants of 'this' instance.

        This method performs a count on the elements of the internal children Vector to see how many elements have an isDirectory field set to FALSE.
        Throws:
        DirExpectedException - If 'this' instance of FileNode is not a directory, but rather a file, then this exception is thrown. (Files may not have child-nodes, only directories may have them).
        See Also:
        numDirChildren(), numChildren(), isDirectory, children
        Code:
        Exact Method Body:
         DirExpectedException.check(this);

 int fileCount = 0;

 for (int i=0; i < children.size(); i++)
     if (! children.elementAt(i).isDirectory)
         fileCount++;

 return fileCount;

      • dir

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public FileNode dir​(java.lang.String dirName,
                    boolean ignoreCase)
        Retrieves the sub-directory FileNode instance named by parameter 'dirName' if there is a FileNode that is a direct descendant of 'this' instance of FileNode.
        Parameters:
        dirName - This is the name of any directory.

        Important: This must be the name-only leaving out all parent-directory or drive-letter text.

        Furthermore: The forward slash ('/') or the back-slash ('\') character that sometimes is appended to a directory-name may not be included in this name (unless a forward-slash or back-slash is a part of the name of the directory).
        ignoreCase - For some files and directories, on some operating systems (Microsoft Windows, for instance) File-System name case is not considered relevant when matching directory names. If this parameter is passed TRUE, then name comparisons will use a case-insensitive comparison mechanism.
        Returns:
        The child FileNode (sub-directory) of this directory whose name matches the name provided by parameter 'dirName'.

        If no matching directory is found, then this method shall return null.
        Throws:
        DirExpectedException - If 'this' instance of FileNode is a file, not a directory, then this exception shall throw. Only directories can contain other instances of FileNode.
        See Also:
        children, isDirectory, name
        Code:
        Exact Method Body:
         // Only directories may contain other instances of FileNode
 DirExpectedException.check(this);

 // We are looking for a directory named 'dirName'
 //
 // IMPORTANT: The outer squiqgly-braces are MANDATORY.  Without them, there is 
 //            "deceptive indentation," because the 'else' is paired with the second-if,
 //            not the first!

 if (ignoreCase)
 {
     for (FileNode fn : children)
         if (fn.isDirectory && fn.name.equalsIgnoreCase(dirName)) return fn;
 }

 else
 {
     for (FileNode fn2 : children)
         if (fn2.isDirectory && fn2.name.equals(dirName)) return fn2;
 }

 // Not found, return null.
 return null;

      • file

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public FileNode file​(java.lang.String fileName,
                     boolean ignoreCase)
        Retrieves a FileNode named by parameter 'fileName' if there is a FileNode instance that is a direct descendant of 'this' FileNode that is, itself, a file and not a directory.
        Parameters:
        fileName - This is the name of any file.

        Important: This must be the name-only, leaving out all parent-directory or drive-letter text.
        ignoreCase - For some files and directories, on some operating systems (Microsoft Windows, for instance) file-name case is not considered relevant when matching file names. If this parameter is passed TRUE, then file-name comparisons will use a case-insensitive comparison mechanism.
        Returns:
        An instance of FileNode that is a direct-descendant of 'this' directory - and whose name matches the name provided by parameter 'fileName'.

        If no matching file is found, then this method shall return null.
        Throws:
        DirExpectedException - If 'this' instance of FileNode is a file, not a directory, then this exception shall throw. Only directories can contain other instances of FileNode.
        See Also:
        children, isDirectory, name
        Code:
        Exact Method Body:
         // Only directories may contain other instances of FileNode
 DirExpectedException.check(this);

 // We are looking for a file named 'fileName'
 //
 // IMPORTANT: The outer squiqly-braces are MANDATORY.  Without them, there is 
 //            "deceptive indentation," because the 'else' is paired with the second-if,
 //            not the first!

 if (ignoreCase)
 {
     for (FileNode fn : children)
         if ((! fn.isDirectory) && fn.name.equalsIgnoreCase(fileName)) return fn;
 }

 else
 {
     for (FileNode fn2 : children)
         if ((! fn2.isDirectory) && fn2.name.equals(fileName)) return fn2;
 }

 // Not found, return null.
 return null;

      • findFirst

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public FileNode findFirst​(FileNodeFilter f)
        Searches a FileNode, looking for any branch (directory) or leaf-node (file) that positively matches the provided filter parameter 'f'. Exits and returns immediately upon finding such a match.

        Here, a Source-Code Directory is searched for the first file or directory that is found which has a lastModified value greater than 12:01 AM, today.

        Example:
         // Create a LocalDateTime object for 12:01 AM of today, and converts that to milliseconds
 // From the Java Time Package (java.time.*)
 
 final long TODAY = LocalDateTime
      .of(LocalDate.now(), LocalTime.of(0, 1));
      .toInstant(ZoneOffset.UTC).toEpochMilli();
 
 String todaysFile = FileNode
      .createRoot("src/main/")
      .loadTree()
      .findFirst((FileNode fn) -> fn.lastModified >= TODAY)
      .getFullPathName();
        Parameters:
        f - Any filter may be used for selecting the file instance being searched.
        Returns:
        The first FileNode instance in 'this' tree that matches the provided filter-predicate.

        If no matching node is found, then this method shall return null.
        Throws:
        DirExpectedException - If 'this' instance of FileNode is a file, not a directory, then this exception shall throw. Only directories can contain other instances of FileNode.
        See Also:
        children, isDirectory
        Code:
        Exact Method Body:
         // Only directories may contain other instances of FileNode
 DirExpectedException.check(this);

 return ffINTERNAL(f);

      • findFirstDir

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public FileNode findFirstDir​(FileNodeFilter f)
        Traverses 'this' tree instance looking for any FileNode instance that is a directory, and matches the filter selector parameter 'f' predicate 'test' method.

        This method will exit and return the first such match it encounters in the tree.

        In the example below, a FileNode-Tree is built out of one particular 'src/main' directory, and then that entire directory is searched for any sub-folder (anywhere in the sub-tree) whose name is equal to 'MyImportantClasses'.

        Example:
         FileNode myFolder = FileNode
      .createRoot("My Source Code/src/main/")
      .loadTree()
      .findFirstDir((FileNode fn) -> fn.name.equals("MyImportantClasses"))


        In this example, a local directories' "sub-tree" is searched for any sub-folder that has at least 15 non-directory files inside.

        Example:
         FileNode atLeast10 = FileNode
      .createRoot("My Saved PDFs")
      .loadTree()
      .findFirstDir((FileNode fn) -> fn.numFileChildren() >= 15);
        Parameters:
        f - Any filter may be used for selecting the FileNode directory instance being searched.
        Returns:
        The first FileNode instance in 'this' tree whose isDirectory flag is TRUE and, furthermore, matches the provided filter-predicate.

        If no matching directory is found, then this method shall return null.
        Throws:
        DirExpectedException - If 'this' instance of FileNode is a file, not a directory, then this exception shall throw. Only directories can contain other instances of FileNode.
        See Also:
        children, isDirectory
        Code:
        Exact Method Body:
         // Only directories may contain other instances of FileNode
 DirExpectedException.check(this);

 return ffdINTERNAL(f);

      • findFirstFile

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public FileNode findFirstFile​(FileNodeFilter f)
        This method is extremely similar to findFirstDir(FileNodeFilter), but searches for leaf-node files, instead of sub-folders / directories.
        Parameters:
        f - Any filter may be used for selecting the file instance being searched.
        Returns:
        The first FileNode instance in 'this' tree whose isDirectory flag is FALSE and, furthermore, matches the provided filter-predicate.

        If no matching directory is found, then this method shall return null.
        Throws:
        DirExpectedException - If 'this' instance of FileNode is a file, not a directory, then this exception shall throw. Only directories can contain other instances of FileNode.
        See Also:
        children, isDirectory
        Code:
        Exact Method Body:
         // Only directories may contain other instances of FileNode
 DirExpectedException.check(this);

 return fffINTERNAL(f);

      • pollDir

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public FileNode pollDir​(java.lang.String dirName,
                        boolean ignoreCase)
        Retrieves the sub-directory FileNode instance named by parameter 'dirName' if there is a FileNode that is a Direct Descendant of 'this' instance of FileNode.

        Differences:
        This method will return identical results as the method dir(String, boolean) However, the difference between the two is that this one will actually "extract" the identified directory from 'this' tree before returning it.

        If and when a directory is found among 'this' tree instance' children that matches the requirements specified by parameters 'name' and 'ignoreCase', that match will be returned as this method's result.

        Before the matching-node is returned, it's parent FileNode reference-field will be set null. It will also be removed from the list of child-nodes contained by 'this' instance list of child-nodes.
        Parameters:
        dirName - This is the name of any directory.

        Important: This must be the name-only, leaving out all parent-directory or drive-letter text.

        Furthermore: The forward slash ('/') or the back-slash ('\') character that sometimes is appended to a directory-name may not be included in this name (unless a forward-slash or back-slash is a part of the name of the directory).

        When this directory is extracted, none of the child pointers contained by this directory-instance of FileNode will be modified. In essence, the entire sub-tree - starting at the directory that was specified - will be extracted from the parent-tree. Any / all contents of the sub-tree shall be in the same state as they were prior to the extraction.
        ignoreCase - For some files and directories, on some operating systems (Microsoft Windows, for instance) File-System name case is not considered relevant when matching directory names. If this parameter is passed TRUE, then name comparisons will use a case-insensitive comparison mechanism.
        Returns:
        The child FileNode (sub-directory) of 'this' directory whose name matches the name provided by parameter 'dirName'. It's 'parent' field will be null, and the parent FileNode instance will not have a pointer to the instance that is returned.

        If no matching directory is found, then this method shall return null.
        Throws:
        DirExpectedException - If 'this' instance of FileNode is a file, not a directory, then this exception shall throw. Only directories can contain other instances of FileNode.
        See Also:
        dir(String, boolean), children
        Code:
        Exact Method Body:
         FileNode ret = dir(dirName, ignoreCase);

 if (ret != null)
 {
     children.remove(ret);
     ret.parent = null;
 }

 return ret;

      • pollFile

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public FileNode pollFile​(java.lang.String fileName,
                         boolean ignoreCase)
        Retrieves a FileNode instance named by parameter 'fileName' if there is a FileNode that is a Direct Descendant of 'this' instance of FileNode, and that instance is a file (not a directory) whose name matches parameter 'fileName'.

        Differences:
        This method will return identical results as the method file(String, boolean) However, the difference between the two is that this one will actually "extract" the identified file from 'this' tree before returning it.

        If and when a file is found among 'this' tree instance' children that matches the requirements specified by parameters 'name' and 'ignoreCase', that match will be returned as this method's result.

        Before the matching-node is returned, it's parent FileNode reference-field will be set null. It will also be removed from the list of child-nodes contained by 'this' instance list of child-nodes.
        Parameters:
        fileName - This is the name of any file.

        IMPORTANT: This must be the name-only leaving out all parent-directory or drive-letter text.
        ignoreCase - For some files and directories, on some operating systems (Microsoft Windows, for instance) File-System name case is not considered relevant when matching file-names. If this parameter is passed TRUE, then name comparisons will use a case-insensitive comparison mechanism.
        Returns:
        The child FileNode of 'this' directory whose name matches the name provided by parameter 'fileName'. It's 'parent' field will be null, and the parent FileNode instance will not have a pointer to the instance that is returned.

        If no matching file is found, then this method shall return null.
        Throws:
        DirExpectedException - If 'this' instance of FileNode is a file, not a directory, then this exception shall throw. Only directories can contain other instances of FileNode.
        See Also:
        file(String, boolean)
        Code:
        Exact Method Body:
         FileNode ret = file(fileName, ignoreCase);

 if (ret != null)
 {
     children.remove(ret);
     ret.parent = null;
 }

 return ret;

      • pollThis

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public FileNode pollThis()
        Extracts 'this' FileNode from its parent's tree.
        Returns:
        returns 'this' for convenience.
        Code:
        Exact Method Body:
         if (this.parent == null) throw new FileNodeException 
     ("Attempting to poll a FileNode, but it's directory-parent FileNode is null");

 boolean             removed = false;
 Iterator<FileNode>  iter    = this.parent.children.iterator();

 while (iter.hasNext())
 {
     FileNode fn = iter.next();

     if (fn == this)
     {
         iter.remove();
         removed = true;
         break;
     }
 }

 // This is a simple-variant on Java's assert statement.  It is saying that the parent
 // FileNode better know where its children are, or else it means this FileNode tree has
 // some kind of bug.

 if (! removed) throw new UnreachableError();

 // Erase this node's parent
 this.parent = null;

 return this;

      • hashCode

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public int hashCode()
        This satisfies Java's "hash-code" method requirement. This can facilitate saving instances of this class into tables, maps, lists, etc.
        Overrides:
        hashCode in class java.lang.Object
        Returns:
        A hash-code to be used by a hash-algorithm with likely few crashes. Note that the hash from Java's java.lang.String is simply reused.
        Code:
        Exact Method Body:
         return toString().hashCode();

      • equals

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final boolean equals​(java.lang.Object o)
        Overrides:
        equals in class java.lang.Object
        Code:
        Exact Method Body:
         FileNode other;

 return (this == o)
     ||  ((o != null)
     &&  (this.getClass().equals(o.getClass()))
     &&  ((other = (FileNode) o).name.equals(this.name))
     &&  (this.parent        == other.parent)        // NOTE: A "Reference Comparison"
     &&  (this.isDirectory   == other.isDirectory)
     &&  (this.fileSize      == other.fileSize)
     &&  (this.lastModified  == other.lastModified)
     &&  this.name.equals(other.name)
     &&  (   ((this.children == null) && (other.children == null))
         ||  (this.children.equals(other.children)))
 );

      • clone

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public FileNode clone()
        Java's interface Cloneable requirements. This instantiates a new FileNode with identical fields. The field Vector<FileNode> 'children' shall be cloned too.
        Overrides:
        clone in class java.lang.Object
        Returns:
        A new FileNode whose internal fields are identical to this one.

        IMPORTANT (DEEP-CLONE) NOTE: This does not perform a deep-tree-traversal clone. Instead, 'this' instance is merely copied, and it's child nodes have references inserted into the internal list of child-nodes.
        See Also:
        name, parent, isDirectory
        Code:
        Exact Method Body:
         if (this.isDirectory)
 {
     FileNode ret = new FileNode(this.name, this.parent, this.lastModified);
     ret.children.addAll(this.children);
     return ret;
 }

 else
     return new FileNode(this.name, this.parent, this.fileSize, this.lastModified);

      • compareTo

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final int compareTo​(FileNode fn)
        Java's Comparable<T> Interface-Requirements. This does a very simple comparison using the results to a call of method getFullPathName()
        Specified by:
        compareTo in interface java.lang.Comparable<FileNode>
        Parameters:
        fn - Any other FileNode to be compared to 'this' FileNode. The file or directories getFullPathName() is used to perform a "String" comparison.
        Returns:
        An integer that fulfils Java's interface Comparable<T> public boolean compareTo(T t) method requirements.
        See Also:
        getFullPathName()
        Code:
        Exact Method Body:
         return this.getFullPathName().compareTo(fn.getFullPathName());

      • toString

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.lang.String toString()
        Converts 'this' FileNode to a String.
        Specified by:
        toString in interface java.lang.CharSequence
        Overrides:
        toString in class java.lang.Object
        Returns:
        The complete-full path-name of this file or directory.
        Code:
        Exact Method Body:
         return this.getFullPathName();

      • charAt

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final char charAt​(int index)
        Returns the char value at the specified index of the results to a call of method getFullPathName(). An index ranges from zero to length() - 1. The first char value of the sequence is at index zero, the next at index one, and so on and so forth - as per array indexing.

        Character Surrogates: If the char value specified by the index is a surrogate, the surrogate value is returned.

        Final Method:
        This method is final, and cannot be modified by sub-classes.
        Specified by:
        charAt in interface java.lang.CharSequence
        Parameters:
        index - The index of the char value to be returned
        Returns:
        The specified char value
        See Also:
        getFullPathName()
        Code:
        Exact Method Body:
         return this.getFullPathName().charAt(index);

      • length

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final int length()
        Returns the length of the String returned by public String getFullPathName() The length is the number of 16-bit characters in the sequence.

        Final Method:
        This method is final, and cannot be modified by sub-classes.
        Specified by:
        length in interface java.lang.CharSequence
        Returns:
        the number of characters in the "Full Path Name" for 'this' file or\ directory.
        See Also:
        getFullPathName()
        Code:
        Exact Method Body:
         return this.getFullPathName().length();

      • subSequence

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final java.lang.CharSequence subSequence​(int start,
                                                int end)
        Returns a java.lang.CharSequence that is a subsequence of the results to a call of method getFullPathName()

        The subsequence starts with the char value at the specified index and ends with the char value at index 'end - 1'. The length (in characters) of the returned sequence is 'end - start', so in the case where 'start == end' then an empty sequence is returned.

        Final Method:
        This method is final, and cannot be modified by sub-classes.
        Specified by:
        subSequence in interface java.lang.CharSequence
        Parameters:
        start - The start index, inclusive
        end - The end index, exclusive
        Returns:
        The specified subsequence
        See Also:
        getFullPathName()
        Code:
        Exact Method Body:
         return this.getFullPathName().substring(start, end);

      • deepClone

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public FileNode deepClone()
        Whereas the standard Java clone() method in this class returns a new, cloned, instance of FileNode, if 'this' instance of FileNode is a directory, the tree-branch represented by 'this' FileNode instance would not be copied by an invocation of 'clone'. However, if using this method, 'deepClone', on a directory-FileNode instance, the entire tree-branch represented by 'this' FileNode instance is copied..

        Deep-Clone: The method's clone() and deepClone() shall return identical results when used on an instance of FileNode that represents a file, rather than a directory (and, therefore, does not have any tree-branch information associated with it).
        Returns:
        a "Deep Clone" of 'this' FileNode instance. If 'this' instance of FileNode represents a file, not a directory, the results of this method shall be identical to the results of an invocation of the standard 'clone()' method. If 'this' FileNode represents an operation-system directory (not a file), then each and every child of this tree-branch shall also be copied / cloned by this method.
        Code:
        Exact Method Body:
         if (this.isDirectory)
 {
     FileNode ret = new FileNode(this.name, this.parent, this.lastModified);
     for (FileNode child : children) ret.children.add(child.deepClone());
     return ret;
 }

 else return this.clone();

      • nameNoExt

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.lang.String nameNoExt()
        This returns the name of the file, but leaves off the "extension"
        Returns:
        Returns the name without the file-extension
        Throws:
        FileExpectedException - Since only files may have extensions, if 'this' instance of FileNode is a directory, the FileExpectedException will throw.
        Code:
        Exact Method Body:
         FileExpectedException.check(this);  // Directories do not have extensions

 int pos = name.lastIndexOf('.');

 if (pos == -1) return name;

 return name.substring(0, pos);

      • ext

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.lang.String ext​(boolean includeTheDot)
        This returns the extension of the file. If this file does not have an extension, then null shall be returned.
        Parameters:
        includeTheDot - if the user would like to have the '.' included in the return String, then TRUE should be passed to this parameter.
        Returns:
        Returns this file's extension
        Throws:
        FileExpectedException - Since only files may have extensions, if 'this' instance of FileNode is a directory, the FileExpectedException will throw.
        Code:
        Exact Method Body:
         FileExpectedException.check(this);  // Directories do not have extensions

 int pos = name.lastIndexOf('.');

 if (pos == -1) return null;

 return includeTheDot ? name.substring(pos) : name.substring(pos+1);

      • forEach

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public void forEach​(java.util.function.Consumer<FileNode> c)
        Invokes the input Java Consumer<FileNode> on each element in 'this' FileNode-Tree. Note that if 'this' instance of is a file, not a directory, then the passed Consumer shall only be invoked once (on 'this' instance, since files do not have sub-directories).
        Parameters:
        c - This is any java Consumer<FileNode>
        Code:
        Exact Method Body:
         c.accept(this);
 if (children != null) children.forEach((FileNode fn) -> fn.forEach(c));

      • printTree

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public void printTree​(java.lang.Appendable a,
                      boolean showSizes,
                      FileNodeFilter fileTest,
                      FileNodeFilter directoryTest)
               throws java.io.IOException
        This will print the directory tree to the java.lang.Appendable passed as a parameter. Specific Test-Predicate's may be sent to this method to identify which branches of the File-System Directory-Tree should be printed.
        Parameters:
        a - If this is null, then System.out is used. If it is not null, then information is printed to this Java java.lang.Appendable. This expects an implementation of Java's java.lang.Appendable interface which allows for a wide range of options when logging intermediate messages.
        Class or Interface Instance Use & Purpose
        'System.out' Sends text to the standard-out terminal
        Torello.Java.StorageWriter Sends text to System.out, and saves it, internally.
        FileWriter, PrintWriter, StringWriter General purpose java text-output classes
        FileOutputStream, PrintStream More general-purpose java text-output classes

        Checked IOException:
        The Appendable interface requires that the Checked-Exception IOException be caught when using its append(...) methods.
        showSizes - If this is true, then "file-size" information will also be printed with the file.
        fileTest - If this is null, then it is ignored, and all files in the FileNode Directory-Tree pass (are accepted).

        If this parameter is not null, then each FileNode that is not a directory is run through this Predicate's test method. If the test returns FALSE, then this file is not printed to the output.
        directoryTest - If this is null, then it is ignored, and all directories in the FileNode Directory-Tree pass (are accepted).

        If this parameter is not null, then each FileNode that is a directory is run through this Predicate's test method, and any directories that fail this Predicate's test() method (when directoryTest.test(dir) returns FALSE), that directory will not be printed to the output.
        Throws:
        java.io.IOException - Java's interface Appendable mandates that the unchecked Java IOException must be caught when using this interface.
        See Also:
        printTree(), getDirContentsFiles(), getDirContentsDirs(), fileSize, getFullPathName()
        Code:
        Exact Method Body:
         if (a == null) a = System.out;

 for (FileNode file : getDirContentsFiles(fileTest))
     a.append((showSizes ? (file.fileSize + ",\t") : "") + file.getFullPathName() + '\n');

 for (FileNode dir : getDirContentsDirs(directoryTest))
 {
     a.append(dir.getFullPathName() + '\n');
     dir.printTree(a, showSizes, fileTest, directoryTest);
 }

      • getDirContentsSize

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public long getDirContentsSize​(FileNodeFilter fileTest)
        This sums the file-sizes of each file in the current directory, not sub-directories that pass the requirements of the Predicate<FileNode> here. If p.test(fileNode) fails, then the size of a FileNode is not counted in the total sum.

        Non-Recursive Method: This only retrieves the contents of 'this' directory - and does not expand or visit any sub-directories - when computing the total size of the files!
        Parameters:
        fileTest - Any Java Lambda-Expression that satisfies the requirement of having a public boolean test(FileNode); method. An instance of the interface 'FileNodeFilter' will also work.

        This is used to "test" whether to include the files in a directory' fileSize in the summed return value. When TRUE is returned by the Predicate test(...) method, a file's size will be included in the sum-total directory-size. When the Predicate test(...) method returns FALSE, the tested file's size will be ignored and not included in the total.

        This may be null, and if it is, it is ignored. This means that file-sizes for all files in the directory will count towards the total-size returned by this method.
        Returns:
        The sum of file-sizes for each file which passes the Predicate test in this directory.
        Throws:
        DirExpectedException - If 'this' instance of FileNode is not a directory, but rather a file, then this exception is thrown. (Files may not have child-nodes, only directories).
        See Also:
        fileSize, children, isDirectory
        Code:
        Exact Method Body:
         DirExpectedException.check(this);

 long size=0;           

 for (FileNode f : children)
     if (! f.isDirectory)
         if ((fileTest == null) || fileTest.test(f))
             size += f.fileSize;

 return size;

      • getDirTotalContentsSize

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public long getDirTotalContentsSize​(FileNodeFilter fileTest,
                                    FileNodeFilter directoryTest)
        This sums the file contents in the current directory - and all sub-directories as well. Only files that pass the Predicate 'fileTest' parameter are counted. Furthermore, only directories that pass the Predicate 'directoryTest' will be traversed and inspected.

        Recursive Method: This method computes the sizes of the files, recursively. Tbis method enters sub-directories (provided they pass the 'directoryTest') to compute the total file size.
        Parameters:
        fileTest - Any Java Lambda-Expression that satisfies the requirement of having a public boolean test(FileNode); method. An instance of the interface 'FileNodeFilter' will also work.

        This is used to "test" whether to include the fileSize for a specific file in a directory in the summed return value. When TRUE is returned by the Predicate 'test' method, a file's size will be included in the sum-total directory-size. When the Predicate 'test' method returns FALSE, the tested file's size will be ignored, and not included in the total.

        This may be null, and if it is, it is ignored. This means that file-sizes for all files in the directory will count towards the total-size returned by this method.
        directoryTest - Any Java Lambda-Expression that satisfies the requirement of having a public boolean test(FileNode); method. An instance of the interface 'FileNodeFilter' will also work.

        This is used to test directories, rather than files, for inclusion in the total file-size returned by this method. When TRUE is returned by the filter's 'test' method, then that directory shall be traversed, inspected, and its contents shall have their fileSize's included in the computed result.

        This parameter may be null, and if it is, it is ignored. This would mean that all sub-directories shall be traversed when computing the total directory size.
        Returns:
        The sum of all file-sizes for each file in this directory that pass 'fileTest', and all sub-dir's that pass the 'directoryTest'.
        Throws:
        DirExpectedException - If 'this' instance of FileNode is not a directory, but rather a file, then this exception is thrown. (Files may not have child-nodes, only directories). (
        See Also:
        fileSize, children, getDirTotalContentsSize()
        Code:
        Exact Method Body:
         DirExpectedException.check(this);

 long size=0;

 for (FileNode f : children)

     if (f.isDirectory)
     {
         if ((directoryTest == null) || directoryTest.test(f))
             size += f.getDirTotalContentsSize(fileTest, directoryTest);
     }

     else
     {
         if ((fileTest == null) || fileTest.test(f))
             size += f.fileSize;
     }                 

 return size;

      • count

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public int count​(FileNodeFilter fileFilter,
                 FileNodeFilter directoryFilter)
        Performs a count on the total number of files and directories contained by 'this' directory. This method is recursive, and traverses both 'this' directory, and all sub-directories when calculating the return-value.
        Parameters:
        fileFilter - This allows a user to eliminate certain files from the total count.

        The filter provided should be a Predicate<FileNode> that returns TRUE if the file should be counted, and FALSE if the file should not be counted.

        This parameter may be 'null', and if it is, it will be ignored. In such cases, all files will be included in the total count.
        directoryFilter - This allows a user to skip branches of the directory-tree when performing the count.

        The filter provided should be a Predicate<FileNode> that returns TRUE if the sub-directory should be entered (and counted), and FALSE if the sub-directory tree-branch should be skipped completely.

        This parameter may be 'null', and if it is, it will be ignored. In such cases, all sub-directory branches will be included when computing the total count.

        When this filter-parameter returns FALSE, the entire sub-directory tree-branch will be skipped completely. Any branches of the directory-tree that would actually pass the 'directoryFilter' test are rendered irrelevant if a parent sub-directory branch has failed the 'directoryFilter' test.
        Returns:
        A total count of all files and sub-directories contained by 'this' instance of FileNode - less the files and directory-tree branches that were excluded by the filters that may or may not have been passed to this method.
        Throws:
        DirExpectedException - If the user has attempted to perform a count on a FileNode that is a 'file' rather than a 'directory'.
        Code:
        Exact Method Body:
         DirExpectedException.check(this);

 // This was moved to an "INTERNAL" method to avoid invoking the above exception check
 // every time this (recursive) code encounters a directory.

 return countINTERNAL(fileFilter, directoryFilter);

      • countJustFiles

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public int countJustFiles​(FileNodeFilter fileFilter,
                          FileNodeFilter directoryFilter)
        Performs a count on the total number of files only (does not count sub directories) contained by 'this' directory. This method is recursive, and traverses both 'this' directory, and all sub-directories when calculating the return-value.
        Parameters:
        fileFilter - This allows a user to eliminate certain files from the total count.

        The filter provided should be a FileNodeFilter (Predicate} / Lambda-Expression that returns TRUE if the file should be counted, and FALSE if the file should not be counted.

        This parameter may be 'null', and if it is, it will be ignored. In such cases, all files will be included in the total count.
        directoryFilter - This allows a user to skip branches of the directory-tree when performing the count.

        The filter provided should be a FileNodeFilter (Predicate} / Lambda-Expression that returns TRUE if the sub-directory should be entered (the directory itself will not contribute to the count). When this filter returns FALSE the sub-directory tree-branch will be skipped completely, and any files in those sub-directories will not contribute to the total file-count.

        This parameter may be 'null', and if it is, it will be ignored. In such cases, all sub-directory branches will be included when computing the total count.

        When this filter-parameter returns FALSE, the entire sub-directory tree-branch will be skipped completely. Any branches of the directory-tree that would actually pass the 'directoryFilter' test are rendered irrelevant if a parent sub-directory branch has failed the 'directoryFilter' test.
        Returns:
        A total count of all files (excluding sub-directories) contained by 'this' instance of FileNode - less the files that reside in directory-tree branches that were excluded by the 'directoryFilter' parameter and less the files that were excluded by 'fileFilter'.
        Throws:
        DirExpectedException - If the user has attempted to perform a count on a FileNode that is a 'file' rather than a 'directory'.
        Code:
        Exact Method Body:
         DirExpectedException.check(this);

 // This was moved to an "INTERNAL" method to avoid invoking the above exception check
 // every time this (recursive) code encounters a directory.

 return countJustFilesINTERNAL(fileFilter, directoryFilter);

      • countJustDirs

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public int countJustDirs​(FileNodeFilter directoryFilter)
        Performs a count on the total number of sub-directories contained by 'this' directory. This method is recursive, and traverses all sub-directories when calculating the return-value.
        Parameters:
        directoryFilter - This allows a user to skip branches of the directory-tree when performing the count.

        The filter provided should be a FileNodeFilter (Predicate} / Lambda-Expression that returns TRUE if the sub-directory should be entered and FALSE if sub-directory tree-branch should be skipped completely.

        This parameter may be 'null', and if it is, it will be ignored. In such cases, all sub-directory branches will be included when computing the total count.

        When this filter-parameter returns FALSE, the entire sub-directory tree-branch will be skipped completely. Any branches of the directory-tree that would actually pass the 'directoryFilter' test are rendered irrelevant if a parent sub-directory branch has failed the 'directoryFilter' test.
        Returns:
        A total count of all sub-directories contained by 'this' instance of FileNode - less the sub-directories that reside in directory-tree branches that were excluded by the 'directoryFilter' parameter.
        Throws:
        DirExpectedException - If the user has attempted to perform a count on a FileNode that is a 'file' rather than a 'directory'.
        Code:
        Exact Method Body:
         DirExpectedException.check(this);

 // This was moved to an "INTERNAL" method to avoid invoking the above exception check
 // every time this (recursive) code encounters a directory.

 return countJustDirsINTERNAL(directoryFilter);

      • getDirContents

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public <T> T getDirContents​(RTC<T> returnedDataStructureChoice)
        Convenience Method
        Accepts: RTC. (Specifies Output Data-Structure & Contents)
        Invokes: getDirContents(RTC, FileNodeFilter)
        Passes: null to parameter 'filter' (all files and directories found will be returned).
        Code:
        Exact Method Body:
         return getDirContents(returnedDataStructureChoice, null);

      • getDirContents

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public <T> T getDirContents​(RTC<T> returnedDataStructureChoice,
                            FileNodeFilter filter)
        This method returns the contents of a single-directory in the directory-tree, the sub-directories are returned, but the contents of the sub-directories are not. Any method whose name begins with 'getDirContents ...' will not traverse the directory tree. Instead, only the contents of the internal 'children' Vector<FileNode> of 'this' instance of FileNode are iterated and returned.

        This method may only be invoked on FileNode instances which, themselves, represent directories on the File-System, not files. If this method is erroneously invoked on a 'file' instead of a 'directory', you should expect a DirExpectedException exception to throw. Remember: files on the file-system do not have 'contents' (specifically: other files and sub-directories), only directories may contain them.

        Non-Recursive Method:
        This method does not recursively traverse the directory-tree. The search logic of any getDirContents method will only visit the contents of 'this' FileNode instance (the one on which this method was invoked).

        To retrieve a list, collection, stream or array of the entire directory-tree rooted at 'this' instance, instead use one of the flatten methods.
        Type Parameters:
        T - This type parameter may be chosen using the methods in class RTC. The methods in that class each return an instance of RTC. The Generic-Type Parameter of class RTC specify, exactly, what this method's ultimate Return-Type will be. There are many, many options provided in that class for deciding exactly how this returned File-System Information is represented.
        Parameters:
        returnedDataStructureChoice - This allows the user to choose a particular Data-Container or List, such as Vector, Stream, or Array as a desired Return-Type for this method.

        In addition to the Data-Container, you may use this parameter to request that the output be sorted using a set of pre-selected sort Comparator's. You may also request that the data be converted to a String-Format (rather than a FileNode) that contains either the File-Name as a String, or the Full-Path (Complete) File-Name.

        See: class RTC for details.
        filter - When this parameter is used, any files or directories that do not pass the filter's 'test' method shall not be included in the returne data-structure.

        The filter that is passed should return TRUE when a file or directory needs to be included in the returned-result. When the provided filter returns FALSE as a result of testing a file or directory, the returned Data-Structure will exclude it.

        If this parameter is null, it will be ignored, and every FileNode contained by 'this' directory-instance will be included in the result.
        Returns:
        A list containing the files & sub-directories inside 'this' directory.

        class RTC allows a user of this API to specify this method's Return-Type. There are dozens of options included for choosing which Reference-Container Type to return, what Sorting-Method to employ, and even for selecting the how the FileNode instances are returned: File-Name String Full-PathString, FileNode etc..

        See: class RTC for details
        Throws:
        DirExpectedException - This exception will throw if 'this' FileNode instance is representing a file, rather than a directory. It is (hopefully) obvious that files may not have child-nodes (other files and directories), only directories may have them.
        See Also:
        FileNodeFilter, children
        Code:
        Exact Method Body:
         DirExpectedException.check(this);

 if (filter != null)
     children.forEach((FileNode fn) ->
         { if (filter.test(fn)) returnedDataStructureChoice.inserter.accept(fn); });

 else 
     children.forEach((FileNode fn) -> returnedDataStructureChoice.inserter.accept(fn));

 return returnedDataStructureChoice.finisher.get();

      • getDirContentsDirs

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public <T> T getDirContentsDirs​(RTC<T> returnedDataStructureChoice,
                                FileNodeFilter filter)
        This method is nearly identical to the method getDirContents(FileNodeFilter). This method, alternatively, will 'logically-and' a filter that first eliminates any and all FileNode instances which, themselves, represent 'files'. This method will preclude 'files' from passing the user-provided filter-logic test (and thereby prevent 'files' from being included in the result-set). Only directories can be members of the returned data-structure.

        This method only returns the contents of a single-directory in the directory-tree. Any directories in sub-directories will not be retrieved.

        This method may only be invoked on FileNode instances which, themselves, represent directories on the File-System, not files. If this method is erroneously invoked on a 'file' instead of a 'directory', you should expect a DirExpectedException exception to throw. Remember: files on the file-system do not have 'contents' (specifically: other files and sub-directories), only directories may contain them.

        Non-Recursive Method:
        This method does not recursively traverse the directory-tree. The search logic of any getDirContents method will only visit the contents of 'this' FileNode instance (the one on which this method was invoked).

        To retrieve a list, collection, stream or array of the entire directory-tree rooted at 'this' instance, instead use one of the flatten methods.
        Type Parameters:
        T - This type parameter may be chosen using the methods in class RTC. The methods in that class each return an instance of RTC. The Generic-Type Parameter of class RTC specify, exactly, what this method's ultimate Return-Type will be. There are many, many options provided in that class for deciding exactly how this returned File-System Information is represented.
        Parameters:
        returnedDataStructureChoice - This allows the user to choose a particular Data-Container or List, such as Vector, Stream, or Array as a desired Return-Type for this method.

        In addition to the Data-Container, you may use this parameter to request that the output be sorted using a set of pre-selected sort Comparator's. You may also request that the data be converted to a String-Format (rather than a FileNode) that contains either the File-Name as a String, or the Full-Path (Complete) File-Name.

        See: class RTC for details.
        filter - Any Lambda-Expression that will select directories to include in the return Data-Structure. This parameter may be null, and if it is it will be ignored and all sub-directories will be added to the return-instance.
        Returns:
        A list containing sub-directories rooted at 'this' directory.

        class RTC allows a user of this API to specify this method's Return-Type. There are dozens of options included for choosing which Reference-Container Type to return, what Sorting-Method to employ, and even for selecting the how the FileNode instances are returned: File-Name String Full-PathString, FileNode etc..

        See: class RTC for details
        Throws:
        DirExpectedException - This exception will throw if 'this' FileNode instance is representing a file, rather than a directory. It is (hopefully) obvious that files may not have child-nodes (other files and directories), only directories may have them.
        See Also:
        FileNodeFilter, isDirectory
        Code:
        Exact Method Body:
         return getDirContents(
     returnedDataStructureChoice,
     (filter != null) ? DIR_ONLY.and(filter) : DIR_ONLY
 );

      • getDirContentsFiles

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public <T> T getDirContentsFiles​(RTC<T> returnedDataStructureChoice,
                                 FileNodeFilter filter)
        This method is nearly identical to the method getDirContents(FileNodeFilter). This method, alternatively, will 'logically-and' a filter that first eliminates any and all FileNode instances which, themselves, represent 'directories'. This method will preclude 'directories' from passing the user-provided filter-logic test (and thereby prevent 'directories' from being included in the result-set). Only files can be members of the returned data-structure.

        This method only returns the contents of a single-directory in the directory-tree. Any files in sub-directories will not be retrieved.

        This method may only be invoked on FileNode instances which, themselves, represent directories on the File-System, not files. If this method is erroneously invoked on a 'file' instead of a 'directory', you should expect a DirExpectedException exception to throw. Remember: files on the file-system do not have 'contents' (specifically: other files and sub-directories), only directories may contain them.

        Non-Recursive Method:
        This method does not recursively traverse the directory-tree. The search logic of any getDirContents method will only visit the contents of 'this' FileNode instance (the one on which this method was invoked).

        To retrieve a list, collection, stream or array of the entire directory-tree rooted at 'this' instance, instead use one of the flatten methods.
        Type Parameters:
        T - This type parameter may be chosen using the methods in class RTC. The methods in that class each return an instance of RTC. The Generic-Type Parameter of class RTC specify, exactly, what this method's ultimate Return-Type will be. There are many, many options provided in that class for deciding exactly how this returned File-System Information is represented.
        Parameters:
        returnedDataStructureChoice - This allows the user to choose a particular Data-Container or List, such as Vector, Stream, or Array as a desired Return-Type for this method.

        In addition to the Data-Container, you may use this parameter to request that the output be sorted using a set of pre-selected sort Comparator's. You may also request that the data be converted to a String-Format (rather than a FileNode) that contains either the File-Name as a String, or the Full-Path (Complete) File-Name.

        See: class RTC for details.
        filter - Any Lambda-Expression that will select files to include in the return Data-Structure. This parameter may be null, and if it is it will be ignored and all files will be added to the return-instance.
        Returns:
        A Vector that contains the files inside the current directory.

        class RTC allows a user of this API to specify this method's Return-Type. There are dozens of options included for choosing which Reference-Container Type to return, what Sorting-Method to employ, and even for selecting the how the FileNode instances are returned: File-Name String Full-PathString, FileNode etc..

        See: class RTC for details
        Throws:
        DirExpectedException - This exception will throw if 'this' FileNode instance is representing a file, rather than a directory. It is (hopefully) obvious that files may not have child-nodes (other files and directories), only directories may have them.
        See Also:
        FileNodeFilter, isDirectory
        Code:
        Exact Method Body:
         return getDirContents(
     returnedDataStructureChoice,
     (filter != null) ? FILE_ONLY.and(filter) : FILE_ONLY
 );

      • flatten

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public <T> T flatten​(RTC<T> returnedDataStructureChoice,
                     int maxTreeDepth,
                     FileNodeFilter fileFilter,
                     boolean includeFilesInResult,
                     FileNodeFilter directoryFilter,
                     boolean includeDirectoriesInResult)
        This flattens the FileNode tree into a data-structure of your choosing. Review & read the parameter explanations below, closely, to see what the specifiers do.

        The concept of "flatten" is identical to the concept of "retrieve" or "search." All of these methods perform the 'copying' of a set of filter-matches into a return-container. If one wishes to scour and search a FileNode tree to obtain some or all Tree-Nodes for saving into a list (or other data-structure of your choosing), this can be easily done using this method.

        Write the necessary Lambda-Expressions (filter-predicates) to choose the files and directories that need to be included in the result-container, and then invoke any one of the overloaded flattan(...) methods offered by this class.

        If you would like to "flatten" the entire tree into a Vector or some other type of list or data-structure, then leave both of the filter parameters blank (by passing them null), and also pass '-1' to parameter 'maxTreeDepth'. Everything in the directory-tree that is rooted at 'this' instance of FileNode is returned into a data-structure of your choosing.
        Type Parameters:
        T - This type parameter may be chosen using the methods in class RTC. The methods in that class each return an instance of RTC. The Generic-Type Parameter of class RTC specify, exactly, what this method's ultimate Return-Type will be. There are many, many options provided in that class for deciding exactly how this returned File-System Information is represented.
        Parameters:
        returnedDataStructureChoice - This allows the user to choose a particular Data-Container or List, such as Vector, Stream, or Array as a desired Return-Type for this method.

        In addition to the Data-Container, you may use this parameter to request that the output be sorted using a set of pre-selected sort Comparator's. You may also request that the data be converted to a String-Format (rather than a FileNode) that contains either the File-Name as a String, or the Full-Path (Complete) File-Name.

        See: class RTC for details.
        maxTreeDepth - The value passed to 'maxTreeDepth' should be set to the maximum number of tree branches to follow, recursively, when traversing the the operating-system's directory-tree / file-system.
        'maxTreeDepth' Value Meaning
        (Any) Negative Integer Visit the directory-tree to its maximum depth; visit all leaf nodes (files).
        '0' (zero) Visit each branch (directory) and leaf node (file) of 'this' instance of FileNode, but do not enter any sub-directories.
        '1' (one) Visit each branch (directory) and leaf node (file) of 'this' instance of FileNode, and enter - recursively - any sub-directories that are found. Visit the contents of each of these branches - their files & directories - but do not enter any of those sub-directory tree-branches
        '2' ... 'n' Visit the children (both files & directories) of 'this' instance of FileNode, and enter - recursively - any sub-directories found. Apply this process, recursively, n-times.
        fileFilter - This is a Java 8 "accept" interface java.util.function.Predicate. Implementing the 'test(FileNode)' method, allows one to pick & choose which files will be visited as the tree is recursively traversed. Use a lambda-expression, if needed or for convenience.

        Regarding 'null': This parameter may be null, and if so - all files will be presumed to pass the filter test.

        Java Stream's: The behavior of the filter-logic here is identical to the Java 8+ Streams-Method 'filter(Predicate<...>)'. Specifically, when the filter returns a TRUE value for a particular FileNode, that FileNode shall be retained, or 'kept', in the returned result-set. When the filter returns FALSE for a particular FileNode, then that file or directory will be removed from the result-set.

        One way to think about which files are included in the results of a 'flatten' operation is by this list below:

        • Whether/if the boolean includeFilesInResult boolean-flag has been set to TRUE.

        • Whether the FileNode in question would pass the fileFilter.test predicate (if one is being provided). If no such Predicate is present among the input parameters, just ignore this metric.

        • Whether the containing directory's FileNode would pass the directoryFilter.test predicate (if one is being provided). If no such Predicate is present among the input parameters, just ignore this metric.

        • Whether or not all parent-containing directories of the FileNode would pass the directoryFilter.test predicate (if one were provided).
        includeFilesInResult - If this parameter is TRUE, then files will be included in the resulting Vector.

        If this parameter is FALSE, this value will "over-ride" any results that might be produced from the public fileFilter.test(this) method (if such a filter has been provided as a non-null parameter to this method).
        directoryFilter - This is also a Java 8 "Predicate Filter" interface java.util.function.Predicate. Implementing the 'test(FileNode)' method, allows one to pick & choose which directories will be visited as the tree is recursively traversed. Use a lambda-expression, if needed or for convenience.

        Regarding 'null': This parameter may be null, and if so - all directories will be traversed.

        Java Stream's: The behavior of this filter-logic is identical to the Java 8+ Streams-Method 'filter(Predicate<...>)'. Specifically, when the filter returns a TRUE value for a particular FileNode, that FileNode shall be retained, or 'kept', in the returned result-set. When the filter returns FALSE for a FileNode, then that file or directory will be removed from the result-set.

        Important: There is no way to differentiate between which directories are traversed and which directories are included in the result set - if a directory is not traversed or examined, then that directory, and any/all files and sub-directories contained by that directory will all be eliminated from the returned-results.

        One way to think about which directories are included in the results of a 'flatten' operation is by this list below:

        • Whether/if the boolean includeDirectoriesInResult boolean-flag has been set to TRUE.

        • Whether that FileNode would pass the directoryFilter.test predicate (if one is being provided). If no such Predicate is present among the input parameters, just ignore this metric.

        • Whether or not all parent directories of the FileNode would also pass the directoryFilter.test predicate (if one is being provided). If no such Predicate is present among the input parameters, just ignore this metric.
        includeDirectoriesInResult - If this parameter is TRUE, then directories will be included in the resulting Vector.

        Note: If this parameter is FALSE, this value will "over-ride" any results that may be produced from the public directoryFilter.test(this) method.
        Returns:
        A flattened version of this tree.

        class RTC allows a user of this API to specify this method's Return-Type. There are dozens of options included for choosing which Reference-Container Type to return, what Sorting-Method to employ, and even for selecting the how the FileNode instances are returned: File-Name String Full-PathString, FileNode etc..

        See: class RTC for details
        Throws:
        DirExpectedException - If 'this' instance of FileNode is not a directory, but a file, then this exception is thrown. (Files may not have child-nodes, only directories).
        java.lang.IllegalArgumentException - If the value of 'maxTreeDepth' is set to zero, then this exception shall be thrown because the method-invocation would not be making an actual request to do anything.

        This exception shall *also* be throw if both of the boolean parameters are set to FALSE, for the same reason being that the method-invocation would not be making a request.
        Code:
        Exact Method Body:
         DirExpectedException.check(this);

 if (maxTreeDepth == 0) throw new IllegalArgumentException(
     "flatten(int, FileNodeFilter, boolean, directoryFilter, boolean) has been invoked " +
     "with the maxTreeDepth (integer) parameter set to zero.  This means that there is " +
     "nothing for the method to do."
 );

 if ((! includeFilesInResult) && (! includeDirectoriesInResult))

     throw new IllegalArgumentException(
         "flatten(int, FileNodeFilter, boolean, directoryFilter, boolean) has been " +
         "invoked with both of the two boolean search criteria values set to FALSE.  " +
         "This means that there is nothing for the method to do."
     );

 // 'this' directory needs to be included (unless filtering directories)
 if (    includeDirectoriesInResult
     &&  ((directoryFilter == null) || directoryFilter.test(this))
 )
     returnedDataStructureChoice.inserter.accept(this);

 // Call the general-purpose flatten method.
 flattenINTERNAL(
     this,               returnedDataStructureChoice.inserter,
     fileFilter,         includeFilesInResult,
     directoryFilter,    includeDirectoriesInResult,
     0,                  maxTreeDepth
 );

 // retrieve the Container specified by the user.
 return returnedDataStructureChoice.finisher.get();

      • pruneTree

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public int pruneTree​(FileNodeFilter fileFilter,
                     boolean nullThePointers)
        This removes instances of FileNode that meet these conditions:

        1. Are file instances, not directories. Specifically: public final boolean isDirectory == false;

        2. Do not pass the 'fileFilter.test(...)' method. If the test method returns FALSE, the file shall be removed from the containing directory's children Vector<FileNode> File-List.


        Recursive Method: This method shall skip through, 'traverse', the entire FileNode tree and prune all 'file-leaves' that do not meet the criteria specified by the 'fileFilter' parameter.
        Parameters:
        fileFilter - This is the test used to filter out files from the directory-tree that begins at 'this' instance. Returning FALSE shall eliminate the file from its containing parent, and when this filter returns TRUE that file shall remain.
        nullThePointers - The primary use of this boolean is to remind users that this data-structure class FileNode is actually a tree that maintains pointers in both directions - upwards and downwards. Generally, trees have the potential to make programming an order of magnitude more complicated. Fortunately, because this data-structure merely represents the File-System, and because the data-structure itself (READ: 'this' tree) does not have much use for being modified itself... The fact that FileNode is a two-way, bi-directional tree rarely seems important. The most useful methods are those that "flatten" the tree, and then process the data in the files listed.

        When this parameter is set to TRUE, all parent pointers shall be nulled, and this can make garbage-collection easier.
        Returns:
        The number of files that were removed.
        Throws:
        DirExpectedException - If 'this' instance of FileNode does not represent a 'directory' on the File-System, then this exception shall throw.
        See Also:
        prune(FileNodeFilter, boolean), isDirectory, parent
        Code:
        Exact Method Body:
         DirExpectedException.check(this);

 Iterator<FileNode>  iter        = this.children.iterator();
 int                 removeCount = 0;

 while (iter.hasNext())
 {
     FileNode fn = iter.next();

     /*
     DEBUGGING, KEEP HERE.
     System.out.print(
         "Testing: fn.name: " + fn.name + "\tfn.getParentDir().name: " +
         fn.getParentDir().name
     );
     */

     if (! fn.isDirectory)

         // NOTE: This only filters 'files' (leaf-nodes) out of the tree.  This 'tree-prune'
         //       operation does not have any bearing on 'directory-nodes' (branch-nodes) in
         //       the tree.

         if (! fileFilter.test(fn))
         {
             // These types of lines can help the Java Garbage-Collector.
             // They also prevent the user from ever utilizing this object reference again.

             if (nullThePointers) fn.parent = null;

             // System.out.println("\tRemoving...");

             // This iterator is one generated by class 'Vector<FileNode>', and its remove()
             // operation, therefore, is fully-supported.  This removes FileNode fn from
             // 'this' private, final field 'private Vector<FileNode> children'

             iter.remove();

             removeCount++;
             continue;
         }

     // Keep Here, for Testing
     // System.out.println("\tKeeping...");

     if (fn.isDirectory) removeCount += fn.pruneTree(fileFilter, nullThePointers);
 }

 return removeCount;

      • getParentDir

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public FileNode getParentDir()
        Returns the parent of 'this' FileNode
        Returns:
        this.parent

        Note: If this is a "root node" or "root directory" then null will be returned.
        See Also:
        parent
        Code:
        Exact Method Body:
         return parent;

      • move

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public void move​(FileNode destinationDir)
        Move's a file or directory from "inside" or "within" the contents of the current/parent directory, and into a new/destination/parent directory. If the destinationDir is not actually a directory, then an exception is thrown. If this is already a child/member of the destinationDir, then an exception is also thrown.

        File-System Safety: This method does not modify the underlying UNIX or MS-DOS File-System - just the FileNode Tree representation in Java Memory! (No UNIX, Apple, MS-DOS etc. files are actually moved by this method)
        Parameters:
        destinationDir - the destination directory
        Throws:
        java.util.InputMismatchException
        DirExpectedException - If 'destinationDir' is not a directory, but a file, then this exception is thrown. (Files may not contain child-nodes, only directories)
        See Also:
        parent, name, children
        Code:
        Exact Method Body:
         DirExpectedException.check(destinationDir);

 if (this.parent == destinationDir) throw new java.util.InputMismatchException(
     "[" + name + "] - is already a member of the target directory " +
     "[" + destinationDir.name + "]"
 );

 parent = destinationDir;

 destinationDir.children.addElement(this);

      • del

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public void del()
        This deletes a file from the FileNode tree. It's only operation is to remove 'this' from the parent-node's Vector<FileNode> children node-list! For Java garbage collection purposes, it also empties (calls children.removeAllElements()) on the children Vector - if there is one (a.k.a) if 'this' FileNode represents a directory, not a file!

        File-System Safety: This method does not modify the underlying UNIX or MS-DOS File-System - just the FileNode-Tree representation in Java Memory! (No UNIX, Apple, MS-DOS, etc. files are actually deleted by this method)
        See Also:
        parent, children, isDirectory
        Code:
        Exact Method Body:
         parent.children.removeElement(this);

 if (isDirectory) children.removeAllElements();

 parent = null;

      • getFullPathName

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.lang.String getFullPathName()
        This visits the '.name' field for 'this' FileNode, as well as all parent instances of 'this' FileNode, and concatenates those String's.
        Returns:
        the full, available path name for 'this' FileNode as a String
        See Also:
        parent, isDirectory, name, getFullPathName()
        Code:
        Exact Method Body:
         if (parent == null)

     // This is tested in this class constructor, If this is TRUE, isDirectory must be true
     // RECENT ISSUE: May, 2022 - Google Cloud Shell Root Directory.

     return name.equals(File.separator) 
         ? name
         : name + (isDirectory ? File.separatorChar : "");
             // All other nodes where 'isDirectory' is TRUE
             // must have the file.separator appended
                                                
 else
     return parent.getFullPathName() + name + (isDirectory ? File.separatorChar : "");

      • getParentPathName

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.lang.String getParentPathName()
        Returns the as much of the "Full Path Name" of the file referenced by 'this' filename as is possible for this particular FileNode.

        If this file or directory does not have a parent, then the empty (zero-length) String will be returned. Usually, unless certain tree modification operations have been performed, only a root-node FileNode will have a 'null' parent.
        Returns:
        the full, available path name to 'this' FileNode - leaving out the actual name of this file.

        Specifically:

        • for a file such as 'directory-1/subdirectory-2/filename.txt'

        • 'directory-1/subdirectory-2/' would be returned
        See Also:
        parent, getFullPathName()
        Code:
        Exact Method Body:
         if (parent == null) return ""; else return parent.getFullPathName();

      • getJavaIOFile

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.io.File getJavaIOFile()
        Gets the java.io.File version of a file. The java class for files has quite a bit of interactive stuff for a file system - including checking for 'r/w/x' permissions. This can be useful.
        Returns:
        Gets the java.io.File instance of 'this' FileNode
        See Also:
        getFullPathName()
        Code:
        Exact Method Body:
         return new File(getFullPathName());

      • accept

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public void accept​
            (java.util.function.BiConsumer<FileNode,​java.lang.String> c,
             IOExceptionHandler ioeh)
        This presumes that 'this' instance of FileNode is not a directory, but rather a file. If it is not a file, then an exception shall throw. This method also requires that 'this' file represents a text-file that may be loaded into a String.

        This method will load the contents of 'this' file into a java.lang.String and then pass that String (along with 'this' FileNode to the method 'accept(FileNode, String' provided by the BiConsumer<FileNode, String> input-parameter 'c'.
        Parameters:
        c - This is the java FunctionalInterface 'BiConsumer'. As a functional-interface, it has a method named 'accept' and this method 'accept' receives two parameters itself:

        1. The first Parameter shall be 'this' instance of 'FileNode'

        2. The second Parameter shall be the file-contents on the File-System of 'this' FileNode - passed as a java.lang.String.
        ioeh - This an is instance of FunctionalInterface 'IOExceptionHandler'. It receives an instance of an IOException, and the programmer may insert any type of code he wants to see happen when an IOException is thrown. The 'added-value' of including this handler is that when batches of accept's are performed one a FileNode-tree, one file causing an exception throw does not have to halt the entire batch-process.

        Regarding 'null': This parameter may be null, and if it is, it shall be ignored. It is only invoked if it is not null, and if an exception occurs when reading the file from the File-System.
        Throws:
        FileExpectedException - If 'destinationDir' is not a file, but a directory, then this exception is thrown.
        See Also:
        FileRW.loadFileToString(String), getFullPathName(), IOExceptionHandler.accept(FileNode, IOException)
        Code:
        Exact Method Body:
         // This method can only be used with 'file' FileNode's.
 // FileNode's that are 'directories' do not have "text-contents" or "file-contents"

 FileExpectedException.check(this);

 try
     { c.accept(this, FileRW.loadFileToString(getFullPathName())); }

 catch (IOException ioe)

     // if an I/O exception did occur, send the information to the
     // I/O exception handler provided by the user (if and only if the
     // actually provided a non-null exception handler)

     { if (ioeh != null) ioeh.accept(this, ioe); }

      • ask

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public boolean ask​
            (java.util.function.BiPredicate<FileNode,​java.lang.String> p,
             IOExceptionHandler ioeh)
        This presumes that 'this' instance of FileNode is not a directory, but rather a file. If it is not a file, then an exception shall throw. This method also requires that 'this' file represents a text-file that may be loaded into a String.

        This method will load the contents of 'this' file into a java.lang.String and then pass that String (along with 'this' FileNode to the method 'ask(FileNode, String' provided by the BiPredicate<FileNode, String> input-parameter 'p'.

        This is the type of method that could easily be used in conjunction with a java.util.stream.Stream or a java.util.Vector.

        • Stream<FileNode>.filter (fileNode -> fileNode.ask(myFilterPred, myIOEHandler));

        • Vector<FileNode>.removeIf (fileNode -> fileNode.ask(myFilterPred, myIOEHandler));
        Parameters:
        p - This is the java FunctionalInterface 'BiPredicate'. As a functional-interface, it has a method named 'test' and this method 'test' receives two parameters itself:

        1. The first parameter shall be 'this' instance of 'FileNode'

        2. The second parameter shall be the file-contents on the File-System of 'this' FileNode - passed as a java.lang.String.


        Important: The functional-interface that is passed to parameter 'p' should provide a return boolean-value that is to act as a pass/fail filter criteria. It is important to note that the Java Vector method Vector.removeIf(Predicate) and the Java method Stream.filter(Predicate) will produce exactly opposite outputs based on the same filter logic.

        To explain further, when Vector.removeIf(Predicate) is used, the predicate should return FALSE to indicate that the FileNode needs to be eliminated not retained. When Stream.filter(Predicate) is used, TRUE should indicate that the FileNode should be retained not eliminated.
        ioeh - This is an instance of functional-interface class, IOExceptionHandler. It receives an instance of an IOException, and the programmer may insert any type of code he wants to see happen when an IOException is thrown. The 'added-value' of including this handler is that when batches of ask's are performed on a FileNode-tree, one file causing an exception throw does not have to halt the entire batch-process.

        Regarding 'null': This parameter may be null, and if it is, it shall be ignored. It is only invoked if it is not null, and if an exception occurs when reading the file from the File-System.
        Returns:
        This method returns TRUE if there were no I/O faults when either reading or writing the file.
        Throws:
        FileExpectedException - If 'destinationDir' is not a file, but a directory, then this exception is thrown.
        See Also:
        getFullPathName(), FileRW.loadFileToString(String), IOExceptionHandler.accept(FileNode, IOException)
        Code:
        Exact Method Body:
         // This method can only be used with 'file' FileNode's.
 // FileNode's that are 'directories' do not have "text-contents" or "file-contents"

 FileExpectedException.check(this);

 try
     { return p.test(this, FileRW.loadFileToString(getFullPathName())); }

 catch (IOException ioe)
     { if (ioeh != null) ioeh.accept(this, ioe); return false; }

      • NULL_THE_TREE

        🡅  ⇈  ⮫ 🗕  🗗  🗖 
        public void NULL_THE_TREE()
        There are not any "Tree Structures" present in the HTML Search, Update, and Scrape Packages. In the Java Packages, the class 'FileNode' is the lone source of "Tree Structures." The Java Garbage Collector sometimes seems to work in mysterious ways.

        This method will 'null-ify' all references (pointers) in a 'FileNode'-Tree. The FileNode-Tree can be a great asset or tool during the development process when looking through file-contents and trying to modify them - or just find files with certain characteristics.
        See Also:
        getDirContents(), getDirContentsDirs(), parent, children
        Code:
        Exact Method Body:
         Iterator<FileNode> iter = getDirContents(RTC.ITERATOR());

 while (iter.hasNext()) iter.next().parent = null;

 iter = getDirContentsDirs(RTC.ITERATOR());

 while (iter.hasNext()) iter.next().NULL_THE_TREE();

 children.clear();