Package Torello.Java
Class FileNode
- java.lang.Object
-
- Torello.Java.FileNode
-
- All Implemented Interfaces:
java.io.Serializable
,java.lang.CharSequence
,java.lang.Cloneable
,java.lang.Comparable<FileNode>
public final class FileNode extends java.lang.Object implements java.lang.CharSequence, java.lang.Comparable<FileNode>, java.io.Serializable, java.lang.Cloneable
One of the flagship classes of Java HTML,FileNode
loads a directory or directory-tree from a file-system into memory, and provides a thorough API for listing and analyzing its contents.
This loads the UNIX or MS-DOS file-system tree into Java Memory. It can be a very useful utility class. Both directory-filters and file-filters may be used to eliminate or include certain files. It uses a simple (obvious) recursive method to load all files and sub-directories into a tree which can be traversed or flattened.No Method within This Class Performs File-System Writes!
Writes may only be performed after retrieving a file-name list, and invoking some other mechanism, for instance:FileTransfer
,FileRW
orjava.io.File
This class builds an in memory node-tree that is loaded from disk, and mirrors the directory tree from which it was loaded. The contents of these'nodes'
are nothing more thanjava.lang.String's
, and a few other pieces of data including a'fileSize'
field, and a'lastModified'
field. (At present, there is no attributes field). As nothing more than aString
-Tree, experiments with the features of the class are harmless - since only Java Memory will be modified!
It is possible to use this class to modify files and directories on disk, but it requires additional classes / code to do so. Some suggestions include:- Use
class FileTransfer
, to move copy or delete files. - Retrieve File-Names from a
FileNode
-Tree, and use Java's standardjava.io.*
package to modify file(s) contents, using your own code that your trust. - There are numerous methods, provided here, for retrieving lists of file-names, and much can be done with a list of files, once retrieved, using any utside library.
LOAD TREE:
There are numerous methods provided for loading the contents of the file-system into aFileNode
tree. These methods offer different ways of limiting which files will be inserted and read when reading from disk. The JavaFunctionalInterface
structure is used viainterface FileNodeFilter
. These filters can be built with standard lambda-expressions, or by implementing the functional-interface.
FLATTEN TREE:
It is important to note that the primary purpose of theVector<FileNode> flatten(...)
methods are such that lists of files can be used, printed, looked-at, etc... by the programmer. The individual instances ofFileNode
are saved to a single list byflatten(...)
methods, which makes working with the actual operating-system file, itself, quick and easy.
PRINT TREE:
There are three methods for printing various branches of the tree provided by this class.
These concepts are illustrated in the example code, below:
Example:
// Printing Example // Prints all ".java" source-files in your directory hierarchy FileNode.createRoot("MyJavaPackages/") .loadTree(-1, (f, name) -> name.endsWith(".java"), null) .printTree(); // Flatten Example // NOTE: This ought to produce the same output as the previous example, // except showing ".class" files instead of ".java" files FileNode.createRoot("MyJavaPackages/") .loadTree() .flatten(-1, (FileNode fn) -> fn.name.endsWith(".class"), true, null, true) .forEach((FileNode fn) -> System.out.println(fn.getFullPathName())); // Num Children Example FileNode fn = FileNode.createRoot("etc/").loadTree(); System.out.println("There are precisely " + fn.numDirChildren() + " sub-directories in etc/"); System.out.println("There are precisely " + fn.numFileChildren() + " files in etc/"); // Print the subdirectories of a particular nodes FileNode fn = FileNode.createRoot("users/"); fn.loadTree(); System.out.println("The directory 'users/' has the following sub-directories:"); Iterator<FileNode> iter = fn.getDirContentsDirs(FileNode.RetTypeChoice.ITERATOR); while (iter.hasNext()) System.out.println(iter.next().name); System.out.println("And the following files:"); iter = fn.getDirContentsFiles(); while (iter.hasNext()) System.out.println(iter.next().name);
- See Also:
- Serialized Form
Hi-Lited Source-Code:- View Here: Torello/Java/FileNode.java
- Open New Browser-Tab: Torello/Java/FileNode.java
-
-
Nested Class Summary
Nested Classes Modifier and Type Class static class
FileNode.RetTypeChoice
-
Field Summary
Serializable ID Modifier and Type Field static long
serialVersionUID
Primary Fields Modifier and Type Field long
fileSize
boolean
isDirectory
long
lastModified
String
name
Static Print Flag Modifier and Type Field static boolean
VERBOSE
Static SecurityException Catch Flag Modifier and Type Field static boolean
SKIP_DIR_ON_SECURITY_EXCEPTION
2nd java.util.Comparator Modifier and Type Field static Comparator<FileNode>
comp2
Protected Reference-Pointer Fields Modifier and Type Field protected Vector<FileNode>
children
protected FileNode
parent
-
Constructor Summary
Constructors Modifier Description protected
This constructor builds a "root"FileNode
instance.protected
This constructor builds aFileNode
object - which must be a directoryFileNode
instance and may not be a fileFileNode
instance.protected
This constructor builds aFileNode
object which must be a fileFileNode
instance - and may not be a directoryFileNode
instance.
-
Method Summary
Basic Methods Modifier and Type Method FileNode
deepClone()
String
ext(boolean includeTheDot)
String
getFullPathName()
File
getJavaIOFile()
FileNode
getParentDir()
String
getParentPathName()
void
move(FileNode destinationDir)
String
nameNoExt()
void
NULL_THE_TREE()
Initialize: Create a Tree, Load the Tree Modifier and Type Method static FileNode
createRoot(String name)
FileNode
loadTree()
FileNode
loadTree(boolean includeFiles, boolean includeDirectories)
FileNode
loadTree(int maxTreeDepth, FilenameFilter fileFilter, FileFilter directoryFilter)
FileNode
loadTreeJustDirs(int maxTreeDepth, FileFilter directoryFilter)
List: Print all Files to Terminal or an Appendable
Modifier and Type Method void
printTree()
void
printTree(Appendable a, boolean showSizes, FileNodeFilter fileTest, FileNodeFilter directoryTest)
void
printTreeNOIOE(boolean showSizes, FileNodeFilter fileTest, FileNodeFilter directoryTest)
Find: Search a Single Directory for One File or Sub-Directory Modifier and Type Method FileNode
dir(String dirName)
FileNode
dir(String dirName, boolean ignoreCase)
FileNode
file(String fileName)
FileNode
file(String fileName, boolean ignoreCase)
Flatten: Copy Directory-Tree Contents to a Vector
Modifier and Type Method Vector<FileNode>
flatten()
Vector<FileNode>
flatten(int maxTreeDepth, FileNodeFilter fileFilter, boolean includeFilesInResult, FileNodeFilter directoryFilter, boolean includeDirectoriesInResult)
Vector<FileNode>
flattenJustDirs()
Vector<FileNode>
flattenJustDirs(int maxTreeDepth, FileNodeFilter directoryFilter)
Vector<FileNode>
flattenJustFiles()
Vector<FileNode>
flattenJustFiles(int maxTreeDepth, FileNodeFilter fileFilter)
Flatten: Copy Directory-Tree Contents to any container (using RetTypeChoice
)Modifier and Type Method <T> T
flatten(VarList<T,FileNode> listChoice)
<T> T
flatten(VarList<T,FileNode> listChoice, int maxTreeDepth, FileNodeFilter fileFilter, boolean includeFilesInResult, FileNodeFilter directoryFilter, boolean includeDirectoriesInResult)
<T> T
flattenJustDirs(VarList<T,FileNode> listChoice)
<T> T
flattenJustDirs(VarList<T,FileNode> listChoice, int maxTreeDepth, FileNodeFilter directoryFilter)
<T> T
flattenJustFiles(VarList<T,FileNode> listChoice)
<T> T
flattenJustFiles(VarList<T,FileNode> listChoice, int maxTreeDepth, FileNodeFilter fileFilter)
Retrieve: Copy a Single-Directory's Contents to a Vector
Modifier and Type Method Vector<FileNode>
getDirContents()
Vector<FileNode>
getDirContents(FileNodeFilter filter)
Vector<FileNode>
getDirContentsDirs()
Vector<FileNode>
getDirContentsDirs(FileNodeFilter filter)
Vector<FileNode>
getDirContentsFiles()
Vector<FileNode>
getDirContentsFiles(FileNodeFilter filter)
long
getDirContentsSize()
long
getDirContentsSize(FileNodeFilter fileTest)
Retrieve: Copy a Single-Directory's Contents to any container (using RetTypeChoice
)Modifier and Type Method <T> T
getDirContents(VarList<T,FileNode> listChoice)
<T> T
getDirContents(VarList<T,FileNode> listChoice, FileNodeFilter filter)
<T> T
getDirContentsDirs(VarList<T,FileNode> listChoice)
<T> T
getDirContentsDirs(VarList<T,FileNode> listChoice, FileNodeFilter filter)
<T> T
getDirContentsFiles(VarList<T,FileNode> listChoice)
<T> T
getDirContentsFiles(VarList<T,FileNode> listChoice, FileNodeFilter filter)
Count: The Number of FileNode's in the Entire Tree Modifier and Type Method int
count()
int
count(FileNodeFilter fileFilter, FileNodeFilter directoryFilter)
int
countJustDirs()
int
countJustDirs(FileNodeFilter directoryFilter)
int
countJustFiles()
int
countJustFiles(FileNodeFilter fileFilter, FileNodeFilter directoryFilter)
Count: The Number of FileNode's in a Single-Directory Modifier and Type Method int
numChildren()
int
numDirChildren()
int
numFileChildren()
Poll: Extract & Return a FileNode from the Tree Modifier and Type Method FileNode
pollDir(String dirName)
FileNode
pollDir(String dirName, boolean ignoreCase)
FileNode
pollFile(String fileName)
FileNode
pollFile(String fileName, boolean ignoreCase)
Remove: FileNode(s) from the Tree Modifier and Type Method void
del()
FileNode
prune(FileNodeFilter fileFilter, boolean nullThePointers)
int
pruneTree(FileNodeFilter fileFilter, boolean nullThePointers)
Lambda-Target: Methods Accepting a Functional-Interface Modifier and Type Method void
accept(BiConsumer<FileNode,String> c, IOExceptionHandler ioeh)
boolean
apply(BiFunction<FileNode,String,String> f, IOExceptionHandler ioeh)
boolean
ask(BiPredicate<FileNode,String> p, IOExceptionHandler ioeh)
void
forEach(Consumer<FileNode> c)
On-Disk File-Size Modifier and Type Method long
getDirTotalContentsSize()
long
getDirTotalContentsSize(FileNodeFilter fileTest, FileNodeFilter directoryTest)
Methods: interface java.lang.CharSequence Modifier and Type Method char
charAt(int index)
int
length()
CharSequence
subSequence(int start, int end)
String
toString()
Methods: interface java.lang.Comparable<FileNode> Modifier and Type Method int
compareTo(FileNode fn)
Methods: interface java.lang.Cloneable Modifier and Type Method FileNode
clone()
Methods: class java.lang.Object Modifier and Type Method boolean
equals(Object o)
int
hashCode()
-
-
-
Field Detail
-
serialVersionUID
public static final long serialVersionUID
This fulfils the SerialVersion UID requirement for all classes that implement Java'sinterface java.io.Serializable
. Using theSerializable
Implementation offered by java is very easy, and can make saving program state when debugging a lot easier. It can also be used in place of more complicated systems like "hibernate" to store data as well.- See Also:
- Constant Field Values
- Code:
- Exact Field Declaration Expression:
public static final long serialVersionUID = 1;
-
VERBOSE
public static boolean VERBOSE
When this variable is TRUE debug and status information will be sent toStandard Output
- Code:
- Exact Field Declaration Expression:
public static boolean VERBOSE = false;
-
name
public final java.lang.String name
The name of the file or directory is saved/stored here- Code:
- Exact Field Declaration Expression:
public final String name;
-
isDirectory
public final boolean isDirectory
If'this'
class-instance represents a directory in the BASH/UNIX or MS-DOS file system, this variable will be TRUE.- Code:
- Exact Field Declaration Expression:
public final boolean isDirectory;
-
parent
protected FileNode parent
The parent/container'FileNode'
directory is saved here - like a pointer "tree".- Code:
- Exact Field Declaration Expression:
protected FileNode parent;
-
fileSize
public final long fileSize
When a tree is loaded into memory, the size of each file is saved in this variable. It can be retrieved (and even changed).- Code:
- Exact Field Declaration Expression:
public final long fileSize;
-
lastModified
public final long lastModified
When a tree is loaded into memory, the file-date of the file is saved in this variable. It can be retrieved. If theSecurityManager.checkRead(fileName)
denies read access to the file, this field will equal zero.
NOTE: This field is a Java simple-type'long'
which represents the time the file was last modified, measured in milliseconds since the epoch(00:00:00 GMT, January 1, 1970)
- Code:
- Exact Field Declaration Expression:
public final long lastModified;
-
children
protected final java.util.Vector<FileNode> children
This variable remains null for all instances of this class which represent 'files' on the underlying operating-system, rather than 'directories.' On the other hand, if'this'
instance ofFileNode
represents an MS-DOS, Unix, or Apple OS directory, then fieldVector<FileNode> children
will be instantiated and hold all files and sub-directories which are found.- Code:
- Exact Field Declaration Expression:
protected final Vector<FileNode> children;
-
comp2
public static final java.util.Comparator<FileNode> comp2
This is an "alternative Comparitor" that can be used for sorting instances of this class. It should work with theCollections.sort(List, Comparator)
method in the standard JDK packagejava.util.*;
NOTE: This version utilizes the standard JDKString.compareToIgnoreCase(String)
method.- See Also:
getFullPathName()
- Code:
- Exact Field Declaration Expression:
public static final Comparator<FileNode> comp2 = (FileNode fn1, FileNode fn2) -> fn1.getFullPathName().compareToIgnoreCase(fn2.getFullPathName());
-
SKIP_DIR_ON_SECURITY_EXCEPTION
public static boolean SKIP_DIR_ON_SECURITY_EXCEPTION
Directories on a UNIX platform that were inaccessible didn't seem to throw aSecurityException
, instead, a null-array was returned. However, in the case that Java'sjava.lang.SecurityManager
is catching attempts to access restricted dirtectories and throwing exceptions (which is likely a rare case) - thisboolean
flag can inform the internal directory-scanner logic to catch theseSecurityException's
.
If "catching and skipping" exceptions has been choosen, then any directory that is scanned and would throw an exception, instead is left empty by this class' tree-loading logic.
IMPORTANT: This flag is a nonThread
-Safe flag, because it is a'static'
flag that applies to all instances of classFileNode
- Code:
- Exact Field Declaration Expression:
public static boolean SKIP_DIR_ON_SECURITY_EXCEPTION = false;
-
-
Constructor Detail
-
FileNode
protected FileNode(java.lang.String name, FileNode parent, long lastModified)
This constructor builds aFileNode
object - which must be a directoryFileNode
instance and may not be a fileFileNode
instance.
SPECIFICALLY: The node that is instantiated will have afinal int fileSize
field value of'0'
and afinal boolean isDirectory
value of TRUE.
NOTE: File-name validity checks are not performed here, no validity checks are performed because this constructor has protected access, and the calls to it are generated here in this class. Furthermore, the values sent to these parameters are all retrieved from getter-calls toclass java.io.File
, and likely are not invalid.- Parameters:
name
- The name of'this' FileNode
parent
- This is the parent or "container-directory" of'this' FileNode
. If aFileNode
that is not a directory itself is passed as the parent, then an exception will be thrown.lastModified
- This must be along
value indicating when the file was last modified - according to the operating-system. This value may be'0'
, and if so, it indicates that this information was either not available, or a read of the value was not allowed by the operating-system security manager.
Exact Method Body:
this.name = name; this.parent = parent; this.isDirectory = true; this.fileSize = 0; this.lastModified = lastModified; this.children = new Vector<>();
-
FileNode
protected FileNode(java.lang.String name, FileNode parent, long fileSize, long lastModified)
This constructor builds aFileNode
object which must be a fileFileNode
instance - and may not be a directoryFileNode
instance.
SPECIFICALLY: The node that is instantiated will have afinal boolean isDirectory
value of FALSE.
NOTE: File-name validity checks are not performed here, no validity checks are performed because this constructor has protected access, and the calls to it are generated here in this class. Furthermore, the values sent to these parameters are all' retrieved from getter-calls toclass java.io.File
, and likely are not invalid.- Parameters:
name
- The name of'this' FileNode
parent
- This is the parent or "container-directory" of'this' FileNode
. If aFileNode
that is not a directory itself is passed as the parent, then an exception will be thrown.fileSize
- The size of this file - in bytes.lastModified
- This must be a long value indicating when the file was last modified - according to the operating-system. This value may be'0'
, and if so, it indicates that this information was either not available, or a read of the value was not allowed by the operating-system security manager.
Exact Method Body:
this.name = name; this.parent = parent; this.isDirectory = false; this.fileSize = fileSize; this.lastModified = lastModified; this.children = null;
-
FileNode
protected FileNode(java.lang.String name)
This constructor builds a "root"FileNode
instance.- Parameters:
name
- The name of'this' FileNode
-
-
Method Detail
-
createRoot
public static FileNode createRoot(java.lang.String name)
This is the "Factory Method" for this class. TheString name
parameter is intended to be the root directory-name from which the tree is intended to be built.
NOTE: Once a "root node" for the tree has been built, calling theloadTree(...)
methods is simple, and the only way to populate the tree of UNIX or MS-DOS file-names.
Example:
FileNode fn = FileNode.createRoot("etc/MyDataFiles/user123/").loadTree();
- Returns:
- An instance of this class from which a
FileNode
tree may be instantiated. - Code:
- Exact Method Body:
return new FileNode(name);
-
pollDir
public FileNode pollDir(java.lang.String dirName)
- Code:
- Exact Method Body:
return pollDir(dirName, false);
-
pollDir
public FileNode pollDir(java.lang.String dirName, boolean ignoreCase)
Retrieves the sub-directoryFileNode
instance named by parameter'dirName'
if there is aFileNode
that is a direct descendant of'this'
instance ofFileNode
.
Differing: Different than methoddir(String, boolean)
, this method will "extract" the directory from the in-memory file-tree. If a directory is found matching the requested name and case requirements, when it is returned, it's parentFileNode
pointer instance shall be null, and the parent will not contain a link to the directory in it's list of child-nodes.- Parameters:
dirName
- This is the name of any directory.
IMPORTANT: This must be the name-only leaving out all parent-directory or drive-letter text.
FURTHERMORE: The forward slash ('/'
) or the back-slash ('\'
) character that sometimes is appended to a directory-name may not be included in this name (unless a forward-slash or back-slash is a part of the name of the directory).
FINALLY: When this directory is extracted, none of the child pointers contained by this directory-instance ofFileNode
will be modified. In essence, the entire sub-tree - starting at the directory that was specified - will be extracted from the parent-tree. Any / all contents of the sub-tree shall be in the same state as they were prior to the extraction.ignoreCase
- For some files and directories, on some operating systems (Microsoft Windows, for instance) file-system name case is not considered relevant when matching directory names. If this parameter is passed TRUE, then name comparisons will use a case-insensitive comparison mechanism.- Returns:
- The child
FileNode
(sub-directory) of'this'
directory whose name matches the name provided by parameter'dirName'
. It's'parent'
field will be null, and the parentFileNode
instance will not have a pointer to the instance that is returned.
If no matching directory is found, then this method shall return null. - Throws:
DirExpectedException
- If'this'
instance ofFileNode
is a file, not a directory, then this exception shall throw. Only directories can contain other instances ofFileNode
.- See Also:
dir(String, boolean)
,children
- Code:
- Exact Method Body:
FileNode ret = dir(dirName, ignoreCase); if (ret != null) { children.remove(ret); ret.parent = null; } return ret;
-
dir
public FileNode dir(java.lang.String dirName)
- Code:
- Exact Method Body:
return dir(dirName, false);
-
dir
public FileNode dir(java.lang.String dirName, boolean ignoreCase)
Retrieves the sub-directoryFileNode
instance named by parameter'dirName'
if there is aFileNode
that is a direct descendant of'this'
instance ofFileNode
.- Parameters:
dirName
- This is the name of any directory.
IMPORTANT: This must be the name-only leaving out all parent-directory or drive-letter text.
FURTHERMORE: The forward slash ('/'
) or the back-slash ('\'
) character that sometimes is appended to a directory-name may not be included in this name (unless a forward-slash or back-slash is a part of the name of the directory).ignoreCase
- For some files and directories, on some operating systems (Microsoft Windows, for instance) file-system name case is not considered relevant when matching directory names. If this parameter is passed TRUE, then name comparisons will use a case-insensitive comparison mechanism.- Returns:
- The child
FileNode
(sub-directory) of this directory whose name matches the name provided by parameter'dirName'
.
If no matching directory is found, then this method shall return null. - Throws:
DirExpectedException
- If'this'
instance ofFileNode
is a file, not a directory, then this exception shall throw. Only directories can contain other instances ofFileNode
.- See Also:
children
,isDirectory
,name
- Code:
- Exact Method Body:
// Only directories may contain other instances of FileNode DirExpectedException.check(this); // We are looking for a directory named 'dirName' // // IMPORTANT: The outer squiqgly-braces are MANDATORY. Without them, there is // "deceptive indentation," because the 'else' is paired with the second-if, // not the first! if (ignoreCase) { for (FileNode fn : children) if (fn.isDirectory && fn.name.equalsIgnoreCase(dirName)) return fn; } else { for (FileNode fn2 : children) if (fn2.isDirectory && fn2.name.equals(dirName)) return fn2; } // Not found, return null. return null;
-
pollFile
public FileNode pollFile(java.lang.String fileName)
- Code:
- Exact Method Body:
return pollFile(fileName, false);
-
pollFile
public FileNode pollFile(java.lang.String fileName, boolean ignoreCase)
Retrieves aFileNode
instance named by parameter'fileName'
if there is aFileNode
that is a direct descendant of'this'
instance ofFileNode
, and that instance is a file (not a directory) whose name matches'fileName'
.
Differing: Different than methodfile(String, boolean)
, this method will "extract" the file from the in-memory file-tree. If a file is found matching the requested name and case requirements, when it is returned, it's parentFileNode
pointer instance shall be null, and the parent will not contain a link to the returnedFileNode
in it's list of child-nodes.- Parameters:
fileName
- This is the name of any file.
IMPORTANT: This must be the name-only leaving out all parent-directory or drive-letter text.ignoreCase
- For some files and directories, on some operating systems (Microsoft Windows, for instance) file-system name case is not considered relevant when matching file-names. If this parameter is passed TRUE, then name comparisons will use a case-insensitive comparison mechanism.- Returns:
- The child
FileNode
of'this'
directory whose name matches the name provided by parameter'fileName'
. It's'parent'
field will be null, and the parentFileNode
instance will not have a pointer to the instance that is returned.
If no matching file is found, then this method shall return null. - Throws:
DirExpectedException
- If'this'
instance ofFileNode
is a file, not a directory, then this exception shall throw. Only directories can contain other instances ofFileNode
.- See Also:
file(String, boolean)
- Code:
- Exact Method Body:
FileNode ret = file(fileName, ignoreCase); if (ret != null) { children.remove(ret); ret.parent = null; } return ret;
-
file
public FileNode file(java.lang.String fileName)
- Code:
- Exact Method Body:
return file(fileName, false);
-
file
public FileNode file(java.lang.String fileName, boolean ignoreCase)
Retrieves aFileNode
named by parameter'fileName'
if there is aFileNode
instance that is a direct descendant of'this' FileNode
that is, itself, a file and not a directory.- Parameters:
fileName
- This is the name of any file.
IMPORTANT: This must be the name-only leaving out all parent-directory or drive-letter text.ignoreCase
- For some files and directories, on some operating systems (Microsoft Windows, for instance) file-name case is not considered relevant when matching file names. If this parameter is passed TRUE, then file-name comparisons will use a case-insensitive comparison mechanism.- Returns:
- An instance of
FileNode
that is a direct-descendant of'this'
directory - and whose name matches the name provided by parameter'fileName'
.
If no matching file is found, then this method shall return null. - Throws:
DirExpectedException
- If'this'
instance ofFileNode
is a file, not a directory, then this exception shall throw. Only directories can contain other instances ofFileNode
.- See Also:
children
,isDirectory
,name
- Code:
- Exact Method Body:
// Only directories may contain other instances of FileNode DirExpectedException.check(this); // We are looking for a file named 'fileName' // // IMPORTANT: The outer squiqly-braces are MANDATORY. Without them, there is // "deceptive indentation," because the 'else' is paired with the second-if, // not the first! if (ignoreCase) { for (FileNode fn : children) if ((! fn.isDirectory) && fn.name.equalsIgnoreCase(fileName)) return fn; } else { for (FileNode fn2 : children) if ((! fn2.isDirectory) && fn2.name.equals(fileName)) return fn2; } // Not found, return null. return null;
-
hashCode
public int hashCode()
This satisfies Java's "hash-code" method requirement. This can facilitate saving instances of this class into tables, maps, lists, etc.- Overrides:
hashCode
in classjava.lang.Object
- Returns:
- A hash-code to be used by a hash-algorithm with likely few crashes. Note that the
hash from Java's
java.lang.String
is simply reused. - Code:
- Exact Method Body:
return toString().hashCode();
-
equals
public final boolean equals(java.lang.Object o)
- Overrides:
equals
in classjava.lang.Object
- Code:
- Exact Method Body:
FileNode other; return (this == o) || ((o != null) && (this.getClass().equals(o.getClass())) && ((other = (FileNode) o).name.equals(this.name)) && (this.parent == other.parent) // NOTE: This is a "Reference Comparison" && (this.isDirectory == other.isDirectory) && (this.fileSize == other.fileSize) && (this.lastModified == other.lastModified) && this.name.equals(other.name) && ( ((this.children == null) && (other.children == null)) || (this.children.equals(other.children))) );
-
clone
public FileNode clone()
Java'sinterface Cloneable
requirements. This instantiates a newFileNode
with identical fields. The fieldVector<FileNode> 'children'
shall be cloned too.- Overrides:
clone
in classjava.lang.Object
- Returns:
- A new
FileNode
whose internal fields are identical to this one.
IMPORTANT (DEEP-CLONE) NOTE: This does not perform a deep-tree-traversal clone. Instead,'this'
instance is merely copied, and it's child nodes have references inserted into the internal list of child-nodes. - See Also:
name
,parent
,isDirectory
- Code:
- Exact Method Body:
if (this.isDirectory) { FileNode ret = new FileNode(this.name, this.parent, this.lastModified); ret.children.addAll(this.children); return ret; } else return new FileNode(this.name, this.parent, this.fileSize, this.lastModified);
-
compareTo
public final int compareTo(FileNode fn)
Java'sinterface Comparable<T>
requirements. This does a very simple comparison using the results to a call of methodpublic String getFullPathname()
- Specified by:
compareTo
in interfacejava.lang.Comparable<FileNode>
- Parameters:
fn
- Any otherFileNode
to be compared to'this' FileNode
. The file or directoriesgetFullPathName()
is used to perform a "String" comparison.- Returns:
- An integer that fulfils Java's
interface Comparable<T> public boolean compareTo(T t)
method requirements. - See Also:
getFullPathName()
- Code:
- Exact Method Body:
return this.getFullPathName().compareTo(fn.getFullPathName());
-
toString
public java.lang.String toString()
Converts'this' FileNode
to aString
.- Specified by:
toString
in interfacejava.lang.CharSequence
- Overrides:
toString
in classjava.lang.Object
- Returns:
- The complete-full path-name of this file or directory.
- Code:
- Exact Method Body:
return this.getFullPathName();
-
charAt
public final char charAt(int index)
Returns thechar
value at the specified index of the results to a call of methodpublic String getFullPathname()
. An index ranges fromzero
tolength() - 1
. The firstchar
value of the sequence is at indexzero
, the next at indexone
, and so on, as for array indexing.
NOTE: If thechar
value specified by the index is a surrogate, the surrogate value is returned.
FINAL METHOD: This method is final, and cannot be modified by sub-classes.- Specified by:
charAt
in interfacejava.lang.CharSequence
- Parameters:
index
- The index of thechar
value to be returned- Returns:
- The specified
char
value - See Also:
getFullPathName()
- Code:
- Exact Method Body:
return this.getFullPathName().charAt(index);
-
length
public final int length()
Returns the length of theString
returned bypublic String getFullPathname()
The length is the number of 16-bit characters in the sequence.
FINAL METHOD: This method is final, and cannot be modified by sub-classes.- Specified by:
length
in interfacejava.lang.CharSequence
- Returns:
- the number of characters in the "Full Path Name" for
'this'
file or\ directory. - See Also:
getFullPathName()
- Code:
- Exact Method Body:
return this.getFullPathName().length();
-
subSequence
public final java.lang.CharSequence subSequence(int start, int end)
Returns ajava.lang.CharSequence
that is a subsequence of the results to a call of methodpublic String getFullPathname()
The subsequence starts with thechar
value at the specified index and ends with thechar
value at index'end - 1'
. The length (in characters) of the returned sequence is'end - start'
, so in the case where'start == end'
then an empty sequence is returned.
FINAL METHOD: This method isfinal
, and cannot be modified by sub-classes.- Specified by:
subSequence
in interfacejava.lang.CharSequence
- Parameters:
start
- The start index, inclusiveend
- The end index, exclusive- Returns:
- The specified subsequence
- See Also:
getFullPathName()
- Code:
- Exact Method Body:
return this.getFullPathName().substring(start, end);
-
nameNoExt
public java.lang.String nameNoExt()
This returns the name of the file, but leaves off the "extension"- Returns:
- Returns the name without the file-extension
- Throws:
FileExpectedException
- Since only files may have extensions, if'this'
instance ofFileNode
is a directory, theFileExpectedException
will throw.- Code:
- Exact Method Body:
FileExpectedException.check(this); // Directories do not have extensions int pos = name.lastIndexOf('.'); if (pos == -1) return name; return name.substring(0, pos);
-
ext
public java.lang.String ext(boolean includeTheDot)
This returns the extension of the file. If this file does not have an extension, then null shall be returned.- Parameters:
includeTheDot
- if the user would like to have the'.'
included in the returnString
, then TRUE should be passed to this parameter.- Returns:
- Returns this file's extension
- Throws:
FileExpectedException
- Since only files may have extensions, if'this'
instance ofFileNode
is a directory, theFileExpectedException
will throw.- Code:
- Exact Method Body:
FileExpectedException.check(this); // Directories do not have extensions int pos = name.lastIndexOf('.'); if (pos == -1) return null; return includeTheDot ? name.substring(pos) : name.substring(pos+1);
-
forEach
public void forEach(java.util.function.Consumer<FileNode> c)
Invokes the inputjava.util.function.Consumer<FileNode>
on each element in the tree. Note that if'this'
instance ofFileNode
is a file, not a directory, then the passedConsumer
shall only be invoked using'this'
instance.- Parameters:
c
- This is any javaConsumer<FileNode>
- Code:
- Exact Method Body:
c.accept(this); children.forEach((FileNode fn) -> fn.forEach(c));
-
deepClone
public FileNode deepClone()
Whereas the standard Javaclone()
method in this class returns a new, cloned, instance ofFileNode
, if'this'
instance ofFileNode
is a directory, the tree-branch represented by'this' FileNode
instance would not be copied by an invocation of'clone'
. However, if using this method,'deepClone'
, on a directory-FileNode
instance, the entire tree-branch represented by'this' FileNode
instance is copied..
NOTE:The method'sclone()
anddeepClone()
shall return identical results when used on an instance ofFileNode
that represents a file, not a directory (and, therefore, does not have any tree-branch information associated with it.).- Returns:
- a "Deep Clone" of
'this' FileNode
instance. If'this'
instance ofFileNode
represents a file, not a directory, the results of this method shall be identical to the results of an invocation of the standard'clone()'
method. If'this' FileNode
represents an operation-system directory (not a file), then each and every child of this tree-branch shall also be copied / cloned by this method. - Code:
- Exact Method Body:
if (this.isDirectory) { FileNode ret = new FileNode(this.name, this.parent, this.lastModified); for (FileNode child : children) ret.children.add(child.deepClone()); return ret; } else return this.clone();
-
loadTree
public FileNode loadTree()
Convenience Method
Invokes:loadTree(int, FilenameFilter, FileFilter)
Passes: All Tree-Branches requested ('-1'
)
And-Passes: null-filters (Requests no filtering be applied).- Code:
- Exact Method Body:
return loadTree(-1, null, null);
-
loadTree
public FileNode loadTree(boolean includeFiles, boolean includeDirectories)
Convenience Method
Invokes:loadTree(int, FilenameFilter, FileFilter)
Passes:'includeFiles'
as aPredicate
to parameter'fileFilter'
Passes:'includeDirectories'
(asPredicate
) to'directoryFilter'
Throws:IllegalArgumentException
If both boolean parameters are FALSE- Code:
- Exact Method Body:
if ((! includeFiles) && (! includeDirectories)) throw new IllegalArgumentException( "loadTree(boolean, boolean) has been invoked with both search criteria booleans set " + "to FALSE. This means that there is nothing for the method to do." ); return loadTree (-1, (File dir, String name) -> includeFiles, (File file) -> includeDirectories);
-
loadTreeJustDirs
public FileNode loadTreeJustDirs(int maxTreeDepth, java.io.FileFilter directoryFilter)
Convenience Method
Invokes:loadTree(int, FilenameFilter, FileFilter)
Passes: 'Always False'Predicate
to parameter'fileFilter'
Accepts: A'directoryFilter'
and'maxTreeDepth'
- Code:
- Exact Method Body:
// Set the return value of the 'fileFilter' predicate to ALWAYS return FALSE. return loadTree(maxTreeDepth, (File dir, String name) -> false, directoryFilter);
-
loadTree
public FileNode loadTree(int maxTreeDepth, java.io.FilenameFilter fileFilter, java.io.FileFilter directoryFilter)
This populates'this' FileNode
tree with the contents of the file-system directory represented by'this'
.
IMPORTANT: This method can only be invoked on an instance of'FileNode'
which represents a directory on the UNIX or MS-DOS file-system. AnDirExpectedException
shall throw if this method is invoked on aFileNode
instance that represents a file.
The following example was used to help search for a local copy of the Google Chrome Binaries on an instance of Google Cloud Server.
Note that although the standard Shell instance on Google Cloud Server apparently does not have a copy of the chrome in its 'Headless' format, a lot of information can be viewed about a file-system's contents using the code below.
Example:
FileNode // Inside Google Cloud Shell, mostly a UNIX Platform, the Root UNIX directory is simply named // "/" (which happens to be the name of the System's File Separator). Note that on MS-DOS // Systems, the root directory is named after the drive-letter. .createRoot(java.io.File.separator) // The directory tree takes several minutes to load, as the files-system actually contains // hundreds of thousands (if not millions) of files. // // This Line Provides Three Restrictions: // - DO NOT GO MORE THAN SIX DIRECTORIES DEEP // - DO NOT LOOK FOR ANY FILES - ONLY DIRECTORIES WHEN LOADING THIS TREE // - ELIMINATE ANY DIRECTORIES NAMED "chrome-trace-event" .loadTreeJustDirs(6, f -> ! f.getName().contains("chrome-trace-event")) // Build a java.util.stream.Stream<String> containing the full-path name of each of these // directory names (as a java.lang.String) .flattenJustDirs(RetTypeChoice.FULLPATH_STREAM) // Filter all directories that are inside the Stream which do not contain the string "chrome" .filter(s -> s.contains("chrome")) // Print those directories to the terminal .forEach((String fileName) -> System.out.println(fileName));
- Parameters:
maxTreeDepth
- The value passed to'maxTreeDepth'
should be set to the maximum number of tree branches to follow, recursively, when traversing the the operating-system's directory-tree / file-system.'maxTreeDepth'
ValueMeaning (Any) Negative Integer Visit the directory-tree to its maximum depth; visit all leaf nodes (files). '0'
(zero)Visit each branch (directory) and leaf node (file) of 'this'
instance ofFileNode
, but do not enter any sub-directories.'1'
(one)Visit each branch (directory) and leaf node (file) of 'this'
instance ofFileNode
, and enter - recursively - any sub-directories that are found. Visit the contents of each of these branches - their files & directories - but do not enter any of those sub-directory tree-branches'2' ... 'n'
Visit the children (both files & directories) of 'this'
instance ofFileNode
, and enter - recursively - any sub-directories found. Apply this process, recursively,n-times
.fileFilter
- This is an interface from thejava.io.*
library. It can be used here to filter which files (not directories) are loaded into the tree.
Thepublic interface java.io.FilenameFilter
has a method with this signature:
Java Method Signature:
public boolean test(File dir, String name)
Where:- The
File dir
parameter represents the containing/parent directory. - The
String name
parameter represents the simple-name of the file not including the full path, or parent-directory.
NOTE: If thisfilter
parameter is passed null, the parameter is ignored - and all files shall be included in the result, with no filtering applied.
ALSO: Consistent with other Java'filter'
mechanisms, thefilter
you provide should be a lambda-expression or method that returns FALSE if the file should be skipped. If the file needs to be included - or 'kept' (and subsequently loaded into the tree), then yourfilter
should return TRUE.- The
directoryFilter
- This is an interface from thejava.io.*
library as well. It can be used here to filter which directories are visited by the recursion algorithm (it ignores files). If a directory fails the"boolean test"
method here, that branch of the tree will not be included in this object.
Thepublic interface java.io.FileFilter
has a method signature of:
Java Method Signature:
public boolean test(File file)
Where:File file
parameter represents an actual UNIX (or MS-DOS) file.
NOTE: If this filter parameter is null, the parameter is ignored - and all sub-directories are visited.
ALSO: The filter used should return FALSE if the passed directory should be skipped. The filter must return TRUE if the directory needs to be included, or 'kept', (and subsequently visited and loaded into the tree).- Returns:
- a reference to
'this' FileNode
, for convenience only. It's tree branches (directories) and leaf nodes (files) will be populated, as per the above parameter specification-criteria. - Throws:
DirExpectedException
- This method will only execute if the instance of'this'
is a directory. Files on the file-system are leaves, not branches - so they do not have contents to load.java.lang.SecurityException
- The methodjava.io.File.listFiles()
is used to retrieve the list of files for each directory. That method asserts that the Java Security Managaerjava.lang.SecurityManager
may throw this exception if a restricted directory is accessed by'listFiles()'
.
BY-PASS NOTE: Those most common behavior for restricted directories has been for thelistFiles()
to simply return null, which is handled easily by this code. If this exception is throwing, one may use the internal (static
flag)SKIP_DIR_ON_SECURITY_EXCEPTION
. When thisstatic-flag
is used,SecurityExceptions
are caught, and the contents of those directories will simply be ignored and eliminated from the tree.- See Also:
loadTree()
,DirExpectedException.check(FileNode)
,SKIP_DIR_ON_SECURITY_EXCEPTION
- Code:
- Exact Method Body:
DirExpectedException.check(this); loadTreeINTERNAL(maxTreeDepth, fileFilter, directoryFilter); return this;
-
numChildren
public int numChildren()
This returns the number of children-nodes in'this'
instance ofFileNode
.
NOTE: This is not a 'recursive' method, and that means the integer returned by this method is only a count of the number of direct-descendants of'this' FileNode
.- Throws:
DirExpectedException
- If'this'
instance ofFileNode
is not a directory, but rather a file, then this exception is thrown. (Files may not have child-nodes, only directories may have them).- See Also:
numDirChildren()
,numFileChildren()
,children
- Code:
- Exact Method Body:
DirExpectedException.check(this); return children.size();
-
numDirChildren
public int numDirChildren()
This returns the exact number of children-nodes that are directories of'this' FileNode
.
NOTE: This is not a 'recursive' method, and that means the integer returned by this method is only a count of the number of direct-descendants of'this' FileNode
.- Throws:
DirExpectedException
- If'this'
instance ofFileNode
is not a directory, but rather a file, then this exception is thrown. (Files may not have child-nodes, only directories may have them).- See Also:
numFileChildren()
,numChildren()
,children
- Code:
- Exact Method Body:
DirExpectedException.check(this); int dirCount = 0; for (int i=0; i < children.size(); i++) if (children.elementAt(i).isDirectory) dirCount++; return dirCount;
-
numFileChildren
public int numFileChildren()
This returns the exact number of children-nodes that are files of'this' FileNode
.
NOTE: This is not a 'recursive' method, and that means the integer returned by this method is only a count of the number of direct-descendants of'this' FileNode
.- Throws:
DirExpectedException
- If'this'
instance ofFileNode
is not a directory, but rather a file, then this exception is thrown. (Files may not have child-nodes, only directories may have them).- See Also:
numDirChildren()
,numChildren()
,isDirectory
,children
- Code:
- Exact Method Body:
DirExpectedException.check(this); int fileCount = 0; for (int i=0; i < children.size(); i++) if (! children.elementAt(i).isDirectory) fileCount++; return fileCount;
-
printTree
public void printTree()
Convenience Method
Passes:System.out
toAppendable
, and nulls
Invokes:printTree(Appendable, boolean, FileNodeFilter, FileNodeFilter)
Catches:Appendable's IOException
. Prints Stack Trace.- Code:
- Exact Method Body:
try { printTree(System.out, false, null, null); } catch (IOException e) { e.printStackTrace(); }
-
printTreeNOIOE
public void printTreeNOIOE(boolean showSizes, FileNodeFilter fileTest, FileNodeFilter directoryTest)
Convenience Method
Passes: 'null' toAppendable
parameter (usesSystem.out
)
Invokes:printTree(Appendable, boolean, FileNodeFilter, FileNodeFilter)
Catches:Appendable's IOException
- Code:
- Exact Method Body:
try { printTree(null, showSizes, fileTest, directoryTest); } catch (IOException ioe) { }
-
printTree
public void printTree(java.lang.Appendable a, boolean showSizes, FileNodeFilter fileTest, FileNodeFilter directoryTest) throws java.io.IOException
This will print the directory tree to thejava.lang.Appendable
passed as a parameter. Specific testPredicate's
may be sent to this method to identify which branches of the File/Directory tree should be printed.- Parameters:
a
- If this is null, thenSystem.out
is used. If it is not null, then information is printed to this Javajava.lang.Appendable
. This parameter expects an implementation of Java'sinterface java.lang.Appendable
which allows for a wide range of options when logging intermediate messages.Class or Interface Instance Use & Purpose 'System.out'
Sends text to the standard-out terminal Torello.Java.StorageWriter
Sends text to System.out
, and saves it, internally.FileWriter, PrintWriter, StringWriter
General purpose java text-output classes FileOutputStream, PrintStream
More general-purpose java text-output classes
IMPORTANT: Theinterface Appendable
requires that the check exceptionIOException
must be caught when using itsappend(CharSequence)
methods.showSizes
- If this is true, then "file-size" information will also be printed with the file.fileTest
- If this is null, then it is ignored, and all files in theFileNode
Directory Tree pass (are accepted). If this parameter is not null, then eachFileNode
that is not a directory is run through thePredicate's
public boolean test(FileNode fn)
method. If the test returns FALSE, then this file is not printed to the output.directoryTest
- If this is null, then it is ignored, and all directories in theFileNode
Directory Tree pass (are accepted). If this parameter is not null, then eachFileNode
that is a directory is run through the Predicate's test method, and any directories that fail thisPredicate's test()
method (whendirectoryTest.test(dir)
returns FALSE), that directory will not be printed to the output.- Throws:
java.io.IOException
- Java'sinterface Appendable
mandates that the unchecked JavaIOException
must be caught when using this interface.- See Also:
printTree()
,getDirContentsFiles()
,getDirContentsDirs()
,fileSize
,getFullPathName()
- Code:
- Exact Method Body:
if (a == null) a = System.out; for (FileNode file : getDirContentsFiles(fileTest)) a.append((showSizes ? (file.fileSize + ",\t") : "") + file.getFullPathName() + '\n'); for (FileNode dir : getDirContentsDirs(directoryTest)) { a.append(dir.getFullPathName() + '\n'); dir.printTree(a, showSizes, fileTest, directoryTest); }
-
getDirContentsSize
public long getDirContentsSize()
Convenience Method
Invokes:getDirContentsSize(FileNodeFilter)
Passes: null to filter-parameter'fileTest'
. (All file-sizes are counted)- Code:
- Exact Method Body:
return getDirContentsSize(null);
-
getDirContentsSize
public long getDirContentsSize(FileNodeFilter fileTest)
This sums the file-sizes of each file in the current directory, not sub-directories that pass the requirements of thePredicate<FileNode>
here. Ifp.test(fileNode)
fails, then the size of aFileNode
is not counted in the total sum.
NOTE: This only retrieves the contents of'this'
directory - and does not expand the leaf-node directories when scanning for files or sub-directories sizes!- Parameters:
fileTest
- Any javaPredicate
that satisfies the requirement of having a:public boolean test(FileNode f);
method. theinterface 'FileNodeFilter'
will also work, if using Java 7.
This is used to "test" whether to include the files in a directory'fileSize
in the summed return value. When TRUE is returned by thePredicate test(...)
method, a file's size will be included in the sum-total directory-size. When thePredicate test(...)
method returns FALSE, the tested file's size will be ignored and not included in the total.
This may be null, and if it is, it is ignored. This means that file-sizes for all files in the directory will count towards the total-size returned by this method.- Returns:
- The sum of file-sizes for each file which passes the
Predicate
test in this directory. - Throws:
DirExpectedException
- If'this'
instance ofFileNode
is not a directory, but rather a file, then this exception is thrown. (Files may not have child-nodes, only directories).- See Also:
fileSize
,children
,isDirectory
- Code:
- Exact Method Body:
DirExpectedException.check(this); long size=0; for (FileNode f : children) if (! f.isDirectory) if ((fileTest == null) || fileTest.test(f)) size += f.fileSize; return size;
-
getDirTotalContentsSize
public long getDirTotalContentsSize()
Convenience Method
Invokes:getDirTotalContentsSize(FileNodeFilter, FileNodeFilter)
Passes: null to both-filters (all file-sizes counted, no directories skipped)- Code:
- Exact Method Body:
return getDirTotalContentsSize(null, null);
-
getDirTotalContentsSize
public long getDirTotalContentsSize(FileNodeFilter fileTest, FileNodeFilter directoryTest)
This sums the file contents in the current directory - and all sub-directories as well. Only files that pass thePredicate 'fileTest'
parameter are counted. Furthermore, only directories that pass thePredicate 'directoryTest'
will be traversed and inspected.- Parameters:
fileTest
- Anyjava.util.function.Predicate
or lambda-expressions that satisfies the requirement of having a:public boolean test(FileNode f);
method. Implementing theinterface 'FileNodeFilter'
will also work, if using Java 7.
This is used to "test" whether to include thefileSize
for a specific file in a directory in the summed return value. When TRUE is returned by thePredicate 'test'
method, a file's size will be included in the sum-total directory-size. When thePredicate 'test'
method returns FALSE, the tested file's size will be ignored, and not included in the total.
This may be null, and if it is, it is ignored. This means that file-sizes for all files in the directory will count towards the total-size returned by this method.directoryTest
- java predicate that satisfies the requirement of having a:public boolean test(FileNode f);
method. Theinterface 'FileNodeFilter'
will also work, if using Java 7.
This is used to test directories, rather than files, for inclusion in the total file-size returned by this method. When TRUE is returned by thefilter's 'test'
method, then that directory shall be traversed, inspected, and its contents shall have theirfileSize's
included in the computed result.
This parameter may be null, and if it is, it is ignored. This would mean that all sub-directories shall be traversed when computing the total directory size.- Returns:
- The sum of all file-sizes for each file in this directory that pass
'fileTest'
, and all sub-dir's that pass the'directoryTest'
. - Throws:
DirExpectedException
- If'this'
instance ofFileNode
is not a directory, but rather a file, then this exception is thrown. (Files may not have child-nodes, only directories). (- See Also:
fileSize
,children
,getDirTotalContentsSize()
- Code:
- Exact Method Body:
DirExpectedException.check(this); long size=0; for (FileNode f : children) if (f.isDirectory) { if ((directoryTest == null) || directoryTest.test(f)) size += f.getDirTotalContentsSize(fileTest, directoryTest); } else { if ((fileTest == null) || fileTest.test(f)) size += f.fileSize; } return size;
-
count
public int count()
Convenience Method
Invokes:count(FileNodeFilter, FileNodeFilter)
Passes: null to both filter-parameters. (All files and directories are counted)- Code:
- Exact Method Body:
return count(null, null);
-
count
public int count(FileNodeFilter fileFilter, FileNodeFilter directoryFilter)
Performs a count on the total number of files and directories contained by'this'
directory. This method is recursive, and traverses both'this'
directory, and all sub-directories when calculating the return-value.- Parameters:
fileFilter
- This allows a user to eliminate certain files from the total count.
The filter provided should be aPredicate<FileNode>
that returns TRUE if the file should be counted, and FALSE if the file should not be counted.
This parameter may be'null'
, and if it is, it will be ignored. In such cases, all files will be included in the total count.directoryFilter
- This allows a user to skip branches of the directory-tree when performing the count.
The filter provided should be aPredicate<FileNode>
that returns TRUE if the sub-directory should be entered (and counted), and FALSE if the sub-directory tree-branch should be skipped completely.
This parameter may be'null'
, and if it is, it will be ignored. In such cases, all sub-directory branches will be used when making the total count.
NOTE: When this filter-parameter returns FALSE, the entire sub-directory tree-branch will be skipped completely. Any branches of the directory-tree that would actually pass the'directoryFilter'
test are rendered irrelevant if a parent sub-directory branch has failed the'directoryFilter'
test.- Returns:
- A total count of all files and sub-directories contained by
'this'
instance ofFileNode
- 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 aFileNode
that is a 'file' rather than a 'directory'.- Code:
- Exact Method Body:
DirExpectedException.check(this); // This was moved to an "INTERNAL" method to avoid invoking the above exception check // every time this (recursive) code encounters a directory. return countINTERNAL(fileFilter, directoryFilter);
-
countJustFiles
public int countJustFiles()
Convenience Method
Invokes:countJustFiles(FileNodeFilter, FileNodeFilter)
Passes: null to both filter-parameters (all files counted, no directories skipped).- Code:
- Exact Method Body:
return countJustFiles(null, null);
-
countJustFiles
public int countJustFiles(FileNodeFilter fileFilter, FileNodeFilter directoryFilter)
Performs a count on the total number of files only (does not count sub directories) contained by'this'
directory. This method is recursive, and traverses both'this'
directory, and all sub-directories when calculating the return-value.- Parameters:
fileFilter
- This allows a user to eliminate certain files from the total count.
The filter provided should be aPredicate<FileNode>
that returns TRUE if the file should be counted, and FALSE if the file should not be counted.
This parameter may be'null'
, and if it is, it will be ignored. In such cases, all files will be included in the total count.directoryFilter
- This allows a user to skip branches of the directory-tree when performing the count.
The filter provided should be aPredicate<FileNode>
that returns TRUE if the sub-directory should be entered (the directory itself will not contribute to the count). When this filter returns FALSE the sub-directory tree-branch will be skipped completely, and any files in those sub-directories will not contribute to the total file-count.
This parameter may be'null'
, and if it is, it will be ignored. In such cases, all sub-directory branches will be used when making the total count.
NOTE: When this filter-parameter returns FALSE, the entire sub-directory tree-branch will be skipped completely. Any branches of the directory-tree that would actually pass the'directoryFilter'
test are rendered irrelevant if a parent sub-directory branch has failed the'directoryFilter'
test.- Returns:
- A total count of all files (excluding sub-directories) contained by
'this'
instance ofFileNode
- less the files that reside in directory-tree branches that were excluded by the'directoryFilter'
parameter and less the files that were excluded by'fileFilter'
. - Throws:
DirExpectedException
- If the user has attempted to perform a count on aFileNode
that is a 'file' rather than a 'directory'.- Code:
- Exact Method Body:
DirExpectedException.check(this); // This was moved to an "INTERNAL" method to avoid invoking the above exception check // every time this (recursive) code encounters a directory. return countJustFilesINTERNAL(fileFilter, directoryFilter);
-
countJustDirs
public int countJustDirs()
Convenience Method
Invokes:countJustDirs(FileNodeFilter)
Passes: null to'directorFilter'
(all directories are counted).- Code:
- Exact Method Body:
return countJustDirs(null);
-
countJustDirs
public int countJustDirs(FileNodeFilter directoryFilter)
Performs a count on the total number of sub-directories contained by'this'
directory. This method is recursive, and traverses all sub-directories when calculating the return-value.- Parameters:
directoryFilter
- This allows a user to skip branches of the directory-tree when performing the count.
The filter provided should be aPredicate<FileNode>
that returns TRUE if the sub-directory should be entered and FALSE if sub-directory tree-branch should be skipped completely.
This parameter may be'null'
, and if it is, it will be ignored. In such cases, all sub-directory branches will be used when making the total count.
NOTE: When this filter-parameter returns FALSE, the entire sub-directory tree-branch will be skipped completely. Any branches of the directory-tree that would actually pass the'directoryFilter'
test are rendered irrelevant if a parent sub-directory branch has failed the'directoryFilter'
test.- Returns:
- A total count of all sub-directories contained by
'this'
instance ofFileNode
- less the sub-directories that reside in directory-tree branches that were excluded by the'directoryFilter'
parameter. - Throws:
DirExpectedException
- If the user has attempted to perform a count on aFileNode
that is a 'file' rather than a 'directory'.- Code:
- Exact Method Body:
DirExpectedException.check(this); // This was moved to an "INTERNAL" method to avoid invoking the above exception check // every time this (recursive) code encounters a directory. return countJustDirsINTERNAL(directoryFilter);
-
getDirContents
public java.util.Vector<FileNode> getDirContents()
Convenience Method
Automatically Selects:FileNode.RetTypeChoice.VECTOR
Invokes:getDirContents(VarList, FileNodeFilter)
Passes: null to parameter'filter'
(all files and directories found will be returned).- Code:
- Exact Method Body:
return getDirContents(RetTypeChoice.VECTOR, null);
-
getDirContents
public <T> T getDirContents(VarList<T,FileNode> listChoice)
Convenience Method
Accepts:FileNode.RetTypeChoice
. (Specifies Output Data-Structure & Contents)
Invokes:getDirContents(VarList, FileNodeFilter)
Passes: null to parameter'filter'
(all files and directories found will be returned).- Code:
- Exact Method Body:
return getDirContents(listChoice, null);
-
getDirContents
public java.util.Vector<FileNode> getDirContents(FileNodeFilter filter)
Convenience Method
Automatically Selects:FileNode.RetTypeChoice.VECTOR
Accepts:FileNodeFilter
Invokes:getDirContents(VarList, FileNodeFilter)
- Code:
- Exact Method Body:
return getDirContents(RetTypeChoice.VECTOR, filter);
-
getDirContents
public <T> T getDirContents(VarList<T,FileNode> listChoice, FileNodeFilter filter)
This method returns the contents of a single-directory in the directory-tree, the sub-directories are returned, but the contents of the sub-directories are not. Any method whose name begins with'getDirContents ...'
will not traverse the directory tree. Instead, only the contents of the internal'children' Vector<FileNode>
of'this'
instance ofFileNode
are iterated and returned.
IMPORTANT: This method may only be invoked onFileNode
instances which, themselves, represent directories on the file-system, not files. If this method is erroneously invoked on a 'file' instead of a 'directory', you should expect aDirExpectedException
exception to throw. Remember: files on the file-system do not have 'contents' (specifically: other files and sub-directories), only directories may contain them.
TREE TRAVERSAL NOTE: This method does not recursively traverse the directory-tree. The search logic of anygetDirContents
method will only visit the contents of'this' FileNode
instance (the one on which this method was invoked).
To retrieve a list, collection, stream or array of the entire directory-tree rooted at'this'
instance, instead use one of theflatten
methods.- Type Parameters:
T
- This type parameter may be chosen using theRetTypeChoice
inner-class. It is used to determine the return type of this method, for which many options exist.- Parameters:
listChoice
- This allows the user to choose a particularContainer
orList
, such asVector, Stream,
orarray
. Furthermore the ability to specify a sort-type, and a data-out choice including File-Name, Full-Path Name, or File-Node is provided by a long list of options inclass RetTypeChoice
See:FileNode.RetTypeChoice
.filter
- When this parameter is used, any files or directories that do not pass thefilter's 'test'
method shall not be included in the returne data-structure. Thefilter
that is passed should return TRUE when a file or directory needs to be included in the returned-result. When the providedfilter
returns FALSE as a result of testing a file or directory, the returned data-structure will exclude it.
If this parameter is null, it will be ignored, and everyFileNode
contained by'this'
directory-instance will be included in the result.- Returns:
- A list containing the files & sub-directories inside
'this'
directory.
The implementation ofVarList<T, FileNode>
used inside ofclass FileNode.RetTypeChoice
allows a user of this API to specify the return type of this method. There are dozens of options for what file-system information about each file being returned should include, and how these returned instances ofFileNode
should be sorted. Note that this return-value allows for converting the files to their name as JavaString's
- among other operations.
Furthermore, thestatic
member fields inclass RetTypeChoice
also allow a programmer to choose a container for holding these instances ofFileNode
(orString
-convertedFileNode's
).
See:FileNode.RetTypeChoice
. - Throws:
DirExpectedException
- This exception will throw if'this' FileNode
instance is representing a file, rather than a directory. It is (hopefully) obvious that files may not have child-nodes (other files and directories), only directories may have them.- See Also:
FileNodeFilter
,children
- Code:
- Exact Method Body:
DirExpectedException.check(this); VarList<T, FileNode> ret = listChoice.create(); children.forEach ((FileNode fn) -> { if ((filter == null) || filter.test(fn)) ret.insert(fn); }); return ret.retrieve();
-
getDirContentsDirs
public java.util.Vector<FileNode> getDirContentsDirs()
Convenience Method
Automatically Selects:FileNode.RetTypeChoice.VECTOR
Invokes:getDirContentsDirs(VarList, FileNodeFilter)
Passes: null to parameter'filter'
(all directories found are returned).- Code:
- Exact Method Body:
return getDirContentsDirs(RetTypeChoice.VECTOR, null);
-
getDirContentsDirs
public <T> T getDirContentsDirs(VarList<T,FileNode> listChoice)
Convenience Method
Accepts:FileNode.RetTypeChoice
(Specifies Output Data-Structure & Contents)
Invokes:getDirContentsDirs(VarList, FileNodeFilter)
Passes: null to parameter'filter'
(all directories found are returned).- Code:
- Exact Method Body:
return getDirContentsDirs(listChoice, null);
-
getDirContentsDirs
public java.util.Vector<FileNode> getDirContentsDirs (FileNodeFilter filter)
Convenience Method
Automatically Selects:FileNode.RetTypeChoice.VECTOR
Accepts:FileNodeFilter
Invokes:getDirContentsDirs(VarList, FileNodeFilter)
- Code:
- Exact Method Body:
return getDirContentsDirs(RetTypeChoice.VECTOR, filter);
-
getDirContentsDirs
public <T> T getDirContentsDirs(VarList<T,FileNode> listChoice, FileNodeFilter filter)
This method is nearly identical to the methodgetDirContents(FileNodeFilter)
. This method, alternatively, will 'logically-and' afilter
that first eliminates any and allFileNode
instances which, themselves, represent 'files'. This method will preclude 'files' from passing the user-provided filter-logic test (and thereby prevent 'files' from being included in the result-set). Only directories can be members of the returned data-structure.
This method only returns the contents of a single-directory in the directory-tree. Any directories in sub-directories will not be retrieved.
IMPORTANT: This method may only be invoked onFileNode
instances which, themselves, represent directories on the file-system, not files. If this method is erroneously invoked on a 'file' instead of a 'directory', you should expect aDirExpectedException
exception to throw. Remember: files on the file-system do not have 'contents' (specifically: other files and sub-directories), only directories may contain them.
TREE TRAVERSAL NOTE: This method does not recursively traverse the directory-tree. The search logic of anygetDirContents
method will only visit the contents of'this' FileNode
instance (the one on which this method was invoked).
To retrieve a list, collection, stream or array of the entire directory-tree rooted at'this'
instance, instead use one of theflatten
methods.- Type Parameters:
T
- This type parameter may be chosen using theRetTypeChoice
inner-class. It is used to determine the return type of this method, for which many options exist.- Parameters:
listChoice
- This allows the user to choose a particularContainer
orList
, such asVector, Stream,
orarray
. Furthermore the ability to specify a sort-type, and a data-out choice including File-Name, Full-Path Name, or File-Node is provided by a long list of options inclass RetTypeChoice
See:FileNode.RetTypeChoice
.filter
-- Returns:
- A list containing sub-directories rooted at
'this'
directory.
The implementation ofVarList<T, FileNode>
used inside ofclass FileNode.RetTypeChoice
allows a user of this API to specify the return type of this method. There are dozens of options for what file-system information about each file being returned should include, and how these returned instances ofFileNode
should be sorted. Note that this return-value allows for converting the files to their name as JavaString's
- among other operations.
Furthermore, thestatic
member fields inclass RetTypeChoice
also allow a programmer to choose a container for holding these instances ofFileNode
(orString
-convertedFileNode's
).
See:FileNode.RetTypeChoice
. - Throws:
DirExpectedException
- This exception will throw if'this' FileNode
instance is representing a file, rather than a directory. It is (hopefully) obvious that files may not have child-nodes (other files and directories), only directories may have them.- See Also:
FileNodeFilter
,isDirectory
- Code:
- Exact Method Body:
FileNodeFilter dirFilter = (FileNode fn) -> fn.isDirectory; return getDirContents(listChoice, (filter != null) ? filter.and(dirFilter) : dirFilter);
-
getDirContentsFiles
public java.util.Vector<FileNode> getDirContentsFiles()
Convenience Method
Automatically Selects:FileNode.RetTypeChoice.VECTOR
Invokes:getDirContentsFiles(VarList, FileNodeFilter)
Passes: null to parameter'filter'
(all files found are returned).- Code:
- Exact Method Body:
return getDirContentsFiles(RetTypeChoice.VECTOR, null);
-
getDirContentsFiles
public <T> T getDirContentsFiles(VarList<T,FileNode> listChoice)
Convenience Method
Accepts:FileNode.RetTypeChoice
(Specifies Output Data-Structure & Contents)
Invokes:getDirContentsFiles(VarList, FileNodeFilter)
Passes: null to parameter'filter'
(all files found are returned).- Code:
- Exact Method Body:
return getDirContentsFiles(listChoice, null);
-
getDirContentsFiles
public java.util.Vector<FileNode> getDirContentsFiles (FileNodeFilter filter)
Convenience Method
Automatically Selects:FileNode.RetTypeChoice.VECTOR
Accepts:FileNodeFilter
Invokes:getDirContentsFiles(VarList, FileNodeFilter)
- Code:
- Exact Method Body:
return getDirContentsFiles(RetTypeChoice.VECTOR, filter);
-
getDirContentsFiles
public <T> T getDirContentsFiles(VarList<T,FileNode> listChoice, FileNodeFilter filter)
This method is nearly identical to the methodgetDirContents(FileNodeFilter)
. This method, alternatively, will 'logically-and' afilter
that first eliminates any and allFileNode
instances which, themselves, represent 'directories'. This method will preclude 'directories' from passing the user-provided filter-logic test (and thereby prevent 'directories' from being included in the result-set). Only files can be members of the returned data-structure.
This method only returns the contents of a single-directory in the directory-tree. Any files in sub-directories will not be retrieved.
IMPORTANT: This method may only be invoked onFileNode
instances which, themselves, represent directories on the file-system, not files. If this method is erroneously invoked on a 'file' instead of a 'directory', you should expect aDirExpectedException
exception to throw. Remember: files on the file-system do not have 'contents' (specifically: other files and sub-directories), only directories may contain them.
TREE TRAVERSAL NOTE: This method does not recursively traverse the directory-tree. The search logic of anygetDirContents
method will only visit the contents of'this' FileNode
instance (the one on which this method was invoked).
To retrieve a list, collection, stream or array of the entire directory-tree rooted at'this'
instance, instead use one of theflatten
methods.- Type Parameters:
T
- This type parameter may be chosen using theRetTypeChoice
inner-class. It is used to determine the return type of this method, for which many options exist.- Parameters:
listChoice
- This allows the user to choose a particularContainer
orList
, such asVector, Stream,
orarray
. Furthermore the ability to specify a sort-type, and a data-out choice including File-Name, Full-Path Name, or File-Node is provided by a long list of options inclass RetTypeChoice
See:FileNode.RetTypeChoice
.filter
-- Returns:
- A
Vector
that contains the files inside the current directory.
The implementation ofVarList<T, FileNode>
used inside ofclass FileNode.RetTypeChoice
allows a user of this API to specify the return type of this method. There are dozens of options for what file-system information about each file being returned should include, and how these returned instances ofFileNode
should be sorted. Note that this return-value allows for converting the files to their name as JavaString's
- among other operations.
Furthermore, thestatic
member fields inclass RetTypeChoice
also allow a programmer to choose a container for holding these instances ofFileNode
(orString
-convertedFileNode's
).
See:FileNode.RetTypeChoice
. - Throws:
DirExpectedException
- This exception will throw if'this' FileNode
instance is representing a file, rather than a directory. It is (hopefully) obvious that files may not have child-nodes (other files and directories), only directories may have them.- See Also:
FileNodeFilter
,isDirectory
- Code:
- Exact Method Body:
FileNodeFilter fileFilter = (FileNode fn) -> ! fn.isDirectory; return getDirContents (listChoice, (filter != null) ? filter.and(fileFilter) : fileFilter);
-
flattenJustDirs
public java.util.Vector<FileNode> flattenJustDirs()
Convenience Method
Automatically Selects:FileNode.RetTypeChoice.VECTOR
Invokes:flatten(VarList, int, FileNodeFilter, boolean, FileNodeFilter, boolean)
Parameter:'includeDirectoriesInResult'
set TRUE
Parameter:'includeFilesInResult'
set FALSE
Passes: null to both filter-parameters (all files & directories are returned)- Code:
- Exact Method Body:
return flatten(RetTypeChoice.VECTOR, -1, null, false, null, true);
-
flattenJustDirs
public <T> T flattenJustDirs(VarList<T,FileNode> listChoice)
Convenience Method
Accepts:FileNode.RetTypeChoice
(Specifies Output Data-Structure & Contents)
Invokes:flatten(VarList, int, FileNodeFilter, boolean, FileNodeFilter, boolean)
Parameter:'includeDirectoriesInResult'
set TRUE
Parameter:'includeFilesInResult'
set FALSE
Passes: null to both filter-parameters (all directories are returned by this method).- Code:
- Exact Method Body:
return flatten(listChoice, -1, null, false, null, true);
-
flattenJustDirs
public java.util.Vector<FileNode> flattenJustDirs (int maxTreeDepth, FileNodeFilter directoryFilter)
Convenience Method
Automatically Selects:FileNode.RetTypeChoice.VECTOR
Invokes:flatten(VarList, int, FileNodeFilter, boolean, FileNodeFilter, boolean)
Parameter:'includeDirectoriesInResult'
set TRUE
Parameter:'includeFilesInResult'
set FALSE
Accepts:'directoryFilter'
parameter.- Code:
- Exact Method Body:
return flatten(RetTypeChoice.VECTOR, maxTreeDepth, null, false, directoryFilter, true);
-
flattenJustDirs
public <T> T flattenJustDirs(VarList<T,FileNode> listChoice, int maxTreeDepth, FileNodeFilter directoryFilter)
Convenience Method
Accepts:FileNode.RetTypeChoice
(Specifies Output Data-Structure & Contents)
Invokes:flatten(VarList, int, FileNodeFilter, boolean, FileNodeFilter, boolean)
Parameter:'includeDirectoriesInResult'
set TRUE
Parameter:'includeFilesInResult'
set FALSE
Accepts:'directoryFilter'
parameter- Code:
- Exact Method Body:
return flatten(listChoice, maxTreeDepth, null, false, directoryFilter, true);
-
flattenJustFiles
public java.util.Vector<FileNode> flattenJustFiles()
Convenience Method
Automatically Selects:FileNode.RetTypeChoice.VECTOR
Invokes:flatten(VarList, int, FileNodeFilter, boolean, FileNodeFilter, boolean)
Parameter:includeDirectoriesInResult
set FALSE
Parameter:includeFilesInResult
set TRUE
Passes: null to both filter-parameters (all files are returned)- Code:
- Exact Method Body:
return flatten(RetTypeChoice.VECTOR, -1, null, true, null, false);
-
flattenJustFiles
public <T> T flattenJustFiles(VarList<T,FileNode> listChoice)
Convenience Method
Accepts:FileNode.RetTypeChoice
(Specifies Output Data-Structure & Contents)
Invokes:flatten(VarList, int, FileNodeFilter, boolean, FileNodeFilter, boolean)
Parameter:includeDirectoriesInResult
set FALSE
Parameter:includeFilesInResult
set TRUE
Passes: null to both filter-parameters (all files are returned)- Code:
- Exact Method Body:
return flatten(listChoice, -1, null, true, null, false);
-
flattenJustFiles
public java.util.Vector<FileNode> flattenJustFiles (int maxTreeDepth, FileNodeFilter fileFilter)
Convenience Method
Automatically Selects:FileNode.RetTypeChoice.VECTOR
Invokes:flatten(VarList, int, FileNodeFilter, boolean, FileNodeFilter, boolean)
Parameter:includeDirectoriesInResult
set FALSE
Parameter:includeFilesInResult
set TRUE
Accepts:'fileFilter'
parameter- Code:
- Exact Method Body:
return flatten(RetTypeChoice.VECTOR, maxTreeDepth, fileFilter, true, null, false);
-
flattenJustFiles
public <T> T flattenJustFiles(VarList<T,FileNode> listChoice, int maxTreeDepth, FileNodeFilter fileFilter)
Convenience Method
Accepts:FileNode.RetTypeChoice
(Specifies Output Data-Structure & Contents)
Invokes:flatten(VarList, int, FileNodeFilter, boolean, FileNodeFilter, boolean)
Parameter:includeDirectoriesInResult
set FALSE
Parameter:includeFilesInResult
set TRUE- Code:
- Exact Method Body:
return flatten(listChoice, maxTreeDepth, fileFilter, true, null, false);
-
flatten
public java.util.Vector<FileNode> flatten()
Convenience Method
Automatically Selects:FileNode.RetTypeChoice.VECTOR
Invokes:flatten(VarList, int, FileNodeFilter, boolean, FileNodeFilter, boolean)
Parameters:includeFilesInResult, includeDirectoriesInResult
both set TRUE
Passes: null to both filter-parameers (all files & directories are returned)- Code:
- Exact Method Body:
return flatten(RetTypeChoice.VECTOR, -1, null, true, null, true);
-
flatten
public <T> T flatten(VarList<T,FileNode> listChoice)
Convenience Method
Accepts:FileNode.RetTypeChoice
(Specifies Output Data-Structure & Contents)
Invokes:flatten(VarList, int, FileNodeFilter, boolean, FileNodeFilter, boolean)
Parameters:includeFilesInResult, includeDirectoriesInResult
both set TRUE
Passes: null to both filter-parameers (all files & directories are returned)- Code:
- Exact Method Body:
return flatten(listChoice, -1, null, true, null, true);
-
flatten
public java.util.Vector<FileNode> flatten (int maxTreeDepth, FileNodeFilter fileFilter, boolean includeFilesInResult, FileNodeFilter directoryFilter, boolean includeDirectoriesInResult)
Convenience Method
Automatically Selects:FileNode.RetTypeChoice.VECTOR
Invokes:flatten(VarList, int, FileNodeFilter, boolean, FileNodeFilter, boolean)
Accepts: Both filters (directoryFilter, fileFilter
) may be passed.
Accepts: Both'includeIn'
boolean-flags may be passed.- Code:
- Exact Method Body:
return flatten(RetTypeChoice.VECTOR, maxTreeDepth, fileFilter, includeFilesInResult, directoryFilter, includeDirectoriesInResult );
-
flatten
public <T> T flatten(VarList<T,FileNode> listChoice, int maxTreeDepth, FileNodeFilter fileFilter, boolean includeFilesInResult, FileNodeFilter directoryFilter, boolean includeDirectoriesInResult)
This flattens theFileNode
tree into a data-structure of your choosing. Review & read the parameter explanations below, closely, to see what the specifiers do.
GENERALLY: The concept of "flatten" is identical to the concept of "retrieve" or "search" - because all of these perform the 'copying' of a set offilter
-matches into a list. If one wishes to scour or search aFileNode
tree, and obtain the individual nodes of the tree and save them into a list (or other data-structure of your choosing), it can be done easily by writing the appropriate file & directory filter-predicates (using Java "lambda" expressions or actual methods) - and then invoking one of the several overloadedflatten(...)
methods offered by this class..
If you would like to "flatten" the entire tree into aVector
or some other type of list or data-structure, then leave both of thefilter
parameters blank (by passing them null), and also pass'-1'
to parameter'maxTreeDepth'
. Everything in the directory-tree that is rooted at'this'
instance ofFileNode
is returned into a data-structure of your choosing.- Type Parameters:
T
- This type parameter may be chosen using theRetTypeChoice
inner-class. It is used to determine the return type of this method, for which many options exist.- Parameters:
listChoice
- This allows the user to choose a particularContainer
orList
, such asVector, Stream,
orarray
. Furthermore the ability to specify a sort-type, and a data-out choice including File-Name, Full-Path Name, or File-Node is provided by a long list of options inclass RetTypeChoice
See:FileNode.RetTypeChoice
.maxTreeDepth
- The value passed to'maxTreeDepth'
should be set to the maximum number of tree branches to follow, recursively, when traversing the the operating-system's directory-tree / file-system.'maxTreeDepth'
ValueMeaning (Any) Negative Integer Visit the directory-tree to its maximum depth; visit all leaf nodes (files). '0'
(zero)Visit each branch (directory) and leaf node (file) of 'this'
instance ofFileNode
, but do not enter any sub-directories.'1'
(one)Visit each branch (directory) and leaf node (file) of 'this'
instance ofFileNode
, and enter - recursively - any sub-directories that are found. Visit the contents of each of these branches - their files & directories - but do not enter any of those sub-directory tree-branches'2' ... 'n'
Visit the children (both files & directories) of 'this'
instance ofFileNode
, and enter - recursively - any sub-directories found. Apply this process, recursively,n-times
.fileFilter
- This is a Java 8 "accept"interface java.util.function.Predicate
. Implementing the'test(FileNode)'
method, allows one to pick & choose which files will be visited as the tree is recursively traversed. Use a lambda-expression, if needed or for convenience.
NOTE: This parameter may be null, and if so - all files are will be presumed to pass thefilter test
.
JAVA STREAM'S The behavior of thisfilter
-logic is identical to the Java 8+ Streams-Method'filter(Predicate<...>)'
. Specifically, when thefilter
returns a TRUE value for a particularFileNode
, thatFileNode
shall be retained, or 'kept', in the returned result-set. When thefilter
returns FALSE for aFileNode
, that file or directory will be removed from the result-set.
One way to think about which files are included in the results of a'flatten'
operation is by this list below:- Whether/if the
boolean includeFilesInResult
boolean-flag has been set to TRUE. - Whether the
FileNode
would pass thefileFilter.test
predicate (if one has been provided, otherwise ignore this metric). - Whether the containing directory's
FileNode
would pass thedirectoryFilter.test
predicate (if one has been provided, otherwise ignore this metric). - Whether or not all parent-containing directories of the
FileNode
would pass thedirectoryFilter.test
predicate (if one were provided).
- Whether/if the
includeFilesInResult
- If this parameter is TRUE, then files will be included in the resultingVector
.
NOTE: If this parameter is FALSE, this value will "over-ride" any results that may be produced from thepublic boolean fileFilter.test(this)
method (if such a filter had been provided).directoryFilter
- This is also a Java 8 "Predicate Filter"interface java.util.function.Predicate
. Implementing the'test(FileNode)'
method, allows one to pick & choose which directories will be visited as the tree is recursively traversed. Use a lambda-expression, if needed or for convenience.
NOTE: This parameter may be null, and if so - all directories will be traversed.
JAVA STREAM'S The behavior of thisfilter
-logic is identical to the Java 8+ Streams-Method'filter(Predicate<...>)'.
Specifically, when thefilter
returns a TRUE value for a particularFileNode
, thatFileNode
shall be retained, or 'kept', in the returned result-set. When thefilter
returns FALSE for aFileNode
, that file or directory will be removed from the result-set.
IMPORTANT: There is no way to differentiate between which directories are traversed and which directories are included in the result set - if a directory is not traversed or examined, then that directory, and any/all files and sub-directories contained by that directory will all be eliminted from the returned-results.
One way to think about which directories are included in the results of a'flatten'
operation is by this list below:- Whether/if the
boolean includeDirectoriesInResult
boolean-flag has been set to TRUE. - Whether that
FileNode
would pass thedirectoryFilter.test
predicate (if one has been provided, otherwise ignore this metric). - Whether or not all parent directories of the
FileNode
would also pass thedirectoryFilter.test
predicate (if one were provided).
- Whether/if the
includeDirectoriesInResult
- If this parameter is TRUE, then directories will be included in the resultingVector
.
NOTE: If this parameter is FALSE, this value will "over-ride" any results that may be produced from thepublic boolean directoryFilter.test(this)
method.- Returns:
- A flattened version of this tree.
The implementation ofVarList<T, FileNode>
used inside ofclass FileNode.RetTypeChoice
allows a user of this API to specify the return type of this method. There are dozens of options for what file-system information about each file being returned should include, and how these returned instances ofFileNode
should be sorted. Note that this return-value allows for converting the files to their name as JavaString's
- among other operations.
Furthermore, thestatic
member fields inclass RetTypeChoice
also allow a programmer to choose a container for holding these instances ofFileNode
(orString
-convertedFileNode's
).
See:FileNode.RetTypeChoice
. - Throws:
DirExpectedException
- If'this'
instance ofFileNode
is not a directory, but a file, then this exception is thrown. (Files may not have child-nodes, only directories).java.lang.IllegalArgumentException
- If the value of'maxTreeDepth'
is set tozero
, then this exception shall be thrown because the method-invocation would not be making an actual request to do anything.
This exception shall *also* be throw if both of the boolean parameters are set to FALSE, for the same reason being that the method-invocation would not be making a request.- Code:
- Exact Method Body:
DirExpectedException.check(this); if (maxTreeDepth == 0) throw new IllegalArgumentException( "flatten(int, FileNodeFilter, boolean, directoryFilter, boolean) has been invoked " + "with the maxTreeDepth (integer) parameter set to zero. This means that there is " + "nothing for the method to do." ); if ((! includeFilesInResult) && (! includeDirectoriesInResult)) throw new IllegalArgumentException( "flatten(int, FileNodeFilter, boolean, directoryFilter, boolean) has been invoked " + "with both of the two boolean search criteria values set to FALSE. This means that " + "there is nothing for the method to do." ); // This allows us to permit the user to decide what type of Container and what type of // Object inside the container is returned. VarList<T, FileNode> ret = listChoice.create(); // 'this' directory needs to be included (unless filtering directories) if (includeDirectoriesInResult && ((directoryFilter == null) || directoryFilter.test(this))) ret.insert(this); // Call the general-purpose flatten method. flattenINTERNAL( this, ret, fileFilter, includeFilesInResult, directoryFilter, includeDirectoriesInResult, 0, maxTreeDepth ); // retrieve the Container specified by the user. return ret.retrieve();
-
prune
public FileNode prune(FileNodeFilter fileFilter, boolean nullThePointers)
- Code:
- Exact Method Body:
this.pruneTree(fileFilter, nullThePointers); return this;
-
pruneTree
public int pruneTree(FileNodeFilter fileFilter, boolean nullThePointers)
This removes instances ofFileNode
that meet these conditions:- Are file instances, not directories. Specifically:
public final boolean isDirectory == false;
- Do not pass the
'fileFilter.test(...)'
method. If the test method returns FALSE, the file shall be removed from the containing directory'sprivate final Vector<FileNode> children
file-list.
RECURSION: This method shall skip through, 'traverse', the entireFileNode
tree and prune all 'file-leaves' that do not meet the criteria specified by the'fileFilter'
parameter.- Parameters:
fileFilter
- This is the test used to filter out files from the directory-tree that begins at'this'
instance. Returning FALSE shall eliminate the file from its containing parent, and when this filter returns TRUE that file shall remain.nullThePointers
- The primary use of this boolean is to remind users that this data-structureclass FileNode
is actually a tree that maintains pointers in both directions - upwards and downwards. Generally, trees have the potential to make programming an order of magnitude more complicated. Fortunately, because this data-structure merely represents the file-system, and because the data-structure itself (READ:'this'
tree) does not have much use for being modified itself... The fact thatFileNode
is a two-way, bi-directional tree rarely seems important. The most useful methods are those that "flatten" the tree, and then process the data in the files listed.
POINT: When this parameter is set to TRUE, all parent pointers shall be nulled, and this can make garbage-collection easier.- Returns:
- The number of files that were removed.
- Throws:
DirExpectedException
- If'this'
instance ofFileNode
does not represent a 'directory' on the file-system, then this exception shall throw.- See Also:
prune(FileNodeFilter, boolean)
,isDirectory
,parent
- Code:
- Exact Method Body:
DirExpectedException.check(this); Iterator<FileNode> iter = this.children.iterator(); int removeCount = 0; while (iter.hasNext()) { FileNode fn = iter.next(); /* DEBUGGING, KEEP HERE. System.out.print ("Testing: fn.name: " + fn.name + "\tfn.getParentDir().name: " + fn.getParentDir().name); */ if (! fn.isDirectory) // NOTE: This only filters 'files' (leaf-nodes) out of the tree. This 'tree-prune' // operation does not have any bearing on 'directory-nodes' (branch-nodes) in the tree. if (! fileFilter.test(fn)) { // These types of lines can help the Java Garbage-Collector. // They also prevent the user from ever utilizing this object reference again. if (nullThePointers) fn.parent = null; // System.out.println("\tRemoving..."); // This iterator is one generated by class 'Vector<FileNode>', and its remove() // operation, therefore, is fully-supported. This removes FileNode fn from 'this' // private, final field 'private Vector<FileNode> children' iter.remove(); removeCount++; continue; } // Keep Here, for Testing // System.out.println("\tKeeping..."); if (fn.isDirectory) removeCount += fn.pruneTree(fileFilter, nullThePointers); } return removeCount;
- Are file instances, not directories. Specifically:
-
getParentDir
public FileNode getParentDir()
Returns the parent of'this' FileNode
- Returns:
this.parent
NOTE If this is a "root node" or "root directory" then null will be returned here.- See Also:
parent
- Code:
- Exact Method Body:
return parent;
-
move
public void move(FileNode destinationDir)
Move's a file or directory from "inside" or "within" the contents of the current/parent directory, and into a new/destination/parent directory. If thedestinationDir
is not actually a directory, then an exception is thrown. If this is already a child/member of thedestinationDir
, then an exception is also thrown.
NOTE: This method does not modify the underlying UNIX or MS-DOS file-system - just theFileNode
Tree representation in Java Memory! (No UNIX, Apple, MS-DOS, etc. files are actually moved by this method)- Parameters:
destinationDir
- the destination directory- Throws:
java.util.InputMismatchException
DirExpectedException
- If'destinationDir'
is not a directory, but a file, then this exception is thrown. (Files may not contain child-nodes, only directories)- See Also:
parent
,name
,children
- Code:
- Exact Method Body:
DirExpectedException.check(destinationDir); if (this.parent == destinationDir) throw new java.util.InputMismatchException( "[" + name + "] - is already a member of the target directory " + "[" + destinationDir.name + "]" ); parent = destinationDir; destinationDir.children.addElement(this);
-
del
public void del()
This deletes a file from theFileNode
tree. It's only operation is to remove'this'
from the parent-node'sVector<FileNode> children
node-list! For Java garbage collection purposes, it also empties (callschildren.removeAllElements()
) on the childrenVector
- if there is one (a.k.a) if'this' FileNode
represents a directory, not a file!
NOTE: This method does not modify the underlying UNIX or MS-DOS file-system - just theFileNode
-Tree representation in Java Memory! (No UNIX, Apple, MS-DOS, etc. files are actually deleted by this method)- See Also:
parent
,children
,isDirectory
- Code:
- Exact Method Body:
parent.children.removeElement(this); if (isDirectory) children.removeAllElements(); parent = null;
-
getFullPathName
public java.lang.String getFullPathName()
This visits the'.name'
field for'this' FileNode
, as well as all parent instances of'this' FileNode
, and concatenates thoseString's
.- Returns:
- the full, available path name for
'this' FileNode
as aString
- See Also:
parent
,isDirectory
,name
,getFullPathName()
- Code:
- Exact Method Body:
if (parent == null) // This is tested in this class constructor, If this is TRUE, isDirectory must be true // RECENT ISSUE: May, 2022 - Google Cloud Shell Root Directory. return name.equals(File.separator) ? name : name + (isDirectory ? File.separatorChar : ""); // All other nodes where 'isDirectory' is TRUE // must have the file.separator appended else return parent.getFullPathName() + name + (isDirectory ? File.separatorChar : "");
-
getParentPathName
public java.lang.String getParentPathName()
Returns the as much of the "Full Path Name" of the file referenced by'this'
filename as is possible for this particularFileNode
.
NOTE: If this file or directory does not have a parent, then the empty (zero-length)String
will be returned. Usually, unless certain tree modification operations have been performed, only a root-nodeFileNode
will have a 'null' parent.- Returns:
- the full, available path name to
'this' FileNode
- leaving out the actual name of this file.
SPECIFICALLY:- for a file such as
'directory-1/subdirectory-2/filename.txt'
'directory-1/subdirectory-2/'
would be returned
- for a file such as
- See Also:
parent
,getFullPathName()
- Code:
- Exact Method Body:
if (parent == null) return ""; else return parent.getFullPathName();
-
getJavaIOFile
public java.io.File getJavaIOFile()
Gets thejava.io.File
version of a file. The java class for files has quite a bit of interactive stuff for a file system - including checking for'r/w/x'
permissions. This can be useful.- Returns:
- Gets the
java.io.File
instance of'this' FileNode
- See Also:
getFullPathName()
- Code:
- Exact Method Body:
return new File(getFullPathName());
-
apply
public boolean apply (java.util.function.BiFunction<FileNode,java.lang.String,java.lang.String> f, IOExceptionHandler ioeh)
This presumes that'this'
instance ofFileNode
is not a directory, but rather a file. If it is not a file, then an exception shall throw. This method also requires that'this'
file represents a text-file that may be loaded into aString
.
This method will load the contents of'this'
file into ajava.lang.String
and then pass thatString
(along with'this' FileNode
to the method'apply(FileNode, String'
provided by theBiFunction<FileNode, String>
input-parameter'f'
.
This is the type of method that could easily be used in conjunction with Java'sjava.util.stream.Stream
A.P.I. If the'f'
parameter were to include a regular-expression for modifying the contents of a file, then by using Java-Streams a programmer could easily write a UNIX'SED'
or'AWK'
like script with just a couple lines of Java.
Presuming that an appropriate'myFunction'
were written, any one of the following invocations could perform a UNIX'SED'
or'AWK'
type of routine on a suite of text-files, instantly.Stream<FileNode>.forEach(fileNode -> fileNode.apply(myFunction, myIOEHandler));
Vector<FileNode>.forEach(fileNode -> fileNode.apply(myFunction, myIOEHandler));
Stream<FileNode>.map(fileNode -> fileNode.apply(...));
- Parameters:
f
- This is the javaFunctionalInterface 'BiFunction'
As afunctional-interface
, it has a method named'apply'
and this method'apply'
receives two parameters itself:- The first Parameter shall be
'this'
instance of'FileNode'
- The second Parameter shall be the file-contents on the file-system of
'this' FileNode
- passed as ajava.lang.String
.
EXPECTED RETURN: Thefunctional-interface
that is passed to parameter'f'
should provide a return-value that is a "new, updatedString
" that shall be used to "replace the file-contents" of this instance ofFileNode
.
WRITE-NOTICE: This operation will OVER-WRITE the current contents of a file on the file-system. Also, this operation treats the file as if it contained text. Data-Files containing binary-data may not be used with this method. This is the only method in class'FileNode'
that actually will modify the underlying file-system.- The first Parameter shall be
ioeh
- This is an instance offunctional-interface class 'IOExceptionHandler'
. It receives an instance of anIOException
, and the programmer may insert any type of code he wants to see happen when anIOException
is thrown. The 'added-value' of including this handler is that when batches ofapply's
are performed on aFileNode
-tree, one file causing an exception throw does not have to halt the entire batch-process.
NOTE: This parameter may be null, and if it is, it shall be ignored. It is only invoked if it is not null, and if an exception occurs when either reading or writing the file to/from the file-system.- Returns:
- This method returns TRUE if there were no I/O faults when either reading or writing the file.
- Throws:
FileExpectedException
- If'destinationDir'
is not a file, but a directory, then this exception is thrown.- See Also:
getFullPathName()
,FileRW.loadFileToString(String)
,FileRW.writeFile(CharSequence, String)
,IOExceptionHandler.accept(FileNode, IOException)
- Code:
- Exact Method Body:
// This method can only be used with 'file' FileNode's. // FileNode's that are 'directories' do not have "text-contents" or "file-contents" FileExpectedException.check(this); try { // Read 'this' file into a String String fileName = this.toString(); String fileContents = FileRW.loadFileToString(fileName); // Send the contents of 'this' file to the BiFunction parameter 'f' fileContents = f.apply(this, fileContents); // Re-write the new file back to the old location. FileRW.writeFile(fileContents, fileName); return true; } catch (IOException e) { // if an I/O exception did occur, send the information to the // I/O exception handler provided by the user (if and only if the // actually provided a non-null exception handler) if (ioeh != null) ioeh.accept(this, e); return false; }
-
accept
public void accept (java.util.function.BiConsumer<FileNode,java.lang.String> c, IOExceptionHandler ioeh)
This presumes that'this'
instance ofFileNode
is not a directory, but rather a file. If it is not a file, then an exception shall throw. This method also requires that'this'
file represents a text-file that may be loaded into aString
.
This method will load the contents of'this'
file into ajava.lang.String
and then pass thatString
(along with'this' FileNode
to the method'accept(FileNode, String'
provided by theBiConsumer<FileNode, String>
input-parameter'c'
.- Parameters:
c
- This is the javaFunctionalInterface 'BiConsumer'
. As afunctional-interface
, it has a method named'accept'
and this method'accept'
receives two parameters itself:- The first Parameter shall be
'this'
instance of'FileNode'
- The second Parameter shall be the file-contents on the file-system of
'this' FileNode
- passed as ajava.lang.String
.
- The first Parameter shall be
ioeh
- This an is instance ofFunctionalInterface 'IOExceptionHandler'
. It receives an instance of anIOException
, and the programmer may insert any type of code he wants to see happen when anIOException
is thrown. The 'added-value' of including this handler is that when batches ofaccept's
are performed one aFileNode
-tree, one file causing an exception throw does not have to halt the entire batch-process.
NOTE: This parameter may be null, and if it is, it shall be ignored. It is only invoked if it is not null, and if an exception occurs when either reading or writing the file to/from the file-system.- Throws:
FileExpectedException
- If'destinationDir'
is not a file, but a directory, then this exception is thrown.- See Also:
FileRW.loadFileToString(String)
,getFullPathName()
,IOExceptionHandler.accept(FileNode, IOException)
- Code:
- Exact Method Body:
// This method can only be used with 'file' FileNode's. // FileNode's that are 'directories' do not have "text-contents" or "file-contents" FileExpectedException.check(this); try { c.accept(this, FileRW.loadFileToString(getFullPathName())); } catch (IOException ioe) // if an I/O exception did occur, send the information to the // I/O exception handler provided by the user (if and only if the // actually provided a non-null exception handler) { if (ioeh != null) ioeh.accept(this, ioe); }
-
ask
public boolean ask (java.util.function.BiPredicate<FileNode,java.lang.String> p, IOExceptionHandler ioeh)
This presumes that'this'
instance ofFileNode
is not a directory, but rather a file. If it is not a file, then an exception shall throw. This method also requires that'this'
file represents a text-file that may be loaded into aString
.
This method will load the contents of'this'
file into ajava.lang.String
and then pass thatString
(along with'this' FileNode
to the method'ask(FileNode, String'
provided by theBiPredicate<FileNode, String>
input-parameter'p'
.
This is the type of method that could easily be used in conjunction with ajava.util.stream.Stream
or ajava.util.Vector
.Stream<FileNode>.filter(fileNode -> fileNode.ask(myFilterPred, myIOEHandler));
Vector<FileNode>.removeIf(fileNode -> fileNode.ask(myFilterPred, myIOEHandler));
- Parameters:
p
- This is the javaFunctionalInterface 'BiPredicate'
. As afunctional-interface
, it has a method named'test'
and this method'test'
receives two parameters itself:- The first parameter shall be
'this'
instance of'FileNode'
- The second parameter shall be the file-contents on the file-system of
'this' FileNode
- passed as ajava.lang.String
.
IMPORTANT: Thefunctional-interface
that is passed to parameter'p'
should provide a returnboolean
-value that is to act as a pass/fail filter criteria. It is important to note that the JavaVector
methodVector.removeIf(Predicate)
and the Java methodStream.filter(Predicate)
will produce exactly opposite outputs based on the same filter logic.
To explain further, whenVector.removeIf(Predicate)
is used, the predicate should return TRUE to indicate that theFileNode
needs to be eliminated not retained. WhenStream.filter(Predicate)
is used, TRUE should indicate that theFileNode
should be retained not eliminated.- The first parameter shall be
ioeh
- This is an instance of functional-interface class,IOExceptionHandler
. It receives an instance of anIOException
, and the programmer may insert any type of code he wants to see happen when anIOException
is thrown. The 'added-value' of including this handler is that when batches ofask's
are performed on aFileNode
-tree, one file causing an exception throw does not have to halt the entire batch-process.
NOTE: This parameter may be null, and if it is, it shall be ignored. It is only invoked if it is not null, and if an exception occurs when either reading or writing the file to/from the file-system.- Returns:
- This method returns TRUE if there were no I/O faults when either reading or writing the file.
- Throws:
FileExpectedException
- If'destinationDir'
is not a file, but a directory, then this exception is thrown.- See Also:
getFullPathName()
,FileRW.loadFileToString(String)
,IOExceptionHandler.accept(FileNode, IOException)
- Code:
- Exact Method Body:
// This method can only be used with 'file' FileNode's. // FileNode's that are 'directories' do not have "text-contents" or "file-contents" FileExpectedException.check(this); try { return p.test(this, FileRW.loadFileToString(getFullPathName())); } catch (IOException ioe) { if (ioeh != null) ioeh.accept(this, ioe); return false; }
-
NULL_THE_TREE
public void NULL_THE_TREE()
There are not any "Tree Structures" present in the HTML Search, Update, and Scrape Packages. In the Java Packages, theclass 'FileNode'
is the lone source of "Tree Structures." The Java Garbage Collector sometimes seems to work in mysterious ways. The external-library "Java-Parser" is a library that is only used for the Java-Doc Upgrader Tool. Java Parser is not present in anything related to HTML Search, Scrape or Update. The Garbage Collector has had some trouble clearing out the AST Trees that are generated by the Java-Parser import when using the Java-Doc Upgrader Tool. A Circular Tree is probably impossible to clean. The Garbage Collector for memory references has worked wonderfully well with 100% of vectorized-html pages that have been generated although not so much for the "Java Parser Bridge" routines.
This method will 'null-ify' all references (pointers) in a'FileNode'
-Tree. TheFileNode
-Tree can be a great asset or tool during the development process when looking through file-contents and trying to modify them - or just find files with certain characteristics.- See Also:
getDirContents()
,getDirContentsDirs()
,parent
,children
- Code:
- Exact Method Body:
Iterator<FileNode> iter = getDirContents(RetTypeChoice.ITERATOR); while (iter.hasNext()) iter.next().parent = null; iter = getDirContentsDirs(RetTypeChoice.ITERATOR); while (iter.hasNext()) iter.next().NULL_THE_TREE(); children.clear();
-
-