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

    This loads the UNIX or MS-DOS file-system 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.

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

    FLATTEN THE 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 THE TREE: There are three methods for printing various branches of the tree provided by this class.

    Example:
     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
    // 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<FileNode> 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:
        1
        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:
        1
        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:
        1
        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:
        1
        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:
        1
        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:
        1
        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:
        1
        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:
        1
        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:
        1
2
        public static final Comparator<FileNode> comp2 =
        (FileNode fn1, FileNode fn2) -> fn1.getFullPathName().compareToIgnoreCase(fn2.getFullPathName());

    • Constructor Detail

      • FileNode

        protected FileNode​(java.lang.String name,
                   FileNode parent,
                   long lastModified)
        This constructor builds a FileNode object - which must be a 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:
        1
2
3
4
5
6
7
         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:
        1
2
3
4
5
6
7
         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:
        1
2
         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:
        1
         return new FileNode(name);

      • pollDir

        public FileNode pollDir​(java.lang.String dirName)
        Convenience Method. Invokes pollDir(String, boolean)
        Does NOT ignore case.
        Code:
        Exact Method Body:
        1
         return pollDir(dirName, false);

      • 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:
        1
2
3
4
5
6
7
8
9
         FileNode ret = dir(dirName, ignoreCase);

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

 return ret;

      • dir

        public FileNode dir​(java.lang.String dirName)
        Convenience Method. Invokes dir(String, boolean).
        Does NOT ignore case.
        Code:
        Exact Method Body:
        1
         return dir(dirName, false);

      • 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:
         1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
         // 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)
        Convenience Method. Invokes pollFile(String, boolean).
        Does NOT ignore case.
        Code:
        Exact Method Body:
        1
         return pollFile(fileName, false);

      • 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:
        1
2
3
4
5
6
7
8
9
         FileNode ret = file(fileName, ignoreCase);

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

 return ret;

      • file

        public FileNode file​(java.lang.String fileName)
        Convenience Method. Invokes file(String, boolean).
        Does NOT ignore case.
        Code:
        Exact Method Body:
        1
         return file(fileName, false);

      • 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:
         1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
         // 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:
        1
         return toString().hashCode();

      • equals

        public final boolean equals​(java.lang.Object o)
        Overrides:
        equals in class java.lang.Object
        Code:
        Exact Method Body:
         1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
         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:
        1
2
3
4
5
6
7
         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:
        1
         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:
        1
         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:
        1
         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:
        1
         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:
        1
         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:
        1
2
3
4
5
6
7
         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:
        1
2
3
4
5
6
7
         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:
        1
2
         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:
        1
2
3
4
5
6
7
         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()
        This method will fill out the tree with parameter int maxTreeDepth set to '-1', meaning the entire directory-tree, no matter how large, will be visited. Also, the parameters directoryFilter and fileFilter are simply set to null - and another method named loadTree(...) is invoked.
        Returns:
        a reference to 'this' FileNode, for convenience only.
        See Also:
        loadTree(int, FilenameFilter, FileFilter)
        Code:
        Exact Method Body:
        1
         return loadTree(-1, null, null);

      • loadTree

        public FileNode loadTree​(boolean includeFiles,
                         boolean includeDirectories)
        This is a simplified loading method to load the contents of a directory into a FileNode tree. There are three primary scenarios to consider when invoking this method, based on the values provided to the two input parameters 'includeFiles' and 'includeDirectories'.

        One of these three cases is trivial, if TRUE has been passed to both of the inputs, then this method's loading-behavior shall be identical to invoking loadTree() with zero parameters - all files in all sub-directories will be loaded.

        CASE 1: If TRUE has been passed to 'includeDirectories', but not to the other parameter, then only the directory-tree (without any of the files it contains) will be loaded into the FileNode tree.

        CASE 2: If TRUE has been passed to 'includeFiles', but not to 'includeDirectories', then this method will not traverse any branches of the directory-tree rooted at 'this' FileNode, but rather will only import the file-contents of 'this' directory into the tree. Computer jargon specialists would call this a 'level-1' tree-traversal.

        FINALLY: if FALSE has been provided to both of these parameters, then an IllegalArgumentException will throw, because there is no action for this method to take.
        Parameters:
        includeFiles - If the user would like to have file names imported into this data-structure, set this boolean value to TRUE. If this parameter is FALSE, then files will not be imported into 'this' FileNode.
        includeDirectories - If the user would like to have directory names imported into this data-structure, set this boolean value to TRUE. If this parameter is FALSE, then directories will not be imported into 'this' FileNode. Only file names in the current ('working') directory represented by 'this' FileNode may be imported.

        NOTE: If this parameter is FALSE, subsequent branches of the directory-tree will not be traversed. This is because files must be contained by a directory - and since directories are being excluded as per this parameter, therefore any files in subdirectories cannot be stored in this tree
        Returns:
        a reference to 'this' FileNode, for convenience only.
        Throws:
        DirExpectedException - This method will only execute if the instance of 'this' is actually a directory. Files on the file-system are leaves, not branches - so they do not have contents to load.
        java.lang.IllegalArgumentException - If both of the boolean parameters are set to FALSE, then this exception shall be thrown because the method-invocation would not be making an actual request to do any importing / loading.
        See Also:
        loadTree(int, FilenameFilter, FileFilter)
        Code:
        Exact Method Body:
        1
2
3
4
5
6
7
         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)
        This is a simplified loading method to load just the directory tree of a root 'FileNode' into memory. Files on the file-system that reside in this directory-tree will be ignored - meaning their file-names will not be imported into this 'FileNode' tree instance.
        Parameters:
        maxTreeDepth - This value should be set to the maximum number of levels deep to search when traversing the tree.

        NOTE: Simply use any negative number to always visit the tree to its maximum depth. If this value is set to zero, then an exception shall throw.
        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:
        1
2
         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 must be included, or 'kept', (and subsequently visited and loaded into the tree).
        Throws:
        DirExpectedException - This method will only execute if the instance of 'this' is actually a directory. Files on the file-system are leaves, not branches - so they do not have contents to load.
        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.
        Code:
        Exact Method Body:
        1
2
3
4
5
6
7
         if (maxTreeDepth == 0) throw new IllegalArgumentException(
     "loadTreeJustDirs(int, FileFilter) has been invoked with the maxTreeDepth Parameter " +
     "set to zero.  This means that there is nothing for the method to do."
 );

 // Setting the return value of the filter-predicate to 'false' for the fileFilter parameter.
 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' that represents a directory on the UNIX or MS-DOS file-system. An exception shall throw if this method is invoked on an instance of a file.
        Parameters:
        maxTreeDepth - This variable should be set to -1 (or any negative number) if the entire tree is required. For all positive int maxTreeDepth, the recursive algorithm will search through the file-system tree, and add nodes to the child-directories as it encounters them, recursively. When maxTreeDepth has been reached, the recursion ends.

        NOTE: When parameter maxTreeDepth is passed a value of '1', the directory represented by 'this' FileNode will be the only directory searched for files and directories. When maxTreeDepth is passed '2', 'this' directory and each sub-directory of 'this' shall be searched, and so on and so forth, recursively.
        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:
        1
2
         public boolean test(File dir, String name)

        Where:

        • The File dir parameter represents the containing/parent directory.
        • The String name parameter represents the name of the file (not including the full path).

        NOTE: If this filter parameter is null, the parameter is ignored - and all files shall be included in the result.

        ALSO: The filter used should return FALSE if the passed file should be skipped. The filter must return TRUE if the file must be included, or 'kept', (and subsequently loaded into the tree).
        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:
        1
2
         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 must be included, or 'kept', (and subsequently visited and loaded into the tree).
        Returns:
        a reference to 'this' FileNode, for convenience only.
        Throws:
        DirExpectedException - This method will only execute if the instance of 'this' is actually a directory. Files on the file-system are leaves, not branches - so they do not have contents to load.
        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.
        See Also:
        loadTree(), DirExpectedException.check(FileNode)
        Code:
        Exact Method Body:
         1
 2
 3
 4
 5
 6
 7
 8
 9
10
         DirExpectedException.check(this);

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

 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:
        1
         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:
        1
2
3
4
5
6
7
         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:
        1
2
3
4
5
6
7
         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:
         1
 2
 3
 4
 5
 6
 7
 8
 9
10
         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:
         1
 2
 3
 4
 5
 6
 7
 8
 9
10
         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:
         1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
         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:
        1
2
3
4
         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:
        1
2
3
4
         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:
        1
2
3
4
         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 a Vector that contains the contents of a directory.

        IMPORTANT: This method may only be invoked on FileNode instances which represent directories on the file-system. If this method is invoked on a file, an exception shall throw. This is because files on the file-system do not have 'contents' in the sense of 'holding' or 'having' other files or sub-directories.

        TREE TRAVERSAL NOTE: This Vector is not recursively generated, and does not traverse the entire directory tree. The search logic only visits the files & directories contained within the directory on which 'this' instance is invoked. To retrieve a Vector of the entire tree (or a sub-tree), instead use a version of 'flatten(...)'.
        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 return Vector. Specifically, the filter that is passed should return TRUE when a file or directory needs to be included in the Vector. When the filter returns FALSE after testing a file or directory, the Vector that is returned by this method shall exclude that file or directory.

        If this parameter is null, it will be ignored, and every FileNode contained by the directory will be included in the return Vector.
        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 - 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).
        See Also:
        FileNodeFilter, children
        Code:
        Exact Method Body:
        1
2
3
4
5
6
7
8
         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 almost identical to the method getDirContents(filter). This will 'logical-and' a filter which requires that only FileNode instances which are directories can be included in the Vector. FileNode instances which are files, will not be contained by the Vector that is generated.

        IMPORTANT: This method may only be invoked on FileNode instances which represent directories on the file-system. If this method is invoked on a file, an exception shall throw. This is because files on the file-system do not have 'contents' in the sense of 'holding' or 'having' other files or sub-directories.

        TREE TRAVERSAL NOTE: This Vector is not recursively generated, and does not traverse the entire directory tree. The search logic only visits the files & directories contained within the directory on which 'this' instance is invoked. To retrieve a Vector of the entire tree (or a sub-tree), instead use a version of 'flatten(...)'.
        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 directories that do not pass the filter's 'test' method shall not be included in the return Vector. Specifically, the filter that is passed should return TRUE when a directory needs to be included in the Vector. When the filter returns FALSE after testing a directory, the Vector that is returned by this method shall skip that directory.

        If this parameter is null, it will be ignored, and every sub-directory FileNode contained by this directory instance will be included in the return Vector.
        Returns:
        A Vector that contains the sub-directories 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 - 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).
        See Also:
        FileNodeFilter, isDirectory
        Code:
        Exact Method Body:
        1
2
         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 almost identical to the method getDirContents(filter). This will 'logical-and' a filter which requires that only FileNode instances which are files can be included in the return Vector. FileNode instances which are directories, will not be contained by the Vector that is generated.

        IMPORTANT: This method may only be invoked on FileNode instances which represent directories on the file-system. If this method is invoked on a file, an exception shall throw. This is because files on the file-system do not have 'contents' in the sense of 'holding' or 'having' other files or sub-directories.

        TREE TRAVERSAL NOTE: This Vector is not recursively generated, and does not traverse the entire directory tree. The search logic only visits the files & directories contained within the directory on which 'this' instance is invoked. To retrieve a Vector of the entire tree (or a sub-tree), instead use a version of 'flatten(...)'.
        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 that do not pass the filter's 'test' method shall not be included in the return Vector. Specifically, the filter that is passed should return TRUE when a file needs to be included in the Vector. When the filter returns FALSE after testing a file, the Vector that is returned by this method shall skip that file.

        If this parameter is null, it will be ignored, and every instance of FileNode that is a file and is contained by this directory instance will be included in the return Vector.
        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 - 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).
        See Also:
        FileNodeFilter, isDirectory
        Code:
        Exact Method Body:
        1
2
3
4
         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 simple java Vector<FileNode>. Primarily, if the tree was pruned during loading in a way that has changed, or the tree was not pruned at all - then this method is for you! :) Any one of these parameters may be null or negative, and they will be ignored completely. Make sure to use TRUE for the two boolean values if you do not want to lose the file-system type out of your result set. 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 perform 'copying' a set of filter-matches into a list). If one wishes to scour/search a FileNode tree, and obtain individual nodes of the tree and save them in a list, it is easily done by simply writing the appropriate file & directory filter public boolean test(FileNode fn) methods (or using Java "lambda" expressions instead of actual methods) - and then invoking a version of flatten(...).

        If you would like to "flatten" the entire tree into a Vector, leave the filter parameters blank by passing them null.
        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 - This value should be set to the maximum number of levels deep to recursively search when traversing the traversing the file-system / operating-system directory-tree.

        NOTE: Simply use any negative number to always visit the tree to its maximum depth.
        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 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.
        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.
        directoryFilter - This is also a Java 8 "accept" 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.

        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.

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

        ALSO: There is no way to differentiate which directories are traversed and which directories are included in the result set - they are either traversed or not. Whether the particular FileNode (which is a directory, not a file) is included in the result set, is determined by:

        • Whether that FileNode has passed (been accepted by) the public boolean directoryFilter.test(this) method.
        • And also whether/if the boolean includeDirectoriesInResult boolean-flag has been set to TRUE.
        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:
         1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
         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:
         1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
         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)

         if (! fileFilter.test(fn))
         // 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 (nullThePointers) fn.parent = null;
                 // These types of lines can help the Java Garbage-Collector.
                 // They also prevent the user from ever utilizing this object reference again.

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

             iter.remove();
                 // 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'

             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:
        1
         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:
         1
 2
 3
 4
 5
 6
 7
 8
 9
10
         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:
        1
2
3
         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:
        1
2
3
4
         if (parent == null)
     return name + (isDirectory ? File.separatorChar : "");
 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:
        1
         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:
        1
         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:
         1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
         // 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:
         1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
         // 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:
        1
2
3
4
5
6
7
8
         // 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:
        1
2
3
4
5
6
7
         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();