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

        NOTE: This field is a Java simple-type 'long' which represents the time the file was last modified, measured in milliseconds 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 OS directory, then field Vector<FileNode> children will be instantiated and hold all files and sub-directories which are found.
        Code:
        Exact Field Declaration Expression:
         protected final Vector<FileNode> children;

      • 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.*;

        NOTE: 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());

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

        IMPORTANT: This flag is a non Thread-Safe flag, because it is a 'static' flag that applies to all instances of class FileNode
        Code:
        Exact Field Declaration Expression:
         public static boolean SKIP_DIR_ON_SECURITY_EXCEPTION = false;

    • Constructor Detail

      • FileNode

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

        SPECIFICALLY: The node that is instantiated will have a final int fileSize field value of '0' and a final boolean isDirectory value of TRUE.

        NOTE: File-name validity checks are not performed here, no validity checks are performed because this constructor has protected access, and the calls to it are generated here in this class. Furthermore, the values sent to these parameters are all retrieved from getter-calls to class java.io.File, and likely are not 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 file FileNode instance - and may not be a directory FileNode instance.

        SPECIFICALLY: The node that is instantiated will have a final boolean isDirectory value of FALSE.

        NOTE: File-name validity checks are not performed here, no validity checks are performed because this constructor has protected access, and the calls to it are generated here in this class. Furthermore, the values sent to these parameters are all' retrieved from getter-calls to class java.io.File, and likely are not 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.
        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 tree is intended to be built.

        NOTE: Once a "root node" for the tree has been built, calling the loadTree(...) methods is simple, and the only way to populate the tree of UNIX or MS-DOS file-names.

        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);

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

        Differing: Different than method dir(String, boolean), this method will "extract" the directory from the in-memory file-tree. If a directory is found matching the requested name and case requirements, when it is returned, it's parent FileNode pointer instance shall be null, and the parent will not contain a link to the directory in it's 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).

        FINALLY: 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;

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

      • 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 'fileName'.

        Differing: Different than method file(String, boolean), this method will "extract" the file from the in-memory file-tree. If a file is found matching the requested name and case requirements, when it is returned, it's parent FileNode pointer instance shall be null, and the parent will not contain a link to the returned FileNode in it's 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;

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

      • 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: This is 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 interface Comparable<T> requirements. This does a very simple comparison using the results to a call of method public String 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 public String 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, as for array indexing.

        NOTE: 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 public String 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);

      • 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.util.function.Consumer<FileNode> on each element in the tree. Note that if 'this' instance of FileNode is a file, not a directory, then the passed Consumer shall only be invoked using 'this' instance.
        Parameters:
        c - This is any java Consumer<FileNode>
        Code:
        Exact Method Body:
         c.accept(this);
 children.forEach((FileNode fn) -> fn.forEach(c));

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

        NOTE:The method's clone() and deepClone() shall return identical results when used on an instance of FileNode that represents a file, not 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();

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

        IMPORTANT: This method can only be invoked on an instance of 'FileNode' which represents a directory on the UNIX or MS-DOS file-system. An 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: If this filter parameter is passed null, the parameter is ignored - and all files shall be included in the result, with no filtering applied.

        ALSO: Consistent with other Java 'filter' mechanisms, the filter you provide 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: If this filter parameter is null, the parameter is ignored - and all sub-directories are visited.

        ALSO: 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 children-nodes in 'this' instance of FileNode.

        NOTE: This is not a 'recursive' method, and that means the integer returned by this method is only a count of the number of direct-descendants of 'this' FileNode.
        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 children-nodes that are directories of 'this' FileNode.

        NOTE: This is not a 'recursive' method, and that means the integer returned by this method is only a count of the number of direct-descendants of 'this' FileNode.
        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 children-nodes that are files of 'this' FileNode.

        NOTE: This is not a 'recursive' method, and that means the integer returned by this method is only a count of the number of direct-descendants of 'this' FileNode.
        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;

      • 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/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 parameter expects an implementation of Java's interface java.lang.Appendable which allows for a wide range of options when logging intermediate messages.
        Class or Interface InstanceUse & Purpose
        'System.out'Sends text to the standard-out terminal
        Torello.Java.StorageWriterSends text to System.out, and saves it, internally.
        FileWriter, PrintWriter, StringWriterGeneral purpose java text-output classes
        FileOutputStream, PrintStreamMore general-purpose java text-output classes

        IMPORTANT: The interface Appendable requires that the check exception IOException must be caught when using its append(CharSequence) 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 the Predicate's public boolean test(FileNode fn) 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 the 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.

        NOTE: This only retrieves the contents of 'this' directory - and does not expand the leaf-node directories when scanning for files or sub-directories sizes!
        Parameters:
        fileTest - Any java Predicate that satisfies the requirement of having a: public boolean test(FileNode f); method. the interface 'FileNodeFilter' will also work, if using Java 7.

        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.
        Parameters:
        fileTest - Any java.util.function.Predicate or lambda-expressions that satisfies the requirement of having a: public boolean test(FileNode f); method. Implementing the interface 'FileNodeFilter' will also work, if using Java 7.

        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 - java predicate that satisfies the requirement of having a: public boolean test(FileNode f); method. The interface 'FileNodeFilter' will also work, if using Java 7.

        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 used when making the total count.

        NOTE: 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 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 (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 used when making the total count.

        NOTE: 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 Predicate<FileNode> 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 used when making the total count.

        NOTE: 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​(VarList<T,​FileNode> listChoice,
                            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.

        IMPORTANT: 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.

        TREE TRAVERSAL NOTE: 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 RetTypeChoice inner-class. It is used to determine the return type of this method, for which many options exist.
        Parameters:
        listChoice - This allows the user to choose a particular Container or List, such as Vector, Stream, or array. Furthermore the ability to specify a sort-type, and a data-out choice including File-Name, Full-Path Name, or File-Node is provided by a long list of options in class RetTypeChoice

        See: FileNode.RetTypeChoice.
        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.

        The implementation of VarList<T, FileNode> used inside of class FileNode.RetTypeChoice allows a user of this API to specify the return type of this method. There are dozens of options for what file-system information about each file being returned should include, and how these returned instances of FileNode should be sorted. Note that this return-value allows for converting the files to their name as Java String's - among other operations.

        Furthermore, the static member fields in class RetTypeChoice also allow a programmer to choose a container for holding these instances of FileNode (or String-converted FileNode's).

        See: FileNode.RetTypeChoice.
        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);

 VarList<T, FileNode> ret = listChoice.create();

 children.forEach
     ((FileNode fn) -> { if ((filter == null) || filter.test(fn)) ret.insert(fn); });

 return ret.retrieve();

      • getDirContentsDirs

        🡅  🡇  ⇈  ⮫ 
        public <T> T getDirContentsDirs​(VarList<T,​FileNode> listChoice,
                                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.

        IMPORTANT: 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.

        TREE TRAVERSAL NOTE: 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 RetTypeChoice inner-class. It is used to determine the return type of this method, for which many options exist.
        Parameters:
        listChoice - This allows the user to choose a particular Container or List, such as Vector, Stream, or array. Furthermore the ability to specify a sort-type, and a data-out choice including File-Name, Full-Path Name, or File-Node is provided by a long list of options in class RetTypeChoice

        See: FileNode.RetTypeChoice.
        filter -
        Returns:
        A list containing sub-directories rooted at 'this' directory.

        The implementation of VarList<T, FileNode> used inside of class FileNode.RetTypeChoice allows a user of this API to specify the return type of this method. There are dozens of options for what file-system information about each file being returned should include, and how these returned instances of FileNode should be sorted. Note that this return-value allows for converting the files to their name as Java String's - among other operations.

        Furthermore, the static member fields in class RetTypeChoice also allow a programmer to choose a container for holding these instances of FileNode (or String-converted FileNode's).

        See: FileNode.RetTypeChoice.
        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:
         FileNodeFilter dirFilter = (FileNode fn) -> fn.isDirectory;
 return getDirContents(listChoice, (filter != null) ? filter.and(dirFilter) : dirFilter);

      • getDirContentsFiles

        🡅  🡇  ⇈  ⮫ 
        public <T> T getDirContentsFiles​(VarList<T,​FileNode> listChoice,
                                 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.

        IMPORTANT: 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.

        TREE TRAVERSAL NOTE: 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 RetTypeChoice inner-class. It is used to determine the return type of this method, for which many options exist.
        Parameters:
        listChoice - This allows the user to choose a particular Container or List, such as Vector, Stream, or array. Furthermore the ability to specify a sort-type, and a data-out choice including File-Name, Full-Path Name, or File-Node is provided by a long list of options in class RetTypeChoice

        See: FileNode.RetTypeChoice.
        filter -
        Returns:
        A Vector that contains the files inside the current directory.

        The implementation of VarList<T, FileNode> used inside of class FileNode.RetTypeChoice allows a user of this API to specify the return type of this method. There are dozens of options for what file-system information about each file being returned should include, and how these returned instances of FileNode should be sorted. Note that this return-value allows for converting the files to their name as Java String's - among other operations.

        Furthermore, the static member fields in class RetTypeChoice also allow a programmer to choose a container for holding these instances of FileNode (or String-converted FileNode's).

        See: FileNode.RetTypeChoice.
        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:
         FileNodeFilter fileFilter = (FileNode fn) -> ! fn.isDirectory;

 return getDirContents
     (listChoice, (filter != null) ? filter.and(fileFilter) : fileFilter);

      • flatten

        🡅  🡇  ⇈  ⮫ 
        public <T> T flatten​(VarList<T,​FileNode> listChoice,
                     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.

        GENERALLY: The concept of "flatten" is identical to the concept of "retrieve" or "search" - because all of these perform the 'copying' of a set of filter-matches into a list. If one wishes to scour or search a FileNode tree, and obtain the individual nodes of the tree and save them into a list (or other data-structure of your choosing), it can be done easily by writing the appropriate file & directory filter-predicates (using Java "lambda" expressions or actual methods) - and then invoking one of the several overloaded flatten(...) 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 RetTypeChoice inner-class. It is used to determine the return type of this method, for which many options exist.
        Parameters:
        listChoice - This allows the user to choose a particular Container or List, such as Vector, Stream, or array. Furthermore the ability to specify a sort-type, and a data-out choice including File-Name, Full-Path Name, or File-Node is provided by a long list of options in class RetTypeChoice

        See: FileNode.RetTypeChoice.
        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.

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

        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, 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 would pass the fileFilter.test predicate (if one has been provided, otherwise ignore this metric).
        • Whether the containing directory's FileNode would pass the directoryFilter.test predicate (if one has been provided, otherwise 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.

        NOTE: If this parameter is FALSE, this value will "over-ride" any results that may be produced from the public boolean fileFilter.test(this) method (if such a filter had been provided).
        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.

        NOTE: 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, 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 eliminted 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 has been provided, otherwise ignore this metric).
        • Whether or not all parent directories of the FileNode would also pass the directoryFilter.test predicate (if one were provided).
        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 boolean directoryFilter.test(this) method.
        Returns:
        A flattened version of this tree.

        The implementation of VarList<T, FileNode> used inside of class FileNode.RetTypeChoice allows a user of this API to specify the return type of this method. There are dozens of options for what file-system information about each file being returned should include, and how these returned instances of FileNode should be sorted. Note that this return-value allows for converting the files to their name as Java String's - among other operations.

        Furthermore, the static member fields in class RetTypeChoice also allow a programmer to choose a container for holding these instances of FileNode (or String-converted FileNode's).

        See: FileNode.RetTypeChoice.
        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 allows us to permit the user to decide what type of Container and what type of
 // Object inside the container is returned.

 VarList<T, FileNode> ret = listChoice.create();

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

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

 // retrieve the Container specified by the user.
 return ret.retrieve();

      • 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 private final Vector<FileNode> children file-list.


        RECURSION: 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.

        POINT: 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 here.
        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.

        NOTE: 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!

        NOTE: 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.

        NOTE: 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());

      • apply

        🡅  🡇  ⇈  ⮫ 
        public boolean apply​
            (java.util.function.BiFunction<FileNode,​java.lang.String,​java.lang.String> f,
             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 'apply(FileNode, String' provided by the BiFunction<FileNode, String> input-parameter 'f'.

        This is the type of method that could easily be used in conjunction with Java's java.util.stream.Stream A.P.I. If the 'f' parameter were to include a regular-expression for modifying the contents of a file, then by using Java-Streams a programmer could easily write a UNIX 'SED' or 'AWK' like script with just a couple lines of Java.

        Presuming that an appropriate 'myFunction' were written, any one of the following invocations could perform a UNIX 'SED' or 'AWK' type of routine on a suite of text-files, instantly.

        • Stream<FileNode>.forEach(fileNode -> fileNode.apply(myFunction, myIOEHandler));
        • Vector<FileNode>.forEach(fileNode -> fileNode.apply(myFunction, myIOEHandler));
        • Stream<FileNode>.map(fileNode -> fileNode.apply(...));
        Parameters:
        f - This is the java FunctionalInterface 'BiFunction' As a functional-interface, it has a method named 'apply' and this method 'apply' 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.

        EXPECTED RETURN: The functional-interface that is passed to parameter 'f' should provide a return-value that is a "new, updated String" that shall be used to "replace the file-contents" of this instance of FileNode.

        WRITE-NOTICE: This operation will OVER-WRITE the current contents of a file on the file-system. Also, this operation treats the file as if it contained text. Data-Files containing binary-data may not be used with this method. This is the only method in class 'FileNode' that actually will modify the underlying file-system.
        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 apply's are performed on a FileNode-tree, one file causing an exception throw does not have to halt the entire batch-process.

        NOTE: 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 either reading or writing the file to/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), FileRW.writeFile(CharSequence, 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
 {
     // Read 'this' file into a String
     String fileName     = this.toString();
     String fileContents = FileRW.loadFileToString(fileName);

     // Send the contents of 'this' file to the BiFunction parameter 'f'
     fileContents = f.apply(this, fileContents);

     // Re-write the new file back to the old location.
     FileRW.writeFile(fileContents, fileName);

     return true;
 }
 catch (IOException e)
 { 
     // 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, e);

     return false;
 }

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

        NOTE: 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 either reading or writing the file to/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 TRUE 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.

        NOTE: 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 either reading or writing the file to/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. The external-library "Java-Parser" is a library that is only used for the Java-Doc Upgrader Tool. Java Parser is not present in anything related to HTML Search, Scrape or Update. The Garbage Collector has had some trouble clearing out the AST Trees that are generated by the Java-Parser import when using the Java-Doc Upgrader Tool. A Circular Tree is probably impossible to clean. The Garbage Collector for memory references has worked wonderfully well with 100% of vectorized-html pages that have been generated although not so much for the "Java Parser Bridge" routines.

        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(RetTypeChoice.ITERATOR);

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

 iter = getDirContentsDirs(RetTypeChoice.ITERATOR);

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

 children.clear();