package Torello.Java;

import java.util.*;
import java.util.function.*;
import java.util.stream.*;
import java.io.*;

/**
 * One of the <I>flagship classes</I> of Java HTML, {@code FileNode} loads a directory or
 * directory-tree from a File-System into memory, and provides a thorough API for listing and
 * analyzing its contents.
 * 
 * <EMBED CLASS='external-html' DATA-FILE-ID=FN>
 */
public final class FileNode
    implements CharSequence, Comparable<FileNode>, java.io.Serializable, Cloneable
{
    /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUID> */
    public static final long serialVersionUID = 1;

    /**
     * When this variable is {@code TRUE} debug and status information will be sent to 
     * Standard-Output.
     */
    public static boolean VERBOSE = false;

    /** The name of the file or directory is saved/stored here */
    public final String name;

    /**
     * If {@code 'this'} class-instance represents a directory in the BASH/UNIX or MS-DOS file
     * system, this variable will be {@code TRUE}.  When this field is set to {@code FALSE}, it
     * means that {@code 'this'} instance is a file.
     */
    public final boolean isDirectory;

    /** 
     * The parent/container {@code 'FileNode'} directory is saved here - like a <I>pointer 
     * "tree"</I>.
     */
    protected FileNode parent;

    /**
     * When a tree is loaded into memory, the size of each file is saved in this variable.  It can
     * be retrieved (and even changed).
     */
    public final long fileSize;

    /**
     * When a tree is loaded into memory, the file-date of the file is saved in this variable.  It
     * can be retrieved.  If the {@code SecurityManager.checkRead(fileName)} denies read access to
     * the file, this field will equal zero.
     *
     * <BR /><BR /><B CLASS=JDDescLabel>Time in Milli-Seconds:</B>
     * 
     * <BR />This field is a Java simple-type {@code 'long'} which represents the time the file was
     * last modified, measured in Milli-Seconds since the epoch
     * {@code (00:00:00 GMT, January 1, 1970)}
     */
    public final long lastModified;

    /**
     * This variable remains null for all instances of this class which represent 'files' on the
     * underlying Operating-System, rather than 'directories.'
     * 
     * <BR /><BR />On the other hand, if {@code 'this'} instance of {@code FileNode} represents an
     * MS-DOS, Unix, or Apple File-System directory, then this field will be constructed /
     * instantiated and hold all file and sub-directory {@code FileNode}-instances which contained
     * by this directory.
     */
    protected final Vector<FileNode> children;


    // ********************************************************************************************
    // ********************************************************************************************
    // java.io.FilenameFilter static-final helpers
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Implements the interface {@code java.io.FilenameFilte}, and can therefore be used within the
     * {@link #loadTree(int, FilenameFilter, FileFilter) loadTree} method.
     * 
     * <BR /><BR />Selects for files whose name ends with {@code '.html'}, and is
     * <B STYLE='color: red;'>case-insensitive</B>.  This {@code Predicate} will match files
     * ending in {@code '.html', '.HTML',} or even {@code '.hTmL'}.
     */
    public static final FilenameFilter HTML_FILES = (File f, String name) ->
        StrCmpr.endsWithIgnoreCase(name, ".html");

    /**
     * Implements the interface {@code java.io.FilenameFilte}, and can therefore be used within the
     * {@link #loadTree(int, FilenameFilter, FileFilter) loadTree} method.
     * 
     * <BR /><BR />Selects for files whose name ends with {@code '.css'}, and is
     * <B STYLE='color: red;'>case-insensitive</B>.  This {@code Predicate} will match files
     * ending in {@code '.css', '.CSS',} or even {@code '.CsS'}.
     */
    public static final FilenameFilter CSS_FILES = (File f, String name) ->
        StrCmpr.endsWithIgnoreCase(name, ".css");

    /**
     * Implements the interface {@code java.io.FilenameFilte}, and can therefore be used within the
     * {@link #loadTree(int, FilenameFilter, FileFilter) loadTree} method.
     * 
     * <BR /><BR />Selects for files whose name ends with {@code '.java'}.  This particular filter
     * is <B STYLE='color: red;'>case-sensitive</B>.
     */
    public static final FilenameFilter JAVA_FILES = (File f, String name) ->
        name.endsWith(".java");

    /**
     * Implements the interface {@code java.io.FilenameFilte}, and can therefore be used within the
     * {@link #loadTree(int, FilenameFilter, FileFilter) loadTree} method.
     * 
     * <BR /><BR />Selects for files whose name ends with {@code '.class'}.  This particular filter
     * is <B STYLE='color: red;'>case-sensitive</B>.
     */
    public static final FilenameFilter CLASS_FILES = (File f, String name) ->
        name.endsWith(".class");

    /**
     * Implements the interface {@code java.io.FilenameFilte}, and can therefore be used within the
     * {@link #loadTree(int, FilenameFilter, FileFilter) loadTree} method.
     * 
     * <BR /><BR />Selects for files whose name ends with {@code '.json'}.  This particular filter
     * is <B STYLE='color: red;'>case-insensitive</B>.  This {@code Predicate} will match files
     * ending in {@code '.json', '.JSON',} or even {@code '.JsOn'}.
     */
    public static final FilenameFilter JSON_FILES = (File f, String name) ->
        StrCmpr.endsWithIgnoreCase(name, ".json");


    // ********************************************************************************************
    // ********************************************************************************************
    // FileNode Constructors
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * This constructor builds a {@code FileNode} object - which <I>must be a
     * {@code FileNode}-Directory instance</I> and may not be a {@code FileNode}-File instance.
     *
     * <BR /><BR /><B CLASS=JDDescLabel>{@code FileNode}-Directory:</B>
     * 
     * <BR />This instance will have a {@link #fileSize} field whose value equals {@code '0'}, and
     * an {@link #isDirectory} value set to {@code FALSE}.
     *
     * <BR /><BR />Directory-Name validity checks are not performed here.  This constructor has a
     * {@code 'protected'} access level, and is only called internally when a directory has been
     * found by getter-calls to {@code java.io.File} (and therefore are extremely unlikely to be
     * invalid).
     * 
     * @param name The name of {@code 'this' FileNode}.
     *
     * @param parent This is the parent or "container-directory" of {@code 'this' FileNode}.  If a
     * {@code FileNode} that is not a directory itself is passed as the parent, then an exception
     * will be thrown.
     *
     * @param lastModified This must be a {@code long} value indicating when the file was last
     * modified - according to the Operating-System.  This value may be {@code '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.
     *
     * <DIV CLASS=COMPLETE>{@code
     * this.name            = name;  
     * this.parent          = parent;
     * this.isDirectory     = true;
     * this.fileSize        = 0;
     * this.lastModified    = lastModified;
     * this.children        = new Vector<>();
     * }</DIV>
     */
    protected FileNode(String name, FileNode parent, long lastModified)
    {
        this.name           = name;  
        this.parent         = parent;
        this.isDirectory    = true;
        this.fileSize       = 0;
        this.lastModified   = lastModified;
        this.children       = new Vector<>();
    }

    /**
     * This constructor builds a {@code FileNode} object which <I>must be a {@code FileNode}-File
     * instance</I> - and may not be a {@code FileNode}-Directory instance.
     *
     * <BR /><BR /><B CLASS=JDDescLabel>{@code FileNode}-File:</B>
     * 
     * <BR /><BR /><B>SPECIFICALLY:</B> The node that is instantiated will have a
     * {@link #isDirectory} value of {@code FALSE}.
     * 
     * <BR /><BR />File-Name validity checks are not performed here.  This constructor has a
     * {@code 'protected'} access level, and is only called internally when a file has been found
     * by getter-calls to {@code java.io.File} (and therefore are extremely unlikely to be
     * invalid).
     * 
     * @param name The name of {@code 'this' FileNode}
     *
     * @param parent This is the parent or "container-directory" of {@code 'this' FileNode}.
     * If a {@code FileNode} that is not a directory itself is passed as the parent, then an
     * exception will be thrown.
     *
     * @param fileSize The size of this file - in bytes.
     *
     * @param lastModified This must be a long value indicating when the file was last modified -
     * according to the Operating-System.  This value may be {@code '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.
     *
     * <DIV CLASS="COMPLETE">{@code
     * this.name            = name;  
     * this.parent          = parent;
     * this.isDirectory     = false;
     * this.fileSize        = fileSize;
     * this.lastModified    = lastModified;
     * this.children        = null;
     * }</DIV>
     */
    protected FileNode(String name, FileNode parent, long fileSize, long lastModified)
    {
        this.name           = name;  
        this.parent         = parent;
        this.isDirectory    = false;
        this.fileSize       = fileSize;
        this.lastModified   = lastModified;
        this.children       = null;
    }

    /**
     * This constructor builds a {@code 'ROOT' FileNode} instance.  These instances are 
     * {@code FileNode}-Directories, but they do not have a parent / container {@code FileNode}.
     * 
     * <BR /><BR />They function indentically to Directory-{@code FileNode's} in all other aspects.
     * 
     * @param name The name of {@code 'this' FileNode}
     */
    protected FileNode(String name)
    {
        if (name.contains("\n")) throw new IllegalArgumentException
            ("File & Directory names may not contain newlines:\n" + name);

        // NOTE: The first if-statement below is a newer (May, 2022) issue that happened.
        //       The Google Cloud Server UNIX Shell Root Directory is named "/"
        //       That haddn't been tested before.

        if (! name.equals(File.separator))

            // All other directories on the File-System are stored with their 'name' field saved
            // with the ending / trailing File.Separator

            if (name.endsWith(File.separator) || name.endsWith("\'"))
                name = name.substring(0, name.length() - 1);

        long lastModified = 0;

        // Make sure this is a directory.  If not, this exception throws since this constructor is
        // the one used by the "createRoot(String)" method.  A "Root FileNode" must always be a 
        // directory

        try
        {
            File f = new File(name);

            if (! f.isDirectory()) throw new IllegalArgumentException(
                "You have attempted to create a new Root Directory - but the filename passed " +
                "isn't a valid Directory Name: [" + name + ']'
            );

            lastModified = f.lastModified();
        }

        catch (SecurityException se)
        { 
            throw new IllegalArgumentException(
                "You have attempted to create a new Root FileNode instance - but a Security " +
                "Exception is preventing this.  See this exception's Throwable.getCause() for " +
                "more details.",
                se
            );
        }

        this.name           = name;  
        this.parent         = null;
        this.isDirectory    = true;
        this.fileSize       = 0;
        this.lastModified   = lastModified;
        this.children       = new Vector<>();
    }

    /**
     * This is the <B>"Factory Method"</B> for this class.  The {@code String name} parameter is
     * intended to be the root directory-name from which the Complete {@code FileNode}-Tree should
     * be built / constructed.
     * 
     * <BR /><BR />The {@code 'name'} parameter passed to this method must be the actual name of
     * an actual directory on the File-System.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Load-Tree Methods:</B>
     * 
     * <BR />Once this Root-Node for a tree has been built (by invoking this method), the next 
     * thing to do is read any / all files &amp; directories that reside on the File-System inside
     * the directory into memory.  This class provides several methods for both total and partial
     * reads of a directory's contents.
     * 
     * <BR /><BR />In the example below, the standard Tree-Loading method {@link #loadTree()} is
     * invoked in order to to read the entire contents of the specified File-System Directory into
     * a {@code FileNode}-Tree in Java Memory.
     *
     * <DIV CLASS="EXAMPLE">{@code
     * FileNode fn = FileNode
     *      .createRoot("etc/MyDataFiles/user123/")
     *      .loadTree();
     * 
     * }</DIV>
     *
     * @return An instance of this class from which a {@code FileNode} tree may be instantiated.
     */
    public static FileNode createRoot(String name)
    { return new FileNode(name); }


    // ********************************************************************************************
    // ********************************************************************************************
    // Load the contents of the MS-DOS or UNIX File-System into this tree-data-structure
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Convenience Method.
     * <BR />Invokes: {@link #loadTree(int, FilenameFilter, FileFilter)}
     * <BR />Passes: All Tree-Branches requested ({@code '-1'})
     * <BR />And-Passes: null-filters (Requests no filtering be applied).
     */
    public FileNode loadTree() { return loadTree(-1, null, null); }

    /**
     * Convenience Method.
     * <BR />Invokes: {@link #loadTree(int, FilenameFilter, FileFilter)}
     * <BR />Passes: {@code 'includeFiles'} as a {@code Predicate} to parameter
     * {@code 'fileFilter'}
     * <BR />Passes: {@code 'includeDirectories'} (as {@code Predicate}) to
     * {@code 'directoryFilter'}
     * <BR />Throws: {@code IllegalArgumentException} If both boolean parameters are {@code FALSE}
     */
    public FileNode loadTree(final boolean includeFiles, final boolean includeDirectories)
    {
        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);
    }

    /**
     * Convenience Method.
     * <BR />Invokes: {@link #loadTree(int, FilenameFilter, FileFilter)}
     * <BR />Passes: <B>'Always False'</B> {@code Predicate} to parameter {@code 'fileFilter'}
     * <BR />Accepts: A {@code 'directoryFilter'} and {@code 'maxTreeDepth'}
     */
    public FileNode loadTreeJustDirs(int maxTreeDepth, FileFilter directoryFilter)
    {
        // Set the return value of the 'fileFilter' predicate to ALWAYS return FALSE.
        return loadTree(maxTreeDepth, (File dir, String name) -> false, directoryFilter);
    }

    /**
     * This populates {@code 'this' FileNode} tree with the contents of the File-System
     * directory represented by {@code 'this'}.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Directory-FileNode:</B>
     * 
     * <BR />This method can only be invoked on an instance of {@code 'FileNode'} which represents
     * a directory on the UNIX or MS-DOS File-System.  A {@code DirExpectedException} shall throw
     * if this method is invoked on a {@code FileNode} instance that represents a file.
     * 
     * <BR /><BR /><EMBED CLASS='external-html' DATA-FILE-ID=FN_LOAD_TREE>
     * 
     * @param maxTreeDepth <EMBED CLASS='external-html' DATA-FILE-ID=FN_MAX_TREE_DEPTH>
     * @param fileFilter <EMBED CLASS='external-html' DATA-FILE-ID=FN_LOAD_T_FILE_FILT>
     * @param directoryFilter <EMBED CLASS='external-html' DATA-FILE-ID=FN_LOAD_T_DIR_FILT>
     *
     * @return a reference to {@code 'this' FileNode}, for convenience only.  It's tree branches
     * (directories) and leaf nodes (files) will be populated, as per the above parameter
     * specification-criteria.
     *
     * @throws DirExpectedException This method will only execute if the instance of {@code 'this'}
     * is a directory.  Files on the File-System are leaves, not branches - so they do not
     * have contents to load.
     * 
     * @throws SecurityException The method <B>{@code java.io.File.listFiles()}</B> is used to
     * retrieve the list of files for each directory.  That method asserts that the Java
     * Security Managaer {@code java.lang.SecurityManager} may throw this exception if a 
     * restricted directory is accessed by {@code 'listFiles()'}.
     * 
     * <BR /><BR /><B STYLE='color: red;'>BY-PASS NOTE:</B> Those most common behavior for
     * restricted directories has been for the {@code listFiles()} to simply return null, which
     * is handled easily by this code.  If this exception is throwing, one may use the internal
     * <B><I>({@code static} flag)</I></B> {@link #SKIP_DIR_ON_SECURITY_EXCEPTION}.  When this
     * <B><I>{@code static-flag}</I></B> is used, {@code SecurityExceptions} are caught, and the
     * contents of those directories will simply be ignored and eliminated from the tree.
     *
     * @see #loadTree()
     * @see DirExpectedException#check(FileNode)
     * @see #SKIP_DIR_ON_SECURITY_EXCEPTION
     */
    public FileNode loadTree
        (int maxTreeDepth, FilenameFilter fileFilter, FileFilter directoryFilter)
    {
        DirExpectedException.check(this);

        loadTreeINTERNAL(maxTreeDepth, fileFilter, directoryFilter);

        return this;
    }

    /**
     * Directories on a UNIX platform that were inaccessible didn't seem to throw a
     * {@code SecurityException}, instead, a null-array was returned.  However, in the case that
     * Java's {@code java.lang.SecurityManager} is catching attempts to access restricted
     * dirtectories and throwing exceptions (which is likely a rare case) - this {@code boolean}
     * flag can inform the internal directory-scanner logic to catch these
     * {@code SecurityException's}.
     * 
     * <BR /><BR />If "catching and skipping" exceptions has been choosen, then any directory
     * that is scanned and would throw an exception, instead is left empty by this class'
     * tree-loading logic.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Thread-Safety:</B>
     * 
     * <BR />This flag is a non-{@code Thread}-Safe feature, because it is a
     * <B>{@code static}-Field Flag</B> that is applied to <I>all instances</I> of class
     * {@code FileNode}
     */
    public static boolean SKIP_DIR_ON_SECURITY_EXCEPTION = false;

    // NOTE: 'this' instance of FileNode will always be a Directory, never File
    private void loadTreeINTERNAL
        (int maxTreeDepth, FilenameFilter fileFilter, FileFilter directoryFilter)
    {
        File f = getJavaIOFile();

        if (VERBOSE) System.out.println(f.getPath());

        // TRICKY! Added: 2019.05.16 - if we are "re-loading" the tree, this line is imperative
        this.children.removeAllElements(); 

        File[] subFilesAndDirs = null;

        // ADDED: 2022.05.18 - The SecurityManager didn't seem to throw a SecurityException for 
        // UNIX directories that could not be accessed.  Instead, it just returned a null-pointer,
        // and this code just threw a NullPointerException.
        // 
        // NOW: This checks for the "SecurityManager" case (which didn't seem to catch it anyway),
        //      and allows the user whether to skip the directory completely, or throw an exception
        //      when "null" is unceremoniously returned, below.

        try
            { subFilesAndDirs = f.listFiles(); }

        catch (SecurityException e)
        {
            if (SKIP_DIR_ON_SECURITY_EXCEPTION) return;
            else                                throw e;
        }

        // RECENT-OCCURENCE: (Never Needed the Google-Cloud-Shell Root Directory)
        // A directory that is denied access, seems to return null.  The Java-Doc for it says it
        // should be throwing a java.lang.SecurityException

        if (subFilesAndDirs == null)
        {
            if (VERBOSE) System.out.println("DIR IS RESTRICTED: " + f.getAbsolutePath());
            return;
        }

        for (File sub : subFilesAndDirs)

            if (sub.isDirectory())
            {
                if (VERBOSE) System.out.println("TESTING DIR: " + sub.getAbsolutePath());

                if (directoryFilter != null) if (! directoryFilter.accept(sub)) continue;

                long lastModified = 0;

                try { lastModified = sub.lastModified(); } catch (SecurityException se) { }

                FileNode newSubDir = new FileNode(sub.getName(), this, lastModified);

                children.addElement(newSubDir);

                if (VERBOSE) System.out.println("ADDED DIR: " + newSubDir.getFullPathName());

                if (maxTreeDepth != 0)
                    newSubDir.loadTreeINTERNAL(maxTreeDepth - 1, fileFilter, directoryFilter);

            }

            else /* sub is a file, not a directory */
            {
                if (fileFilter != null)
                    if (! fileFilter.accept(sub.getParentFile(), sub.getName()))
                        continue;

                long lastModified = 0;

                try { lastModified = sub.lastModified(); } catch (SecurityException se) { }

                children.addElement(new FileNode(sub.getName(), this, sub.length(), lastModified));

                if (VERBOSE) System.out.println
                    ("ADDED FILE: " + sub.getPath() + "\t\t[" + sub.length() + "]");
            }
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Returns information about the contents of the "children Vector<FileNode>"
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * This returns the number of Child-Nodes in {@code 'this'} instance of {@code FileNode}.
     *
     * <BR /><BR /><B CLASS=JDDescLabel>Non-Recursive Check:</B>
     * 
     * <BR />This method is not 'recursive', which means that the integer returned by this method
     * is only a count of the number of <B><I>direct-descendants</I></B> of {@code 'this'}
     * instance.
     * 
     * <BR /><BR />Another way of saying this is that all it returns is the size of the internal
     * {@link #children} {@code Vector}.  It doesn't actually enter any sub-directories to perform
     * this count.
     *
     * @see #numDirChildren()
     * @see #numFileChildren()
     * @see #children
     *
     * @throws DirExpectedException If {@code 'this'} instance of {@code FileNode} is not a
     * directory, but rather a file, then this exception is thrown.  (Files <I>may not</I> have
     * child-nodes, only directories may have them).
     */
    public int numChildren() { DirExpectedException.check(this); return children.size(); }

    /**
     * This returns the exact number of Child-Nodes of {@code 'this'} instance of {@code FileNode}
     * which are <B>directories</B>.
     *
     * <BR /><BR /><B CLASS=JDDescLabel>Non-Recursive Check:</B>
     * 
     * <BR />This method is not 'recursive', which means that the integer returned by this method
     * is only a count of the number of <B><I>direct-descendants</I></B> of {@code 'this'}
     * instance.
     * 
     * <BR /><BR />This method performs a count on the elements of the internal {@link #children}
     * {@code Vector} to see how many elements have an {@link #isDirectory} field set to
     * {@code TRUE}.
     * 
     * @see #numFileChildren()
     * @see #numChildren()
     * @see #children
     *
     * @throws DirExpectedException If {@code 'this'} instance of {@code FileNode} is not a
     * directory, but rather a file, then this exception is thrown.  (Files <I>may not</I> have
     * child-nodes, only directories may have them).
     */
    public int numDirChildren()
    {
        DirExpectedException.check(this);

        int dirCount = 0;

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

        return dirCount;
    }

    /**
     * This returns the exact number of Child-Nodes of {@code 'this'} instance of {@code FileNode}
     * which are <B>files</B>.
     *
     * <BR /><BR /><B CLASS=JDDescLabel>Non-Recursive Check:</B>
     * 
     * <BR />This method is not 'recursive', which means that the integer returned by this method
     * is only a count of the number of <B><I>direct-descendants</I></B> of {@code 'this'}
     * instance.
     * 
     * <BR /><BR />This method performs a count on the elements of the internal {@link #children}
     * {@code Vector} to see how many elements have an {@link #isDirectory} field set to
     * {@code FALSE}.
     *
     * @see #numDirChildren()
     * @see #numChildren()
     * @see #isDirectory
     * @see #children
     *
     * @throws DirExpectedException If {@code 'this'} instance of {@code FileNode} is not a
     * directory, but rather a file, then this exception is thrown.  (Files <I>may not</I> have
     * child-nodes, only directories may have them).
     */
    public int numFileChildren()
    {
        DirExpectedException.check(this);

        int fileCount = 0;

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

        return fileCount;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // retrieve operations
    // ********************************************************************************************
    // ********************************************************************************************


    /** 
     * Convenience Method.
     * <BR />Invokes: {@link #dir(String, boolean)}
     * <BR />Does <B>NOT</B> ignore case
     */
    public FileNode dir(String dirName) { return dir(dirName, false); }

    /**
     * Retrieves the sub-directory {@code FileNode} instance named by parameter {@code 'dirName'}
     * if there is a {@code FileNode} that is a <I>direct descendant</I> of {@code 'this'} instance
     * of {@code FileNode}.
     * 
     * @param dirName This is the name of any directory.
     * 
     * <BR /><BR /><B STYLE="color: red">IMPORTANT:</B> This must be the <I><B>name-only</I></B>
     * leaving out all parent-directory or drive-letter text.
     * 
     * <BR /><BR /><B STYLE="color: red">FURTHERMORE:</B> The forward slash ({@code '/'}) or the
     * back-slash ({@code '\'}) character that sometimes is appended to a directory-name
     * <B><I>may not</I></B> be included in this name (unless a forward-slash or back-slash is
     * a part of the name of the directory).
     * 
     * @param 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 {@code TRUE}, then name comparisons will use
     * a case-insensitive comparison mechanism.
     * 
     * @return The child {@code FileNode} (sub-directory) of this directory whose name matches
     * the name provided by parameter {@code 'dirName'}.
     * 
     * <BR /><BR />If no matching directory is found, then this method shall return null.
     * 
     * @throws DirExpectedException If {@code 'this'} instance of {@code FileNode} is a file,
     * not a directory, then this exception shall throw.  Only directories can contain other
     * instances of {@code FileNode}.
     * 
     * @see #children
     * @see #isDirectory
     * @see #name
     */
    public FileNode dir(String dirName, boolean ignoreCase)
    {
        // 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;
    }

    /** 
     * Convenience Method.
     * <BR />Invokes: {@link #file(String, boolean)}
     * <BR />Does <B>NOT</B> ignore case
     */
    public FileNode file(String fileName) { return file(fileName, false); }

    /**
     * Retrieves a {@code FileNode} named by parameter {@code 'fileName'} if there is a
     * {@code FileNode} instance that is a <I>direct descendant</I> of {@code 'this' FileNode}
     * that is, itself, a file and not a directory.
     * 
     * @param fileName This is the name of any file.
     * 
     * <BR /><BR /><B STYLE="color: red">IMPORTANT:</B> This must be the <I><B>name-only</I></B>
     * leaving out all parent-directory or drive-letter text.
     * 
     * @param 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 {@code TRUE}, then file-name comparisons will use
     * a case-insensitive comparison mechanism.
     * 
     * @return An instance of {@code FileNode} that is a <I>direct-descendant</I> of
     * {@code 'this'} directory - and whose name matches the name provided by parameter
     * {@code 'fileName'}.
     * 
     * <BR /><BR />If no matching file is found, then this method shall return null.
     * 
     * @throws DirExpectedException If {@code 'this'} instance of {@code FileNode} is a file,
     * not a directory, then this exception shall throw.  Only directories can contain other
     * instances of {@code FileNode}.
     * 
     * @see #children
     * @see #isDirectory
     * @see #name
     */
    public FileNode file(String fileName, boolean ignoreCase)
    {
        // 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;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Search and Retrieve Operations, Search the Entire Directory-Tree
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Searches a {@code FileNode}, looking for any branch (directory) or leaf-node (file) that
     * positively matches the provided filter parameter {@code 'f'}.  Exits and returns immediately
     * upon finding such a match.
     * 
     * <BR /><BR />Here, a Source-Code Directory is searched for the first file or directory that
     * is found which has a {@link #lastModified} value greater than 12:01 AM, today.
     * 
     * <DIV CLASS=EXAMPLE>{@code
     * // Create a LocalDateTime object for 12:01 AM of today, and converts that to milliseconds
     * // From the Java Time Package (java.time.*)
     * 
     * final long TODAY = LocalDateTime
     *      .of(LocalDate.now(), LocalTime.of(0, 1));
     *      .toInstant(ZoneOffset.UTC).toEpochMilli();
     * 
     * String todaysFile = FileNode
     *      .createRoot("src/main/")
     *      .loadTree()
     *      .findFirst((FileNode fn) -> fn.lastModified >= TODAY)
     *      .getFullPathName();
     * }</DIV>
     * 
     * @param f Any filter may be used for selecting the file instance being searched.
     * 
     * @return The first {@code FileNode} instance in {@code 'this'} tree that matches the
     * provided filter-predicate.
     * 
     * <BR /><BR />If no matching node is found, then this method shall return null.
     * 
     * @throws DirExpectedException If {@code 'this'} instance of {@code FileNode} is a file,
     * not a directory, then this exception shall throw.  Only directories can contain other
     * instances of {@code FileNode}.
     * 
     * @see #children
     * @see #isDirectory
     */
    public FileNode findFirst(FileNodeFilter f)
    {
        // Only directories may contain other instances of FileNode
        DirExpectedException.check(this);

        return ffINTERNAL(f);
    }

    // This is included to optimize away the preliminary exception check in the previous method,
    // that is directly above.  Other than the exception-check these two methods are identical.

    private FileNode ffINTERNAL(FileNodeFilter f)
    {
        for (FileNode fn : children) if (f.test(fn)) return fn;

        for (FileNode fn : children)
            if (fn.isDirectory)
                if ((fn = fn.ffINTERNAL(f)) != null)
                    return fn;

        return null;
    }

    /**
     * Traverses {@code 'this'} tree instance looking for any {@code FileNode} instance that 
     * is a directory, and matches the filter selector parameter {@code 'f'} predicate
     * {@code 'test'} method.
     * 
     * <BR /><BR />This method will exit and return the first such match it encounters in the
     * tree.
     * 
     * <BR /><BR />In the example below, a {@code FileNode}-Tree is built out of one particular
     * {@code 'src/main'} directory, and then that entire directory is searched for any sub-folder
     * (anywhere in the sub-tree) whose name is equal to {@code 'MyImportantClasses'}.
     * 
     * <DIV CLASS=EXAMPLE>{@code
     * FileNode myFolder = FileNode
     *      .createRoot("My Source Code/src/main/")
     *      .loadTree()
     *      .findFirstDir((FileNode fn) -> fn.name.equals("MyImportantClasses"))
     * }</DIV>
     * 
     * <BR /><BR />In this example, a local directories' "sub-tree" is searched for any sub-folder
     * that has at least 15 non-directory files inside.
     * 
     * <DIV CLASS=EXAMPLE>{@code
     * FileNode atLeast10 = FileNode
     *      .createRoot("My Saved PDFs")
     *      .loadTree()
     *      .findFirstDir((FileNode fn) -> fn.numFileChildren() >= 15);
     * }</DIV>
     * 
     * @param f Any filter may be used for selecting the {@code FileNode} directory instance being
     * searched.
     * 
     * @return The first {@code FileNode} instance in {@code 'this'} tree whose
     * {@link #isDirectory} flag is {@code TRUE} and, furthermore, matches the provided
     * filter-predicate.
     * 
     * <BR /><BR />If no matching directory is found, then this method shall return null.
     * 
     * @throws DirExpectedException If {@code 'this'} instance of {@code FileNode} is a file,
     * not a directory, then this exception shall throw.  Only directories can contain other
     * instances of {@code FileNode}.
     * 
     * @see #children
     * @see #isDirectory
     */
    public FileNode findFirstDir(FileNodeFilter f)
    {
        // Only directories may contain other instances of FileNode
        DirExpectedException.check(this);

        return ffdINTERNAL(f);
    }

    // Optimizes away the exception check
    private FileNode ffdINTERNAL(FileNodeFilter f)
    {
        for (final FileNode fn : children) if (fn.isDirectory && f.test(fn)) return fn;

        for (FileNode fn : children)
            if (fn.isDirectory)
                if ((fn = fn.ffdINTERNAL(f)) != null)
                    return fn;

        return null;
    }

    /**
     * This method is extremely similar to {@link #findFirstDir(FileNodeFilter)}, but searches
     * for leaf-node files, instead of sub-folders / directories.
     * 
     * @param f Any filter may be used for selecting the file instance being searched.
     * 
     * @return The first {@code FileNode} instance in {@code 'this'} tree whose
     * {@link #isDirectory} flag is {@code FALSE} and, furthermore, matches the provided
     * filter-predicate.
     * 
     * <BR /><BR />If no matching directory is found, then this method shall return null.
     * 
     * @throws DirExpectedException If {@code 'this'} instance of {@code FileNode} is a file,
     * not a directory, then this exception shall throw.  Only directories can contain other
     * instances of {@code FileNode}.
     * 
     * @see #children
     * @see #isDirectory
     */
    public FileNode findFirstFile(FileNodeFilter f)
    {
        // Only directories may contain other instances of FileNode
        DirExpectedException.check(this);

        return fffINTERNAL(f);
    }

    // Optimizes away the exception check
    private FileNode fffINTERNAL(FileNodeFilter f)
    {
        for (final FileNode fn : children) if ((! fn.isDirectory) && f.test(fn)) return fn;

        for (FileNode fn : children)
            if (fn.isDirectory)
                if ((fn = fn.fffINTERNAL(f)) != null)
                    return fn;

        return null;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // poll operations
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Convenience Method.
     * <BR />Invokes: {@link #pollDir(String, boolean)}
     * <BR />Does <B>NOT</B> ignore case
     */
    public FileNode pollDir(String dirName) { return pollDir(dirName, false); }

    /**
     * Retrieves the sub-directory {@code FileNode} instance named by parameter {@code 'dirName'}
     * if there is a {@code FileNode} that is a <B>Direct Descendant</B> of {@code 'this'}
     * instance of {@code FileNode}.
     * 
     * <EMBED CLASS='external-html' DATA-KIND=dir DATA-NAME=directory DATA-FILE-ID=FN_POLL_DIRFILE>
     * 
     * @param dirName This is the name of any directory.
     * 
     * <BR /><BR /><B STYLE="color: red">IMPORTANT:</B> This must be the <I><B>name-only</I></B>
     * leaving out all parent-directory or drive-letter text.
     * 
     * <BR /><BR /><B STYLE="color: red">FURTHERMORE:</B> The forward slash ({@code '/'}) or the
     * back-slash ({@code '\'}) character that sometimes is appended to a directory-name
     * <B><I>may not</I></B> be included in this name (unless a forward-slash or back-slash is
     * a part of the name of the directory).
     * 
     * <BR /><BR /><B STYLE="color: red">FINALLY:</B> When this directory is extracted, none
     * of the child pointers contained by this directory-instance of {@code FileNode} will be
     * modified.  In essence, the entire sub-tree - <I>starting at the directory that was 
     * specified</I> - 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.
     * 
     * @param 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 {@code TRUE}, then name comparisons will use
     * a case-insensitive comparison mechanism.
     * 
     * @return The child {@code FileNode} (sub-directory) of {@code 'this'} directory whose name
     * matches the name provided by parameter {@code 'dirName'}.  It's {@code 'parent'} field
     * will be null, and the parent {@code FileNode} instance will not have a pointer to the
     * instance that is returned.
     * 
     * <BR /><BR />If no matching directory is found, then this method shall return null.
     * 
     * @throws DirExpectedException If {@code 'this'} instance of {@code FileNode} is a file,
     * not a directory, then this exception shall throw.  Only directories can contain other
     * instances of {@code FileNode}.
     * 
     * @see #dir(String, boolean)
     * @see #children
     */
    public FileNode pollDir(String dirName, boolean ignoreCase)
    {
        FileNode ret = dir(dirName, ignoreCase);

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

        return ret;
    }

    /** 
     * Convenience Method.
     * <BR />Invokes: {@link #pollFile(String, boolean)}
     * <BR />Does <B>NOT</B> ignore case
     */
    public FileNode pollFile(String fileName) { return pollFile(fileName, false); }

    /**
     * Retrieves a {@code FileNode} instance named by parameter {@code 'fileName'} if there is
     * a {@code FileNode} that is a <B>Direct Descendant</B> of {@code 'this'} instance
     * of {@code FileNode}, <B><I>and</I></B> that instance is a file (not a directory) whose
     * name matches parameter {@code 'fileName'}.
     * 
     * <EMBED CLASS='external-html' DATA-KIND=file DATA-NAME=file DATA-FILE-ID=FN_POLL_DIRFILE>
     * 
     * @param fileName This is the name of any file.
     * 
     * <BR /><BR /><B STYLE="color: red">IMPORTANT:</B> This must be the <I><B>name-only</I></B>
     * leaving out all parent-directory or drive-letter text.
     * 
     * @param 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 {@code TRUE}, then name comparisons will use
     * a case-insensitive comparison mechanism.
     * 
     * @return The child {@code FileNode} of {@code 'this'} directory whose name matches the
     * name provided by parameter {@code 'fileName'}.  It's {@code 'parent'} field
     * will be null, and the parent {@code FileNode} instance will not have a pointer to the
     * instance that is returned.
     * 
     * <BR /><BR />If no matching file is found, then this method shall return null.
     * 
     * @throws DirExpectedException If {@code 'this'} instance of {@code FileNode} is a file,
     * not a directory, then this exception shall throw.  Only directories can contain other
     * instances of {@code FileNode}.
     * 
     * @see #file(String, boolean)
     */
    public FileNode pollFile(String fileName, boolean ignoreCase)
    {
        FileNode ret = file(fileName, ignoreCase);

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

        return ret;
    }

    /**
     * Extracts {@code 'this' FileNode} from its parent's tree.
     * @return returns {@code 'this'} for convenience.
     */
    public FileNode pollThis()
    {
        if (this.parent == null) throw new FileNodeException 
            ("Attempting to poll a FileNode, but it's directory-parent FileNode is null");

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

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

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

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

        if (! removed) throw new UnreachableError();

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

        return this;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // These methods satisfy the Cloneable, Comparable, CharSequence Interfaces
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * This satisfies Java's "hash-code" method requirement.  This can facilitate saving instances
     * of this class into tables, maps, lists, etc.
     *
     * @return A hash-code to be used by a hash-algorithm with likely few crashes.  Note that the
     * hash from Java's {@code java.lang.String} is simply reused.
     */
    public int hashCode() { return toString().hashCode(); }

    /*
     * Java's {@code equals(Object o)} method requirements.
     *
     * <BR /><BR /><B CLASS=JDDescLabel>Final Method:</B>
     * 
     * <BR />This method is final, and cannot be modified by sub-classes.
     * 
     * @param o This may be any {@code java.lang.Object}, but only ones of {@code 'this'} type
     * whose internal-values are identical will cause this method to return {@code TRUE}.
     *
     * @return {@code TRUE} If {@code 'this'} instance' internal-fields are equal to the
     * internal-fields another {@code FileNode} instance.
     * 
     * <BR /><BR /><B><SPAN STYLE='color: red;">DEEP-EQUALS:</B></SPAN> Due to how Java's
     * {@code class Vector} has implemented it's {@code Vector.equals(other)} method - which is
     * how the child tree-branches of a directory {@code FileNode} stores it's directory
     * branches - this method <I>does, indeed, perform a 'Deep Equals'</I>.
     *
     * @see FileNode#name
     * @see FileNode#parent
     * @see FileNode#isDirectory
     * @see FileNode#children
     */
    public final boolean equals(Object o)
    {
        FileNode other;

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

    /**
     * Java's {@code interface Cloneable} requirements.  This instantiates a new {@code FileNode}
     * with identical fields.  The field {@code Vector<FileNode> 'children'} shall be cloned too.
     *
     * @return A new {@code FileNode} whose internal fields are identical to this one.
     *
     * <BR /><BR /><B><SPAN STYLE="color: red;">IMPORTANT (DEEP-CLONE) NOTE:</SPAN></B> This
     * <B>does not</B> perform a deep-tree-traversal clone.  Instead, {@code 'this'} instance is
     * merely copied, and it's child nodes have references inserted into the internal list of
     * child-nodes.
     *
     * @see FileNode#name
     * @see FileNode#parent
     * @see FileNode#isDirectory
     */
    public FileNode clone()
    {
        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);
    }

    /**
     * Java's {@code Comparable<T>} Interface-Requirements.  This does a very simple comparison 
     * using the results to a call of method {@link #getFullPathName()}
     *
     * @param fn Any other {@code FileNode} to be compared to {@code 'this' FileNode}.  The file
     * or directories {@code getFullPathName()} is used to perform a "String" comparison.
     *
     * @return An integer that fulfils Java's {@code interface Comparable<T> public boolean 
     * compareTo(T t)} method requirements.
     *
     * @see #getFullPathName()
     */
    public final int compareTo(FileNode fn)
    { return this.getFullPathName().compareTo(fn.getFullPathName()); }

    /**
     * This is an "alternative Comparitor" that can be used for sorting instances of this class.
     * It should work with the {@code Collections.sort(List, Comparator)} method in the standard 
     * JDK package {@code java.util.*;}
     *
     * <BR /><BR /><B CLASS=JDDescLabel>Comparison Heuristic:</B>
     * 
     * <BR />This version utilizes the standard JDK {@code String.compareToIgnoreCase(String)}
     * method.
     *
     * @see #getFullPathName()
     */
    public static final Comparator<FileNode> comp2 = (FileNode fn1, FileNode fn2) ->
        fn1.getFullPathName().compareToIgnoreCase(fn2.getFullPathName());

    /**
     * Converts {@code 'this' FileNode} to a {@code String}.
     *
     * @return The complete-full path-name of this file or directory.
     */
    public String toString() { return this.getFullPathName(); }

    /**
     * Returns the {@code char} value at the specified index of the results to a call of method
     * {@link #getFullPathName()}.  An index ranges from {@code zero} to {@code length() - 1}.  The
     * first {@code char} value of the sequence is at index {@code zero}, the next at index
     * {@code one}, and so on and so forth - as per array indexing.
     *
     * <BR /><BR /><B CLASS=JDDescLabel>Character Surrogates:</B>
     * 
     * <BR />If the {@code char} value specified by the index is a surrogate,
     * the surrogate value is returned.
     *
     * <BR /><BR /><B CLASS=JDDescLabel>Final Method:</B>
     * 
     * <BR />This method is final, and cannot be modified by sub-classes.
     * 
     * @param index The index of the {@code char} value to be returned
     *
     * @return The specified {@code char} value
     *
     * @see #getFullPathName()
     */
    public final char charAt(int index) { return this.getFullPathName().charAt(index); }

    /**
     * Returns the length of the {@code String} returned by {@code public String getFullPathName()}
     * The length is the number of 16-bit characters in the sequence.
     *
     * <BR /><BR /><B CLASS=JDDescLabel>Final Method:</B>
     * 
     * <BR />This method is final, and cannot be modified by sub-classes.
     * 
     * @return the number of characters in the "Full Path Name" for {@code 'this'} file or\
     * directory.
     *
     * @see #getFullPathName()
     */
    public final int length() { return this.getFullPathName().length(); }

    /**
     * Returns a {@code java.lang.CharSequence} that is a subsequence of the results to a call of
     * method {@link #getFullPathName()}
     *
     * <BR /><BR /> The subsequence starts with the {@code char} value at the specified index and 
     * ends with the {@code char} value at index {@code 'end - 1'}.  The length (in characters) of
     * the returned sequence is {@code 'end - start'},  so in the case where
     * {@code 'start == end'} then an empty sequence is returned.
     *
     * <BR /><BR /><B CLASS=JDDescLabel>Final Method:</B>
     * 
     * <BR />This method is final, and cannot be modified by sub-classes.
     * 
     * @param start The start index, inclusive
     * @param end The end index, exclusive
     *
     * @return The specified subsequence
     * @see #getFullPathName()
     */
    public final CharSequence subSequence(int start, int end)
    { return this.getFullPathName().substring(start, end); }


    // ********************************************************************************************
    // ********************************************************************************************
    // Deep-Tree Traversal
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Whereas the standard Java {@code clone()} method in this class returns a new, cloned,
     * instance of {@code FileNode}, if {@code 'this'} instance of {@code FileNode} is a directory,
     * the tree-branch represented by {@code 'this' FileNode} instance would not be copied by an
     * invocation of {@code 'clone'}.  However, if using this method, {@code 'deepClone'}, on a
     * directory-{@code FileNode} instance, <B><I>the entire tree-branch represented by
     * {@code 'this' FileNode} instance is copied.</I></B>.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Deep-Clone:</B>
     * 
     * <BR />The method's {@code clone()} and {@code deepClone()} shall return identical results
     * when used on an instance of {@code FileNode} that represents a file, rather than a directory
     * (<I>and, therefore, does not have any tree-branch information associated with it.</I>).
     * 
     * @return a <B>"Deep Clone"</B> of {@code 'this' FileNode} instance.  If {@code 'this'}
     * instance of {@code FileNode} represents a file, not a directory, the results of this method
     * shall be identical to the results of an invocation of the standard {@code 'clone()'} method.
     * If {@code '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.
     */
    public FileNode deepClone()
    {
        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();
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Basic Methods
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * This returns the name of the file, but leaves off the "extension"
     * @return Returns the name <I>without the file-extension</I>
     * 
     * @throws FileExpectedException Since only files may have extensions, if {@code 'this'}
     * instance of {@code FileNode} is a directory, the {@code FileExpectedException} will throw.
     */
    public String nameNoExt()
    {
        FileExpectedException.check(this);  // Directories do not have extensions

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

        if (pos == -1) return name;

        return name.substring(0, pos);
    }

    /**
     * This returns the extension of the file.  If this file does not have an extension,
     * then null shall be returned.
     *
     * @param includeTheDot if the user would like to have the {@code '.'} included in the
     * return {@code String}, then {@code TRUE} should be passed to this parameter.  
     *
     * @return Returns this file's extension
     * 
     * @throws FileExpectedException Since only files may have extensions, if {@code 'this'}
     * instance of {@code FileNode} is a directory, the {@code FileExpectedException} will throw.
     */
    public String ext(boolean includeTheDot)
    {
        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);        
    }

    /**
     * Invokes the input Java {@code Consumer<FileNode>} on each element in {@code 'this'} 
     * {@code FileNode}-Tree.  Note that if {@code 'this'} instance of is a file, not a directory,
     * then the passed {@code Consumer} shall only be invoked once (on {@code 'this'} instance,
     * since files do not have sub-directories).
     *
     * @param c This is any java {@code Consumer<FileNode>}
     */
    public void forEach(Consumer<FileNode> c)
    {
        c.accept(this);
        if (children != null) children.forEach((FileNode fn) -> fn.forEach(c));
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Print Tree - self explanatory
    // ********************************************************************************************
    // ********************************************************************************************


    /** 
     * Convenience Method.
     * <BR />Passes: {@code System.out} to {@code Appendable}, and nulls
     * <BR />Invokes: {@link #printTree(Appendable, boolean, FileNodeFilter, FileNodeFilter)}
     * <BR />Catches: {@code Appendable's IOException}.  Prints Stack Trace.
     */
    public void printTree()
    {
        try
            { printTree(System.out, false, null, null); }

        catch (IOException e)
            { e.printStackTrace(); }
    }

    /** 
     * Convenience Method.
     * <BR />Passes: 'null' to {@code Appendable} parameter (uses {@code System.out})  
     * <BR />Invokes: {@link #printTree(Appendable, boolean, FileNodeFilter, FileNodeFilter)}
     * <BR />Catches: {@code Appendable's IOException} 
     */
    public void printTreeNOIOE
        (boolean showSizes, FileNodeFilter fileTest, FileNodeFilter directoryTest)
    { try { printTree(null, showSizes, fileTest, directoryTest); } catch (IOException ioe) { } }

    /**
     * This will print the directory tree to the {@code java.lang.Appendable} passed as a
     * parameter.  Specific Test-{@code Predicate's} may be sent to this method to identify which
     * branches of the File-System Directory-Tree should be printed.
     *
     * @param a If this is null, then {@code System.out} is used.  If it is not null, then
     * information is printed to this Java {@code java.lang.Appendable}.
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=APPENDABLE>
     *
     * @param showSizes If this is true, then "file-size" information will also be printed with the
     * file.
     *
     * @param fileTest If this is null, then it is ignored, and all <B>files</B> in the
     * {@code FileNode} Directory-Tree pass (are accepted).
     * 
     * <BR /><BR />If this parameter is not null, then each {@code FileNode} that is not a
     * directory is run through this {@code Predicate's} test method.  If the test returns
     * {@code FALSE}, then this file is not printed to the output.
     *
     * @param directoryTest If this is null, then it is ignored, and all <B>directories</B> in
     * the {@code FileNode} Directory-Tree pass (are accepted).
     * 
     * <BR /><BR />If this parameter is not null, then each {@code FileNode} that is a directory is
     * run through this {@code Predicate's} test method, and any directories that fail this
     * {@code Predicate's test()} method (when {@code directoryTest.test(dir)} returns
     * {@code FALSE}), that directory will not be printed to the output.
     *
     * @throws IOException Java's {@code interface Appendable} mandates that the unchecked Java
     * {@code IOException} must be caught when using this interface.
     *
     * @see #printTree()
     * @see #getDirContentsFiles()
     * @see #getDirContentsDirs()
     * @see #fileSize
     * @see #getFullPathName
     */
    public void printTree
        (Appendable a, boolean showSizes, FileNodeFilter fileTest, FileNodeFilter directoryTest)
        throws IOException
    {
        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);
        }
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // These check the size of a directory's contents.  The perform the sums using recursion
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Convenience Method.
     * <BR />Invokes: {@link #getDirContentsSize(FileNodeFilter)}
     * <BR />Passes: null to filter-parameter {@code 'fileTest'}. (All file-sizes are counted)
     */
    public long getDirContentsSize()
    { return getDirContentsSize(null); }

    /**
     * This sums the file-sizes of each file <B>in the current directory, not sub-directories</B>
     * that pass the requirements of the {@code Predicate<FileNode>} here.  If
     * {@code p.test(fileNode)} fails, then the size of a {@code FileNode} is not counted in the
     * total sum.
     *
     * <BR /><BR /><B CLASS=JDDescLabel>Non-Recursive Method:</B>
     * 
     * <BR />This only retrieves the contents of {@code 'this'} directory - and does not expand or
     * visit any sub-directories - when computing the total size of the files!
     *
     * @param fileTest Any Java Lambda-Expression that satisfies the requirement of having a
     * {@code public boolean test(FileNode); } method.   An instance of the interface
     * {@code 'FileNodeFilter'} will also work.
     *
     * <BR /><BR />This is used to "test" whether to include the files in a directory'
     * {@link #fileSize} in the summed return value.  When {@code TRUE} is returned by the 
     * {@code Predicate test(...)} method, a file's size will be included in the sum-total
     * directory-size.  When the {@code Predicate test(...)} method returns {@code FALSE}, the
     * tested file's size will be ignored and not included in the total.
     *
     * <BR /><BR />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.
     *
     * @return The sum of file-sizes for each file which passes the {@code Predicate} test in this
     * directory.
     *
     * @throws DirExpectedException If {@code 'this'} instance of {@code FileNode} is not a
     * directory, but rather a file, then this exception is thrown.  (Files <I>may not</I> have
     * child-nodes, only directories).
     *
     * @see #fileSize
     * @see #children
     * @see #isDirectory
     */
    public long getDirContentsSize(FileNodeFilter fileTest)
    {
        DirExpectedException.check(this);

        long size=0;           

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

        return size;        
    }

    /**
     * Convenience Method.
     * <BR />Invokes: {@link #getDirTotalContentsSize(FileNodeFilter, FileNodeFilter)}
     * <BR />Passes: null to both-filters (all file-sizes counted, no directories skipped)
     */
    public long getDirTotalContentsSize()
    { return getDirTotalContentsSize(null, null); }

    /**
     * This sums the file contents in the current directory - and all sub-directories as well.
     * Only files that pass the {@code Predicate 'fileTest'} parameter are counted.  Furthermore,
     * only directories that pass the {@code Predicate 'directoryTest'} will be traversed and
     * inspected.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Recursive Method:</B>
     * 
     * <BR />This method computes the sizes of the files, recursively.  Tbis method enters 
     * sub-directories (provided they pass the {@code 'directoryTest'}) to compute the total file
     * size.
     *
     * @param fileTest Any Java Lambda-Expression that satisfies the requirement of having a
     * {@code public boolean test(FileNode); } method.   An instance of the interface
     * {@code 'FileNodeFilter'} will also work.
     *
     * <BR /><BR />This is used to "test" whether to include the {@link #fileSize} for a specific
     * file in a directory in the summed return value.  When {@code TRUE} is returned by the
     * {@code Predicate 'test'}  method, a file's size will be included in the sum-total
     * directory-size.  When the {@code Predicate 'test'} method returns {@code FALSE}, the tested
     * file's size will be ignored, and not included in the total.
     *
     * <BR /><BR />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.
     *
     * @param directoryTest Any Java Lambda-Expression that satisfies the requirement of having a
     * {@code public boolean test(FileNode); } method.   An instance of the interface
     * {@code 'FileNodeFilter'} will also work.
     *
     * <BR /><BR />This is used to test directories, rather than files, for inclusion in the total
     * file-size returned by this method.  When {@code TRUE} is returned by the filter's
     * {@code 'test'} method, then that directory shall be traversed, inspected, and its contents
     * shall have their {@code fileSize's} included in the computed result.
     *
     * <BR /><BR />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.
     *
     * @return The sum of all file-sizes for each file in this directory that pass
     * {@code 'fileTest'}, and all sub-dir's that pass the {@code 'directoryTest'}.
     *
     * @throws DirExpectedException If {@code 'this'} instance of {@code FileNode} is not a 
     * directory, but rather a file, then this exception is thrown.  (Files <I>may not</I> have
     * child-nodes, only directories).
     (
     * @see #fileSize
     * @see #children
     * @see #getDirTotalContentsSize()
     */
    public long getDirTotalContentsSize(FileNodeFilter fileTest, FileNodeFilter directoryTest)
    {
        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;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // These count files and sub-directories
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Convenience Method.
     * <BR />Invokes: {@link #count(FileNodeFilter, FileNodeFilter)}
     * <BR />Passes: null to both filter-parameters. (All files and directories are counted)
     */
    public int count() { return count(null, null); }

    /**
     * Performs a count on the total number of files and directories contained by {@code 'this'}
     * directory.  This method is recursive, and traverses both {@code 'this'} directory, and all
     * sub-directories when calculating the return-value.
     *
     * @param fileFilter This allows a user to eliminate certain files from the total count.
     * 
     * <BR /><BR />The filter provided should be a {@code Predicate<FileNode>} that returns
     * {@code TRUE} if the file <I>should be counted</I>, and {@code FALSE} if the file <I>should
     * <B>not</B></I> be counted.
     *
     * <BR /><BR />This parameter may be {@code 'null'}, and if it is, it will be ignored.  In
     * such cases, all files will be included in the total count.
     * 
     * @param directoryFilter This allows a user to skip branches of the directory-tree when
     * performing the count.
     * 
     * <BR /><BR />The filter provided should be a {@code Predicate<FileNode>} that returns
     * {@code TRUE} if the sub-directory <I>should be entered</I> (and counted), and {@code FALSE}
     * if the sub-directory tree-branch <I>should be skipped</I> completely.
     *
     * <EMBED CLASS='external-html' DATA-FILE-ID=FN_COUNT_DIRFILT>
     *
     * @return A total count of all files and sub-directories contained by {@code 'this'} instance
     * of {@code 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
     * {@code FileNode} that is a 'file' rather than a 'directory'.
     */
    public int count(FileNodeFilter fileFilter, FileNodeFilter directoryFilter)
    {
        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);
    }

    private int countINTERNAL(FileNodeFilter fileFilter, FileNodeFilter directoryFilter)
    {
        int count = 0;

        for (FileNode fn : children)

            if (fn.isDirectory)
            {
                if ((directoryFilter == null) || directoryFilter.test(fn))
                    count += 1 /* 'this' adds 1 */ + fn.countINTERNAL(fileFilter, directoryFilter);
            }
            else
                if ((fileFilter == null) || fileFilter.test(fn))
                    count++;

        return count;
    }

    /**
     * Convenience Method.
     * <BR />Invokes: {@link #countJustFiles(FileNodeFilter, FileNodeFilter)}
     * <BR />Passes: null to both filter-parameters
     * (all <B>files</B> counted, no directories skipped).
     */
    public int countJustFiles() { return countJustFiles(null, null); }

    /**
     * Performs a count on the total number of <I><B>files only</I></B> (does not count sub
     * directories) contained by {@code 'this'} directory.  This method is recursive, and traverses
     * both {@code 'this'} directory, and all sub-directories when calculating the return-value.
     *
     * @param fileFilter This allows a user to eliminate certain files from the total count.
     * 
     * <BR /><BR />The filter provided should be a {@link FileNodeFilter} (Predicate} /
     * Lambda-Expression that returns {@code TRUE} if the file <I>should be counted</I>, and
     * {@code FALSE} if the file <I>should <B>not</B></I> be counted.
     *
     * <BR /><BR />This parameter may be {@code 'null'}, and if it is, it will be ignored.  In
     * such cases, all files will be included in the total count.
     * 
     * @param directoryFilter This allows a user to skip branches of the directory-tree when
     * performing the count.
     * 
     * <BR /><BR />The filter provided should be a {@link FileNodeFilter} (Predicate} /
     * Lambda-Expression that returns {@code TRUE} if the sub-directory <I>should be entered</I>
     * (the directory itself will not contribute to the count).  When this filter returns
     * {@code FALSE} the sub-directory tree-branch <I>will be skipped</I> completely, and any files
     * in those sub-directories will not contribute to the total file-count.
     *
     * <EMBED CLASS='external-html' DATA-FILE-ID=FN_COUNT_DIRFILT>
     *
     * @return A total count of all files (excluding sub-directories) contained by {@code 'this'}
     * instance of {@code FileNode} - less the files that reside in directory-tree branches that
     * were excluded by the {@code 'directoryFilter'} parameter <B><I>and</I></B> less the files
     * that were excluded by {@code 'fileFilter'}.
     *
     * @throws DirExpectedException If the user has attempted to perform a count on a
     * {@code FileNode} that is a 'file' rather than a 'directory'.
     */
    public int countJustFiles(FileNodeFilter fileFilter, FileNodeFilter directoryFilter)
    {
        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);
    }

    private int countJustFilesINTERNAL(FileNodeFilter fileFilter, FileNodeFilter directoryFilter)
    {
        int count = 0;

        for (FileNode fn : children)

            if (fn.isDirectory)
            {
                if ((directoryFilter == null) || directoryFilter.test(fn))
                    count += fn.countJustFilesINTERNAL(fileFilter, directoryFilter);
            }

            else // fn is a file, not a dir.
                if ((fileFilter == null) || fileFilter.test(fn))
                    count++;

        return count;
    }

    /**
     * Convenience Method.
     * <BR />Invokes: {@link #countJustDirs(FileNodeFilter)}
     * <BR />Passes: null to {@code 'directorFilter'} (all <B>directories</B> are counted).
     */
    public int countJustDirs() { return countJustDirs(null); }

    /**
     * Performs a count on the total number of sub-directories contained by {@code 'this'}
     * directory.  This method is recursive, and traverses all sub-directories when calculating
     * the return-value.
     *
     * @param directoryFilter This allows a user to skip branches of the directory-tree when
     * performing the count.
     * 
     * <BR /><BR />The filter provided should be a {@link FileNodeFilter} (Predicate} /
     * Lambda-Expression that returns {@code TRUE} if the sub-directory <I>should be entered</I>
     * and {@code FALSE} if sub-directory tree-branch <I>should be skipped</I> completely.
     *
     * <EMBED CLASS='external-html' DATA-FILE-ID=FN_COUNT_DIRFILT>
     *
     * @return A total count of all sub-directories contained by {@code 'this'}
     * instance of {@code FileNode} - less the sub-directories that reside in directory-tree
     * branches that were excluded by the {@code 'directoryFilter'} parameter.
     *
     * @throws DirExpectedException If the user has attempted to perform a count on a
     * {@code FileNode} that is a 'file' rather than a 'directory'.
     */
    public int countJustDirs(FileNodeFilter directoryFilter)
    {
        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);
    }

    private int countJustDirsINTERNAL
        (FileNodeFilter directoryFilter)
    {
        int count = 0;

        if (directoryFilter == null)

            for (FileNode fn1 : children)
                if (fn1.isDirectory)
                    count += 1 /* 'this' adds 1 */ + fn1.countJustDirsINTERNAL(directoryFilter);

        else

            for (FileNode fn2 : children)
                if (fn2.isDirectory)
                    if (directoryFilter.test(fn2))
                        count +=1 /* 'this' adds 1 */ + fn2.countJustDirsINTERNAL(directoryFilter);

        return count;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // ALL - a single level in the file-tree.
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Convenience Method.
     * <BR />Automatically Selects: {@link RTC#VECTOR()}
     * <BR />Invokes: {@link #getDirContents(RTC, FileNodeFilter)}
     * <BR />Passes: null to parameter {@code 'filter'}
     * (all files and directories found will be returned).
     */
    public Vector<FileNode> getDirContents()
    { return getDirContents(RTC.VECTOR(), null); }

    /**
     * Convenience Method.
     * <BR />Accepts: {@link RTC}.  (Specifies Output Data-Structure &amp; Contents)
     * <BR />Invokes: {@link #getDirContents(RTC, FileNodeFilter)}
     * <BR />Passes: null to parameter {@code 'filter'}
     * (all files and directories found will be returned).
     */
    public <T> T getDirContents(RTC<T> returnedDataStructureChoice)
    { return getDirContents(returnedDataStructureChoice, null); }

    /**
     * Convenience Method.
     * <BR />Automatically Selects: {@link RTC#VECTOR()}
     * <BR />Accepts: {@link FileNodeFilter}
     * <BR />Invokes: {@link #getDirContents(RTC, FileNodeFilter)}
     */
    public Vector<FileNode> getDirContents(FileNodeFilter filter)
    { return getDirContents(RTC.VECTOR(), filter); }

    /**
     * This method returns the contents of a <I>single-directory in the directory-tree</I>, the 
     * sub-directories are returned, but the contents of the sub-directories are not.  Any method
     * whose name begins with {@code 'getDirContents ...'} will not traverse the directory tree.
     * Instead, <I>only the contents of the internal {@code 'children' Vector<FileNode>} of
     * {@code 'this'} instance of {@code FileNode} are iterated and returned.</I>
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=FN_DIR_CONTENTS>
     *
     * @param <T> <EMBED CLASS='external-html' DATA-FILE-ID=FN_RTC_TYPE_PARAM>
     * @param returnedDataStructureChoice <EMBED CLASS='external-html' DATA-FILE-ID=FN_RTC_PARAM>
     * 
     * @param filter When this parameter is used, any files or directories that do not pass the
     * {@code filter's 'test'} method shall not be included in the returne data-structure.
     * 
     * <BR /><BR />The {@code filter} that is passed should return {@code TRUE} when a file or
     * directory needs to be included in the returned-result.  When the provided {@code filter}
     * returns {@code FALSE} as a result of testing a file or directory, the returned
     * Data-Structure will exclude it.
     *
     * <BR /><BR />If this parameter is null, it will be ignored, and every {@code FileNode}
     * contained by {@code 'this'} directory-instance will be included in the result.
     * 
     * @return A list containing the files &amp; sub-directories inside {@code 'this'} directory. 
     * <EMBED CLASS='external-html' DATA-FILE-ID=FN_RTC_RET>
     *
     * @throws DirExpectedException <EMBED CLASS='external-html' DATA-FILE-ID=FN_DIR_C_DIR_EXP_EX>
     * @see FileNodeFilter
     * @see #children
     */
    public <T> T getDirContents(RTC<T> returnedDataStructureChoice, FileNodeFilter filter)
    {
        DirExpectedException.check(this);

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

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

        return returnedDataStructureChoice.finisher.get();
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // DIRECTORIES - a single level in the file-tree.
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Convenience Method.
     * <BR />Automatically Selects: {@link RTC#VECTOR()}
     * <BR />Invokes: {@link #getDirContentsDirs(RTC, FileNodeFilter)}
     * <BR />Passes: null to parameter {@code 'filter'} (all directories found are returned).
     */
    public Vector<FileNode> getDirContentsDirs()
    { return getDirContentsDirs(RTC.VECTOR(), null); }

    /**
     * Convenience Method.
     * <BR />Accepts: {@link RTC}  (Specifies Output Data-Structure &amp; Contents)
     * <BR />Invokes: {@link #getDirContentsDirs(RTC, FileNodeFilter)}
     * <BR />Passes: null to parameter {@code 'filter'} (all directories found are returned).
     */
    public <T> T getDirContentsDirs(RTC<T> returnedDataStructureChoice)
    { return getDirContentsDirs(returnedDataStructureChoice, null); }

    /**
     * Convenience Method.
     * <BR />Automatically Selects: {@link RTC#VECTOR()}
     * <BR />Accepts: {@link FileNodeFilter}
     * <BR />Invokes: {@link #getDirContentsDirs(RTC, FileNodeFilter)}
     */
    public Vector<FileNode> getDirContentsDirs(FileNodeFilter filter)
    { return getDirContentsDirs(RTC.VECTOR(), filter); }

    /**
     * <EMBED CLASS='external-html' DATA-INCL=directories DATA-EXCL=files
     *      DATA-FILE-ID=FN_DIR_CONTENTS_2>
     * <EMBED CLASS='external-html' DATA-FILE-ID=FN_DIR_CONTENTS>
     *
     * @param <T> <EMBED CLASS='external-html' DATA-FILE-ID=FN_RTC_TYPE_PARAM>
     * @param returnedDataStructureChoice <EMBED CLASS='external-html' DATA-FILE-ID=FN_RTC_PARAM>
     * 
     * @param filter Any Lambda-Expression that will select directories to include in the
     * return Data-Structure.  This parameter may be null, and if it is it will be ignored and all
     * sub-directories will be added to the return-instance. 
     * 
     * @return A list containing sub-directories rooted at {@code 'this'} directory.
     * <EMBED CLASS='external-html' DATA-FILE-ID=FN_RTC_RET>
     *
     * @throws DirExpectedException <EMBED CLASS='external-html' DATA-FILE-ID=FN_DIR_C_DIR_EXP_EX>
     * @see FileNodeFilter
     * @see #isDirectory
     */
    public <T> T getDirContentsDirs(RTC<T> returnedDataStructureChoice, FileNodeFilter filter)
    {
        return getDirContents(
            returnedDataStructureChoice,
            (filter != null) ? DIR_ONLY.and(filter) : DIR_ONLY
        );
    }

    private static final FileNodeFilter DIR_ONLY = (FileNode fn) -> fn.isDirectory;


    // ********************************************************************************************
    // ********************************************************************************************
    // FILES - a single level in the file-tree.
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Convenience Method.
     * <BR />Automatically Selects: {@link RTC#VECTOR()}
     * <BR />Invokes: {@link #getDirContentsFiles(RTC, FileNodeFilter)}
     * <BR />Passes: null to parameter {@code 'filter'} (all files found are returned).
     */
    public Vector<FileNode> getDirContentsFiles()
    { return getDirContentsFiles(RTC.VECTOR(), null); }

    /**
     * Convenience Method.
     * <BR />Accepts: {@link RTC}  (Specifies Output Data-Structure &amp; Contents)
     * <BR />Invokes: {@link #getDirContentsFiles(RTC, FileNodeFilter)}
     * <BR />Passes: null to parameter {@code 'filter'} (all files found are returned).
     */
    public <T> T getDirContentsFiles(RTC<T> returnedDataStructureChoice)
    { return getDirContentsFiles(returnedDataStructureChoice, null); }

    /**
     * Convenience Method.
     * <BR />Automatically Selects: {@link RTC#VECTOR()}
     * <BR />Accepts: {@link FileNodeFilter}
     * <BR />Invokes: {@link #getDirContentsFiles(RTC, FileNodeFilter)}
     */
    public Vector<FileNode> getDirContentsFiles(FileNodeFilter filter)
    { return getDirContentsFiles(RTC.VECTOR(), filter); }

    /**
     * <EMBED CLASS='external-html' DATA-INCL=files DATA-EXCL=directories
     *      DATA-FILE-ID=FN_DIR_CONTENTS_2>
     * <EMBED CLASS='external-html' DATA-FILE-ID=FN_DIR_CONTENTS>
     *
     * @param <T> <EMBED CLASS='external-html' DATA-FILE-ID=FN_RTC_TYPE_PARAM>
     * @param returnedDataStructureChoice <EMBED CLASS='external-html' DATA-FILE-ID=FN_RTC_PARAM>
     * 
     * @param filter Any Lambda-Expression that will select files to include in the return
     * Data-Structure.  This parameter may be null, and if it is it will be ignored and all files
     * will be added to the return-instance. 
     * 
     * @return A {@code Vector} that contains the files inside the current directory.
     * <EMBED CLASS='external-html' DATA-FILE-ID=FN_RTC_RET>
     * 
     * @throws DirExpectedException <EMBED CLASS='external-html' DATA-FILE-ID=FN_DIR_C_DIR_EXP_EX>
     *
     * @see FileNodeFilter
     * @see #isDirectory
     */
    public <T> T getDirContentsFiles(RTC<T> returnedDataStructureChoice, FileNodeFilter filter)
    {
        return getDirContents(
            returnedDataStructureChoice,
            (filter != null) ? FILE_ONLY.and(filter) : FILE_ONLY
        );
    }

    private static final FileNodeFilter FILE_ONLY = (FileNode fn) -> ! fn.isDirectory;

    
    // ********************************************************************************************
    // ********************************************************************************************
    // FLATTEN - Just Directories
    // ********************************************************************************************
    // ********************************************************************************************


    /** 
     * Convenience Method.
     * <BR />Automatically Selects: {@link RTC#VECTOR()}
     * <BR />Invokes: {@link #flatten(RTC, int, FileNodeFilter, boolean, FileNodeFilter, boolean)}
     * <BR />Parameter: {@code 'includeDirectoriesInResult'} set {@code TRUE}
     * <BR />Parameter: {@code 'includeFilesInResult'} set {@code FALSE}
     * <BR />Passes: null to both filter-parameters (all files &amp; directories are returned)
     */
    public Vector<FileNode> flattenJustDirs()
    { return flatten(RTC.VECTOR(), -1, null, false, null, true); }

    /** 
     * Convenience Method.
     * <BR />Accepts: {@link RTC}  (Specifies Output Data-Structure &amp; Contents)
     * <BR />Invokes: {@link #flatten(RTC, int, FileNodeFilter, boolean, FileNodeFilter, boolean)} 
     * <BR />Parameter: {@code 'includeDirectoriesInResult'} set {@code TRUE}
     * <BR />Parameter: {@code 'includeFilesInResult'} set {@code FALSE}
     * <BR />Passes: null to both filter-parameters (all directories are returned by this method).
     */
    public <T> T flattenJustDirs(RTC<T> returnedDataStructureChoice)
    { return flatten(returnedDataStructureChoice, -1, null, false, null, true); }

    /**
     * Convenience Method.
     * <BR />Automatically Selects: {@link RTC#VECTOR()}
     * <BR />Invokes:
     *      {@link #flatten(RTC, int, FileNodeFilter, boolean, FileNodeFilter, boolean)}
     * <BR />Parameter: {@code 'includeDirectoriesInResult'} set {@code TRUE}
     * <BR />Parameter: {@code 'includeFilesInResult'} set {@code FALSE}
     * <BR />Accepts: {@code 'directoryFilter'} parameter.
     */
    public Vector<FileNode> flattenJustDirs(int maxTreeDepth, FileNodeFilter directoryFilter)
    { return flatten(RTC.VECTOR(), maxTreeDepth, null, false, directoryFilter, true); }

    /**
     * Convenience Method.
     * <BR />Accepts: {@link RTC}  (Specifies Output Data-Structure &amp; Contents)
     * <BR />Invokes: {@link #flatten(RTC, int, FileNodeFilter, boolean, FileNodeFilter, boolean)}
     * <BR />Parameter: {@code 'includeDirectoriesInResult'} set {@code TRUE}
     * <BR />Parameter: {@code 'includeFilesInResult'} set {@code FALSE}
     * <BR />Accepts: {@code 'directoryFilter'} parameter
     */
    public <T> T flattenJustDirs
        (RTC<T> returnedDataStructureChoice, int maxTreeDepth, FileNodeFilter directoryFilter)
    {
        return flatten
            (returnedDataStructureChoice, maxTreeDepth, null, false, directoryFilter, true);
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // FLATTEN - Just Files
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Convenience Method.
     * <BR />Automatically Selects: {@link RTC#VECTOR()}
     * <BR />Invokes:
     *      {@link #flatten(RTC, int, FileNodeFilter, boolean, FileNodeFilter, boolean)}
     * <BR />Parameter: {@code includeDirectoriesInResult} set {@code FALSE}
     * <BR />Parameter: {@code includeFilesInResult} set {@code TRUE}
     * <BR />Passes: null to both filter-parameters (all files are returned)
     */
    public Vector<FileNode> flattenJustFiles()
    { return flatten(RTC.VECTOR(), -1, null, true, null, false); }

    /**
     * Convenience Method.
     * <BR />Accepts: {@link RTC} (Specifies Output Data-Structure &amp; Contents)
     * <BR />Invokes: {@link #flatten(RTC, int, FileNodeFilter, boolean, FileNodeFilter, boolean)}
     * <BR />Parameter: {@code includeDirectoriesInResult} set {@code FALSE}
     * <BR />Parameter: {@code includeFilesInResult} set {@code TRUE}
     * <BR />Passes: null to both filter-parameters (all files are returned)
     */
    public <T> T flattenJustFiles(RTC<T> returnedDataStructureChoice)
    { return flatten(returnedDataStructureChoice, -1, null, true, null, false); }

    /**
     * Convenience Method.
     * <BR />Automatically Selects: {@link RTC#VECTOR()}
     * <BR />Invokes: {@link #flatten(RTC, int, FileNodeFilter, boolean, FileNodeFilter, boolean)}
     * <BR />Parameter: {@code includeDirectoriesInResult} set {@code FALSE}
     * <BR />Parameter: {@code includeFilesInResult} set {@code TRUE}
     * <BR />Accepts: {@code 'fileFilter'} parameter
     */
    public Vector<FileNode> flattenJustFiles(int maxTreeDepth, FileNodeFilter fileFilter)
    { return flatten(RTC.VECTOR(), maxTreeDepth, fileFilter, true, null, false); }

    /**
     * Convenience Method.
     * <BR />Accepts: {@link RTC}  (Specifies Output Data-Structure &amp; Contents)
     * <BR />Invokes: {@link #flatten(RTC, int, FileNodeFilter, boolean, FileNodeFilter, boolean)}
     * <BR />Parameter: {@code includeDirectoriesInResult} set {@code FALSE}
     * <BR />Parameter: {@code includeFilesInResult} set {@code TRUE}
     */
    public <T> T flattenJustFiles
        (RTC<T> returnedDataStructureChoice, int maxTreeDepth, FileNodeFilter fileFilter)
    { return flatten(returnedDataStructureChoice, maxTreeDepth, fileFilter, true, null, false); }


    // ********************************************************************************************
    // ********************************************************************************************
    // Core Flatten Routines
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Convenience Method.
     * <BR />Automatically Selects: {@link RTC#VECTOR()}
     * <BR />Invokes: {@link #flatten(RTC, int, FileNodeFilter, boolean, FileNodeFilter, boolean)}
     * <BR />Parameters: {@code includeFilesInResult, includeDirectoriesInResult} both set
     *      {@code TRUE}
     * <BR />Passes: null to both filter-parameers (all files &amp; directories are returned)
     */
    public Vector<FileNode> flatten()
    { return flatten(RTC.VECTOR(), -1, null, true, null, true); }

    /**
     * Convenience Method.
     * <BR />Accepts: {@link RTC}  (Specifies Output Data-Structure &amp; Contents)
     * <BR />Invokes: {@link #flatten(RTC, int, FileNodeFilter, boolean, FileNodeFilter, boolean)}
     * <BR />Parameters: {@code includeFilesInResult, includeDirectoriesInResult} both set
     *      {@code TRUE}
     * <BR />Passes: null to both filter-parameers (all files &amp; directories are returned)
     */
    public <T> T flatten(RTC<T> returnedDataStructureChoice)
    { return flatten(returnedDataStructureChoice, -1, null, true, null, true); }

    /**
     * Convenience Method.
     * <BR />Automatically Selects: {@link RTC#VECTOR()}
     * <BR />Invokes: {@link #flatten(RTC, int, FileNodeFilter, boolean, FileNodeFilter, boolean)}
     * <BR />Accepts: Both filters ({@code directoryFilter, fileFilter}) may be passed.
     * <BR />Accepts: Both {@code 'includeIn'} boolean-flags may be passed.
     */
    public Vector<FileNode> flatten(
            int maxTreeDepth,
            FileNodeFilter fileFilter,      boolean includeFilesInResult, 
            FileNodeFilter directoryFilter, boolean includeDirectoriesInResult
        )
    {
        return flatten(RTC.VECTOR(), maxTreeDepth,
            fileFilter, includeFilesInResult,
            directoryFilter, includeDirectoriesInResult
        );
    }

    /**
     * This flattens the {@code FileNode} tree into a data-structure of your choosing.  Review
     * &amp; read the parameter explanations below, closely, to see what the specifiers do.
     * 
     * <BR /><BR />The concept of "flatten" is identical to the concept of "retrieve" or
     * "search."  All of these methods perform the 'copying' of a set of {@code filter}-matches
     * into a return-container.  If one wishes to scour and search a {@code FileNode} tree to
     * obtain some or all Tree-Nodes for saving into a list (or other data-structure of your
     * choosing), this can be easily done using this method.
     * 
     * <BR /><BR />Write the necessary Lambda-Expressions (filter-predicates) to choose the files
     * and directories that need to be included in the result-container, and then invoke any one
     * of the overloaded {@code flattan(...)} methods offered by this class.
     *
     * <BR /><BR />If you would like to "flatten" the entire tree into a {@code Vector} or some
     * other type of list or data-structure, then leave both of the {@code filter} parameters blank
     * (by passing them null), and also pass {@code '-1'} to parameter {@code 'maxTreeDepth'}.
     * Everything in the directory-tree that is rooted at {@code 'this'} instance of
     * {@code FileNode} is returned into a data-structure of your choosing.
     *
     * @param <T> <EMBED CLASS='external-html' DATA-FILE-ID=FN_RTC_TYPE_PARAM>
     * @param returnedDataStructureChoice <EMBED CLASS='external-html' DATA-FILE-ID=FN_RTC_PARAM>
     * @param maxTreeDepth <EMBED CLASS='external-html' DATA-FILE-ID=FN_MAX_TREE_DEPTH>
     * 
     * @param fileFilter This is a Java 8 "accept" {@code interface java.util.function.Predicate}.
     * Implementing the {@code 'test(FileNode)'} method, allows one to pick &amp; choose which
     * files will be visited as the tree is recursively traversed.  Use a lambda-expression, if
     * needed or for convenience.
     *
     * <BR /><BR /><B>NOTE:</B> This parameter may be null, and if so - <I>all files</I> are
     * will be presumed to pass the {@code filter test}. 
     *
     * <BR /><BR /><B><SPAN STYLE="color: red;">JAVA STREAM'S</SPAN></B> The behavior of this
     * {@code filter}-logic is identical to the Java 8+ Streams-Method
     * {@code 'filter(Predicate<...>)'}.  Specifically, when the {@code filter} returns a
     * {@code TRUE} value for a particular {@code FileNode}, that {@code FileNode} shall be
     * retained, or 'kept', in the returned result-set.  When the {@code filter} returns
     * {@code FALSE} for a {@code FileNode}, that file or directory will be removed from the
     * result-set.
     * 
     * <BR /><BR />One way to think about which files are included in the results of a 
     * {@code 'flatten'} operation is by this list below:
     *
     * <BR /><BR /><UL CLASS=JDUL>
     * <LI> Whether/if the {@code boolean includeFilesInResult} boolean-flag has been
     *      set to {@code TRUE}.
     *      </LI>
     * <LI> Whether the {@code FileNode} would pass the {@code fileFilter.test} predicate
     *      (if one has been provided, otherwise ignore this metric).
     *      </LI>
     * <LI> Whether the containing directory's {@code FileNode} would pass the
     *      {@code directoryFilter.test} predicate (if one has been provided, otherwise ignore this
     *      metric).
     *      </LI>
     * <LI> Whether or not <I>all parent-containing directories</I> of the {@code FileNode} would
     *      pass the {@code directoryFilter.test} predicate (if one were provided).
     *      </LI>
     * </UL>
     *
     * @param includeFilesInResult If this parameter is {@code TRUE}, then files will be included
     * in the resulting {@code Vector}.
     *
     * <BR /><BR /><SPAN STYLE="color: red;"><B>NOTE:</B></SPAN> If this parameter is
     * {@code FALSE}, this value will "over-ride" any results that may be produced from the public
     * {@code fileFilter.test(this)} method (if such a filter had been provided).
     *
     * @param directoryFilter This is also a Java 8 "Predicate Filter"  {@code interface
     * java.util.function.Predicate}.  Implementing the {@code 'test(FileNode)'} method, allows
     * one to pick &amp; choose which directories will be visited as the tree is recursively
     * traversed.  Use a lambda-expression, if needed or for convenience.
     *
     * <BR /><BR /><B>NOTE:</B> This parameter may be null, and if so - <I>all directories</I>
     * will be traversed.
     *
     * <BR /><BR /><B><SPAN STYLE="color: red;">JAVA STREAM'S</SPAN></B> The behavior of this
     * {@code filter}-logic is identical to the Java 8+ Streams-Method
     * {@code 'filter(Predicate<...>)'.}  Specifically, when the {@code filter} returns a
     * {@code TRUE} value for a particular {@code FileNode}, that {@code FileNode} shall be
     * retained, or 'kept', in the returned result-set.  When the {@code filter} returns
     * {@code FALSE} for a {@code FileNode}, that file or directory will be removed from the
     * result-set.
     *
     * <BR /><BR /><SPAN STYLE="color: red;"><B>IMPORTANT:</B></SPAN> There is no way to
     * differentiate between which directories are traversed and which directories are included in
     * the result set - if a directory is not traversed or examined, then that directory, <I>and
     * any/all files and sub-directories contained by that directory</I> will all be eliminted
     * from the returned-results.
     * 
     * <BR /><BR />One way to think about which directories are included in the results of a 
     * {@code 'flatten'} operation is by this list below:
     *
     * <BR /><BR /><UL CLASS=JDUL>
     * <LI> Whether/if the {@code boolean includeDirectoriesInResult} boolean-flag has been
     *      set to {@code TRUE}.
     *      </LI>
     * <LI> Whether that {@code FileNode} would pass the {@code directoryFilter.test} predicate 
     *      (if one has been provided, otherwise ignore this metric).
     *      </LI>
     * <LI> Whether or not <I>all parent directories</I> of the {@code FileNode} would also pass
     *      the {@code directoryFilter.test} predicate (if one were provided).
     *      </LI>
     * </UL>
     *
     * @param includeDirectoriesInResult If this parameter is {@code TRUE}, then directories will
     * be included in the resulting {@code Vector}.
     *
     * <BR /><BR /><SPAN STYLE="color: red;"><B>NOTE:</B></SPAN> If this parameter is
     * {@code FALSE}, this value will "over-ride" any results that may be produced from the public
     * {@code directoryFilter.test(this)} method.
     *
     * @return A flattened version of this tree.
     *
     * <EMBED CLASS='external-html' DATA-FILE-ID=FN_RTC_RET>
     *
     * @throws DirExpectedException If {@code 'this'} instance of {@code FileNode} is not a
     * directory, but a file, then this exception is thrown.  (Files <I>may not</I> have 
     * child-nodes, only directories).
     *
     * @throws IllegalArgumentException If the value of {@code 'maxTreeDepth'} is set to
     * {@code zero}, then this exception shall be thrown because the method-invocation would not be
     * making an actual request to do anything.
     *
     * <BR /><BR />This exception shall <I><B>*also* be throw if</I></B> both of the boolean
     * parameters are set to {@code FALSE}, for the same reason being that the method-invocation
     * would not be making a request.
     */
    public <T> T flatten(
            RTC<T>  returnedDataStructureChoice,
            int     maxTreeDepth,
            FileNodeFilter fileFilter,      boolean includeFilesInResult, 
            FileNodeFilter directoryFilter, boolean includeDirectoriesInResult)
    {
        DirExpectedException.check(this);

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

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

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

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

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

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

    private static final FileNodeFilter ALWAYS_TRUE = (FileNode f) -> true;

    private static void flattenINTERNAL(
            FileNode cur,                   Consumer<FileNode> inserter,
            FileNodeFilter fileFilter,      boolean includeFilesInResult, 
            FileNodeFilter directoryFilter, boolean includeDirectoriesInResult,
            int curTreeDepth,               int maxTreeDepth
        )
    {
        if ((maxTreeDepth >= 0) && (curTreeDepth > maxTreeDepth)) return;
 
        if (VERBOSE) System.out.println(cur.name);

        directoryFilter = (directoryFilter == null) ? ALWAYS_TRUE : directoryFilter;
        fileFilter      = (fileFilter == null)      ? ALWAYS_TRUE : fileFilter;

        for (FileNode fn : cur.children)

            if (fn.isDirectory)
                { if (includeDirectoriesInResult && directoryFilter.test(fn)) inserter.accept(fn);}

            else
                { if (includeFilesInResult && fileFilter.test(fn)) inserter.accept(fn); }


        for (FileNode fn : cur.children) if (fn.isDirectory && directoryFilter.test(fn))

            flattenINTERNAL(
                fn,                 inserter,
                fileFilter,         includeFilesInResult,
                directoryFilter,    includeDirectoriesInResult,
                curTreeDepth+1,     maxTreeDepth
            );
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Prune Tree
    // ********************************************************************************************
    // ********************************************************************************************


    /** 
     * Convenience Method.
     * <BR />Invokes: {@link #pruneTree(FileNodeFilter, boolean)}
     * <BR />Returns: {@code 'this'} rather than {@code 'int'}
     */
    public FileNode prune(FileNodeFilter fileFilter, boolean nullThePointers)
    { this.pruneTree(fileFilter, nullThePointers); return this; }

    /**
     * This removes instances of {@code FileNode} that meet these conditions:
     *
     * <BR /><BR /><OL CLASS=JDOL>
     * 
     * <LI> Are file instances, not directories. Specifically: {@code public final boolean
     *      isDirectory == false;}<BR />
     *      </LI>
     * 
     * <LI> Do not pass the {@code 'fileFilter.test(...)'} method.  If the test method returns
     *      {@code FALSE}, the file shall be removed from the containing directory's 
     *      {@link #children} {@code Vector<FileNode>} File-List.
     *      </LI>
     * 
     * </OL>
     *
     * <BR /><BR /><B CLASS=JDDescLabel>Recursive Method:</B>
     * 
     * <BR />This method shall skip through, 'traverse', the entire {@code FileNode} tree and prune
     * all 'file-leaves' that do not meet the criteria specified by the {@code 'fileFilter'}
     * parameter.
     *
     * @param fileFilter This is the test used to filter out files from the directory-tree that
     * begins at {@code 'this'} instance.  Returning {@code FALSE} shall eliminate the file from
     * its containing parent, and when this filter returns {@code TRUE} that file shall remain.
     *
     * @param nullThePointers The primary use of this boolean is to remind users that this
     * data-structure {@code 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, <I><B>and because</I></B> the data-structure itself (READ:
     * {@code 'this'} tree) does not have much use for being modified itself...  The fact that
     * {@code 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.
     *
     * <BR /><BR /><B>POINT:</B> When this parameter is set to {@code TRUE}, all parent pointers
     * shall be nulled, and this can make garbage-collection easier.
     *
     * @return The number of files that were removed.
     *
     * @throws DirExpectedException If {@code 'this'} instance of {@code FileNode} does not
     * represent a 'directory' on the File-System, then this exception shall throw.
     *
     * @see #prune(FileNodeFilter, boolean)
     * @see #isDirectory
     * @see #parent
     */
    public int pruneTree(FileNodeFilter fileFilter, boolean nullThePointers)
    {
        DirExpectedException.check(this);

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

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

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

            if (! fn.isDirectory)

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

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

                    if (nullThePointers) fn.parent = null;

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

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

                    iter.remove();

                    removeCount++;
                    continue;
                }

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

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

        return removeCount;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Simple stuff
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Returns the parent of {@code 'this' FileNode}
     *
     * @return {@code this.parent}
     *
     * <BR /><BR /><B>NOTE</B> If this is a "root node" or "root directory" then null will be
     * returned here.
     *
     * @see #parent
     */
    public FileNode getParentDir() { return parent; }

    /**
     * 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 {@code destinationDir} is
     * not actually a directory, then an exception is thrown.  If this is already a child/member
     * of the {@code destinationDir}, then an exception is also thrown.
     *
     * <BR /><BR /><B CLASS=JDDescLabel>File-System Safety:</B>
     * 
     * <BR />This method <I>does not modify</I> the underlying UNIX or MS-DOS File-System - just
     * the {@code FileNode} Tree  representation in Java Memory!   (No UNIX, Apple, MS-DOS etc. 
     * files are actually moved by this method)
     *
     * @param destinationDir the destination directory
     *
     * @throws java.util.InputMismatchException
     * @throws DirExpectedException If {@code 'destinationDir'} is not a directory, but a file,
     * then this exception is thrown.  (Files <I>may not</I> contain child-nodes, only directories)
     *
     * @see #parent
     * @see #name
     * @see #children
     */
    public void move(FileNode destinationDir)
    {
        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);
    }

    /**
     * This deletes a file from the {@code FileNode} tree.  It's only operation is to remove
     * {@code 'this'} from the parent-node's {@code Vector<FileNode> children} node-list!  For
     * Java garbage collection purposes, it also empties (calls
     * {@code children.removeAllElements()}) on the children {@code Vector} - if there is one
     * (a.k.a) if {@code 'this' FileNode} represents a directory, not a file!
     *
     * <BR /><BR /><B CLASS=JDDescLabel>File-System Safety:</B>
     * 
     * <BR />This method <I>does not modify</I> the underlying UNIX or MS-DOS File-System - just
     * the {@code FileNode}-Tree representation in Java Memory!  (No UNIX, Apple, MS-DOS, etc.
     * files are actually deleted by this method)
     *
     * @see #parent
     * @see #children
     * @see #isDirectory
     */
    public void del()
    {
        parent.children.removeElement(this);

        if (isDirectory) children.removeAllElements();

        parent = null;
    }

    /**
     * This visits the {@code '.name'} field for {@code 'this' FileNode}, as well as all parent
     * instances of {@code 'this' FileNode}, and concatenates those {@code String's}.
     * 
     * @return the full, available path name for {@code 'this' FileNode} as a {@code String}
     * @see #parent
     * @see #isDirectory
     * @see #name
     * @see #getFullPathName()
     */
    public String getFullPathName()
    {
        if (parent == null)

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

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

    /**
     * Returns the as much of the "Full Path Name" of the file referenced by {@code 'this'}
     * filename as is possible for this particular {@code FileNode}.
     * 
     * <BR /><BR />If this file or directory does not have a parent, then the empty (zero-length)
     * {@code String} will be returned.  Usually, unless certain tree modification operations have
     * been performed, only a <I><B>root-node</B></I> {@code FileNode} will have a 'null' parent.
     *
     * @return the full, available path name to {@code 'this' FileNode} - leaving out the actual
     * name of this file.
     *
     * <BR /><BR /><B>SPECIFICALLY:</B>
     * 
     * <BR /><BR /><UL CLASS=JDUL>
     * <LI>for a file such as {@code 'directory-1/subdirectory-2/filename.txt'}</LI>
     * <LI>{@code 'directory-1/subdirectory-2/'} would be returned</LI>
     * </UL>
     *
     * @see #parent
     * @see #getFullPathName()
     */
    public String getParentPathName()
    { if (parent == null) return ""; else return parent.getFullPathName(); }

    /**
     * Gets the {@code 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 {@code 'r/w/x'} permissions.
     * This can be useful.
     *
     * @return Gets the {@code java.io.File} instance of {@code 'this' FileNode}
     * @see #getFullPathName()
     */
    public File getJavaIOFile() { return new File(getFullPathName()); }

    /**
     * This presumes that {@code 'this'} instance of {@code 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 {@code 'this'} file represents a <B>text-file</B> that may be loaded into a
     * {@code String}.
     * 
     * <BR /><BR />This method will load the contents of {@code 'this'} file into a 
     * {@code java.lang.String} and then pass that {@code String} (along with {@code 'this'
     * FileNode} to the method {@code 'accept(FileNode, String'} provided by the
     * {@code BiConsumer<FileNode, String>} input-parameter {@code 'c'}.
     *
     * @param c This is the java {@code FunctionalInterface 'BiConsumer'}.  As a
     * {@code functional-interface}, it has a method named {@code 'accept'} and this method
     * {@code 'accept'} receives two parameters itself: 
     *
     * <BR /><BR /><OL CLASS=JDOL>
     * <LI>The first Parameter shall be {@code 'this'} instance of {@code 'FileNode'}</LI>
     * 
     * <LI> The second Parameter shall be the file-contents on the File-System of
     *      {@code 'this' FileNode} - passed as a {@code java.lang.String}.
     *      </LI>
     * </OL>
     * 
     * @param ioeh This an is instance of {@code FunctionalInterface 'IOExceptionHandler'}.  It
     * receives an instance of an {@code IOException}, and the programmer may insert any type of
     * code he wants to see happen when an {@code IOException} is thrown.  The 'added-value' of
     * including this handler is that when batches of {@code accept's} are performed one a 
     * {@code FileNode}-tree, one file causing an exception throw does not have to halt the entire
     * batch-process.
     *
     * <BR /><BR /><B>NOTE:</B> 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 {@code 'destinationDir'} is not a file, but a directory,
     * then this exception is thrown.
     *
     * @see FileRW#loadFileToString(String)
     * @see #getFullPathName()
     * @see IOExceptionHandler#accept(FileNode, IOException)
     */
    public void accept(BiConsumer<FileNode, String> c, IOExceptionHandler ioeh)
    {
        // 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); }
    }

    /**
     * This presumes that {@code 'this'} instance of {@code 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 {@code 'this'} file represents a <B>text-file</B> that may be loaded into a
     * {@code String}.
     * 
     * <BR /><BR />This method will load the contents of {@code 'this'} file into a 
     * {@code java.lang.String} and then pass that {@code String} (along with {@code 'this'
     * FileNode} to the method {@code 'ask(FileNode, String'} provided by the
     * {@code BiPredicate<FileNode, String>} input-parameter {@code 'p'}.
     *
     * <BR /><BR />This is the type of method that could easily be used in conjunction with a
     * {@code java.util.stream.Stream} or a {@code java.util.Vector}.
     *
     * <BR /><BR /><UL CLASS=JDUL>
     * <LI> {@code Stream<FileNode>.filter
     *      (fileNode -> fileNode.ask(myFilterPred, myIOEHandler));}
     *      </LI>
     * 
     * <LI> {@code Vector<FileNode>.removeIf
     *      (fileNode -> fileNode.ask(myFilterPred, myIOEHandler));}
     *      </LI>
     * </UL>
     *
     * @param p This is the java {@code FunctionalInterface 'BiPredicate'}.  As a
     * {@code functional-interface}, it has a method named {@code 'test'} and this method
     * {@code 'test'} receives two parameters itself: 
     *
     * <BR /><BR /><OL CLASS=JDOL>
     * <LI>The first parameter shall be {@code 'this'} instance of {@code 'FileNode'}</LI>
     * <LI>The second parameter shall be the file-contents on the File-System of
     *     {@code 'this' FileNode} - passed as a {@code java.lang.String}.</LI>
     * </OL>
     *
     * <BR /><BR /><B>IMPORTANT:</B> The {@code functional-interface} that is passed to parameter
     * {@code 'p'} should provide a return {@code boolean}-value that is to act as a pass/fail
     * filter criteria.  It is important to note that the Java {@code Vector} method
     * {@code Vector.removeIf(Predicate)} and the Java method {@code Stream.filter(Predicate)} 
     * will produce <B><I>exactly opposite outputs</I></B> based on the same filter logic.
     * 
     * <BR /><BR />To explain further, when {@code Vector.removeIf(Predicate)} is used, the
     * predicate should return {@code FALSE} to indicate that the {@code FileNode} needs to be
     * eliminated not retained.  When {@code Stream.filter(Predicate)} is used, {@code TRUE} should
     * indicate that the {@code FileNode} should be retained not eliminated.
     *
     * @param ioeh This is an instance of functional-interface class, {@code IOExceptionHandler}.
     * It receives an instance of an {@code IOException}, and the programmer may insert any type of
     * code he wants to see happen when an {@code IOException} is thrown.  The 'added-value' of
     * including this handler is that when batches of {@code ask's} are performed on a 
     * {@code FileNode}-tree, one file causing an exception throw does not have to halt the entire
     * batch-process.
     *
     * <BR /><BR /><B>NOTE:</B> 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.
     *
     * @return This method returns {@code TRUE} if there were no I/O faults when either reading or
     * writing the file.
     *
     * @throws FileExpectedException If {@code 'destinationDir'} is not a file, but a directory,
     * then this exception is thrown.
     *
     * @see #getFullPathName()
     * @see FileRW#loadFileToString(String)
     * @see IOExceptionHandler#accept(FileNode, IOException)
     */
    public boolean ask(BiPredicate<FileNode, String> p, IOExceptionHandler ioeh)
    {
        // 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; }
    }

    /**
     * There are not any "Tree Structures" present in the HTML Search, Update, and Scrape Packages.
     * In the Java Packages, the {@code class 'FileNode'} is the lone source of "Tree Structures."
     * The Java Garbage Collector sometimes seems to work in mysterious ways. 
     *
     * <BR /><BR />This method will 'null-ify' all references (pointers) in a
     * {@code 'FileNode'}-Tree.  The {@code FileNode}-Tree can be a great asset or tool during the
     * development process when looking through file-contents and trying to modify them - <I>or
     * just find files with certain characteristics.</I>
     *
     * @see #getDirContents()
     * @see #getDirContentsDirs()
     * @see #parent
     * @see #children
     */
    public void NULL_THE_TREE()
    {
        Iterator<FileNode> iter = getDirContents(RTC.ITERATOR());

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

        iter = getDirContentsDirs(RTC.ITERATOR());

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

        children.clear();
    }
}