net.lucidviews.util.io
Class Files

java.lang.Object
  net.lucidviews.util.io.Streams
      net.lucidviews.util.io.Files

public class Files
extends Streams

A collection of methods for manipualting Files.

Since:

1.0

Version:

$Revision: 1.6.2.2 $

Author:

Stephen Battey

Nested Class Summary

static class

Files.NewFileNameModel Helper class that creates a new file name based on some rules/configuration.

Field Summary

private static String

DEFAULT_PATH_SEPARATOR The character used to separate folder paths in the classpath.

Fields inherited from class net.lucidviews.util.io.Streams

DEFAULT_BUFFER_SIZE

Constructor Summary

protected

Files() Suppresses default constructor, ensuring non-instantiability.

Method Summary

static File	copyFile(File original, File destination) Copy a file to a given folder or file location.
static File	copyFile(File original, File destination, int bufferSize) Copy a file to a given folder or file location.
static File	copyFile(File original, File destinationFolder, String fileName) Copy a file to a folder, giving the copy a new name.
static File	copyFile(File original, File destinationFolder, String fileName, int bufferSize) Copy a file to a folder, giving the copy a new name.
static boolean	copyFolder(File original, File destination) Copy a folder, and all its contents, to another location.
static boolean	copyFolder(File original, File destination, FileFilter filter) Copy a folder, and all its contents, to another location.
static boolean	copyFolder(File original, File destination, FilenameFilter filter) Copy a folder, and all its contents, to another location.
static boolean	copyFolderContents(File original, File destination) Copy the contents of a folder to another location.
static boolean	copyFolderContents(File original, File destination, FileFilter filter) Copy the contents of a folder to another location.
static boolean	copyFolderContents(File original, File destination, FilenameFilter filter) Copy the contents of a folder to another location.
static File	createNewFile(File folder, String preferredFileName) Create a new, blank file in the given folder.
static File	createNewFile(String fileName, File folder) Create a new, blank file with a given name.
static List	createPatch(File currentFolder, boolean recursive, File oldFolder, File destFolder) Create a patch for an old set of files.
static List	createPatch(File currentFolder, boolean recursive, File oldFolder, File destFolder, boolean patchModifiedFiles) Create a patch for an old set of files.
static List<File>	createPatch(File currentFolder, boolean recursive, File oldFolder, File destFolder, boolean patchModifiedFiles, Comparator<File> fileComparator) Create a patch for an old set of files.
static List	createPatch(File currentFolder, File oldFolder, File destFolder) Create a patch for an old set of files.
static List	createPatch(File currentFolder, File oldFolder, File destFolder, boolean patchModifiedFiles) Create a patch for an old set of files.
static boolean	deleteFolder(File folder) Delete a folder and all files and sub-folders.
static File	deriveRootFolder(File file) Recurse down to find the root of a file path.
static File	findFile(String fileName) Find a file with the given name, located somewhere on the classpath.
static File	getExistingParentFile(File file) Get the existing parent (folder) for the given file.
static boolean	isDescendant(File folder, File suspectedChild) Checks if the suspectedChild file (or folder) is contained within the specified folder or one of its sub-folders.
static boolean	isDuplicate(File file, File compare) Checks if one file is a duplicate of another.
static List	listFiles(File folder, Comparator<File> comparator) Get a sorted list of files for a given directory.
static List	listFiles(File folder, FileFilter filter, Comparator<File> comparator) Get a filtered, sorted list of files for a given directory.
static List	listFiles(File folder, FilenameFilter filter, Comparator<File> comparator) Get a filtered, sorted list of files for a given directory.
static List	sortFiles(File[] files, Comparator<File> comparator) Convert an array of Files to a sorted List.

Methods inherited from class net.lucidviews.util.io.Streams

close, close, compare, compare, pipe, pipe

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_PATH_SEPARATOR

private static final String DEFAULT_PATH_SEPARATOR

The character used to separate folder paths in the classpath.

See Also:

Constant Field Values

Constructor Detail

Files

protected Files()

Suppresses default constructor, ensuring non-instantiability.

Method Detail

getExistingParentFile

public static File getExistingParentFile(File file)

Get the existing parent (folder) for the given file.
If no parent or grandparent exist for the given file path, then a null value is returned.

Parameters:

file - the file

Returns:

the first parent or grandparent (folder) that is found to exist

Since:

1.3

deriveRootFolder

public static File deriveRootFolder(File file)

Recurse down to find the root of a file path.

Parameters:

file - a File

Returns:

a File reference to the root folder

Since:

1.3

findFile

public static File findFile(String fileName)
                     throws FileNotFoundException

Find a file with the given name, located somewhere on the classpath.
Each folder defined on the Java classpath will be searched. If the file does not exist in any of those folders an exception will be thrown.

Parameters:

fileName - the name of the file

Returns:

a File with the given name, located somewhere on the classpath, the object is guaranteed to be non-null and the file is guaranteed to exist

Throws:

FileNotFoundException - if the file could not be found on the classpath

isDuplicate

public static boolean isDuplicate(File file,
                                  File compare)
                           throws IOException

Checks if one file is a duplicate of another.

Parameters:

file - file to test

compare - second file to compare the file to

Returns:

true if the two files are the same

Throws:

IOException - error reading content of the two files being compared

isDescendant

public static boolean isDescendant(File folder,
                                   File suspectedChild)

Checks if the suspectedChild file (or folder) is contained within the specified folder or one of its sub-folders.
NB: this methods explicitly checks for descendants - if the two files are the same then this method returns false (not a descendant).

Parameters:

folder - the folder that could be the parent or grand-parent

suspectedChild - the file or folder that is suspected to be a descendant

Returns:

boolean true if the suspectedChild is a descendant of the folder

createNewFile

public static File createNewFile(File folder,
                                 String preferredFileName)
                          throws IOException

Create a new, blank file in the given folder.
The file created is guaranteed not to overwrite any existing file and be located in the specified folder. The file will have a name based on the preferredFileName. If a file with the preferred name already exists then a numeric suffix will be added (e.g. ./filename_2.dat).

Parameters:

folder - the directory where the new file is to be created

preferredFileName - the desired name of the file

Returns:

a File reference to a new file in the given folder

Throws:

IOException - error creating the new file

SecurityException - access to write the file was denied by the system security manager

createNewFile

public static File createNewFile(String fileName,
                                 File folder)
                          throws IOException

Create a new, blank file with a given name.
The file created is guaranteed not to overwrite any existing file and have the specified fileName. The file will be placed within folder, either directly in that folder or in a sub-folder. If a file with the preferred name already exists then a sub-folder will be created with a numeric suffix (e.g. ./filename_2/filename_2.dat).

Parameters:

fileName - the name of the new file

folder - the desired directory where the new file is to be created

Returns:

a File reference to a new file in the given folder

Throws:

IOException - error creating the new file

SecurityException - access to write the file was denied by the system security manager

sortFiles

public static List sortFiles(File[] files,
                             Comparator<File> comparator)

Convert an array of Files to a sorted List.
The files are ordered using a Comparator.

Parameters:

files - an array of File

comparator - the Comparator used to sort the files

Returns:

a List of sorted Files

Throws:

ClassCastException - the specified comparator was not compatible with File objects

UnsupportedOperationException - the generated List did not support a sort operation

See Also:

FileComparator

listFiles

public static List listFiles(File folder,
                             Comparator<File> comparator)

Get a sorted list of files for a given directory.
The list returned will contain all files in the specified folder and will be sorted in the order defined by the comparator.

Parameters:

folder - the folder whose contents are to be listed

comparator - a Comparator that will sort the files

Returns:

a sorted List of Files

Throws:

SecurityException - read access to the folder was denied

ClassCastException - the specified comparator was not compatible with File objects

UnsupportedOperationException - the generated List did not support a sort operation

See Also:

FileComparator

listFiles

public static List listFiles(File folder,
                             FilenameFilter filter,
                             Comparator<File> comparator)

Get a filtered, sorted list of files for a given directory.
The list returned will contain files in the specified folder which are accepted by the filter, and are sorted in the order defined by the comparator.

Parameters:

folder - the folder whose contents are to be listed

filter - a filter that determines which files are added to the list

comparator - a Comparator that will sort the files

Returns:

a sorted List of Files

Throws:

SecurityException - read access to the folder was denied

ClassCastException - the specified comparator was not compatible with File objects

UnsupportedOperationException - the generated List did not support a sort operation

See Also:

FilenameFilter, FileComparator

listFiles

public static List listFiles(File folder,
                             FileFilter filter,
                             Comparator<File> comparator)

Get a filtered, sorted list of files for a given directory.
The list returned will contain files in the specified folder which are accepted by the filter, and are sorted in the order defined by the comparator.

Parameters:

folder - the folder whose contents are to be listed

filter - a filter that determines which files are added to the list

comparator - a Comparator that will sort the files

Returns:

a sorted List of Files

Throws:

SecurityException - read access to the folder was denied

ClassCastException - the specified comparator was not compatible with File objects

UnsupportedOperationException - the generated List did not support a sort operation

See Also:

FileFilter, FileComparator

copyFile

public static File copyFile(File original,
                            File destination,
                            int bufferSize)
                     throws IOException

Copy a file to a given folder or file location.
The destination File can reference either a directory or a file. In the case of a directory, a copy of the original file will be placed in this directory with the same name. If a file is specified, the destination file will be overwritten with the file at the original location.

Parameters:

original - the file to be copied

destination - the destination of the copy - either a file or a directory

bufferSize - the size of the buffer to use when copying the data

Returns:

the new copy of the original file

Throws:

SecurityException - error creating a new file

IOException - error copying the content of the file

copyFile

public static File copyFile(File original,
                            File destination)
                     throws IOException

Copy a file to a given folder or file location.
The destination File can reference either a directory or a file. In the case of a directory, a copy of the original file will be placed in this directory with the same name. If a file is specified, the destination file will be overwritten with the file at the original location.

Parameters:

original - the file to be copied

destination - the destination of the copy - either a file or a directory

Returns:

the new copy of the original file

Throws:

SecurityException - error creating a new file

IOException - error copying the content of the file

copyFile

public static File copyFile(File original,
                            File destinationFolder,
                            String fileName,
                            int bufferSize)
                     throws IOException

Copy a file to a folder, giving the copy a new name.
If a file already exists at the new location, it will be overwritten.

Parameters:

original - the file to be copied

destinationFolder - the folder where the file is to be copied to

fileName - the name of the new copy

bufferSize - the size of the buffer to use when copying the data

Returns:

the new copy of the original file

Throws:

SecurityException - error creating a new file

IOException - error copying the content of the file

copyFile

public static File copyFile(File original,
                            File destinationFolder,
                            String fileName)
                     throws IOException

Copy a file to a folder, giving the copy a new name.
If a file already exists at the new location, it will be overwritten.

Parameters:

original - the file to be copied

destinationFolder - the folder where the file is to be copied to

fileName - the name of the new copy

Returns:

the new copy of the original file

Throws:

SecurityException - error creating a new file

IOException - error copying the content of the file

copyFolder

public static boolean copyFolder(File original,
                                 File destination,
                                 FilenameFilter filter)

Copy a folder, and all its contents, to another location.
If the destination folder already contains a folder with the same name as the original then the contents of the original folder will be merged into that folder, overwriting any writable files already in the destination (read-only files will not be overwritten, but will cause this copy to be incomplete, acknowledged by a false return value).
This copy method will recurse through all sub-folders of the original folder. If one file or folder cannot be copied the routine will continue copying the remaining contents.
This method returns true if all files and sub-folders were successfully copied. This method returns false if any file or folder could not be deleted.
I.e.
• A return value of true indicates the destination folder will be an exact copy of the original. • A return value of false indicates the destination folder may not exist. • In the case of a security exception, there is no guarantee as to which files have been copied, including the root folder.

Parameters:

original - the folder to be copied

destination - the folder where the original folder is to be copied to

filter - a filter used to choose which files to copy

Returns:

true if the folder and its contents were copied successfully, false otherwise

copyFolder

public static boolean copyFolder(File original,
                                 File destination,
                                 FileFilter filter)

Copy a folder, and all its contents, to another location.
If the destination folder already contains a folder with the same name as the original then the contents of the original folder will be merged into that folder, overwriting any writable files already in the destination (read-only files will not be overwritten, but will cause this copy to be incomplete, acknowledged by a false return value).
This copy method will recurse through all sub-folders of the original folder. If one file or folder cannot be copied the routine will continue copying the remaining contents.
This method returns true if all files and sub-folders were successfully copied. This method returns false if any file or folder could not be deleted.
I.e.
• A return value of true indicates the destination folder will be an exact copy of the original. • A return value of false indicates the destination folder may not exist. • In the case of a security exception, there is no guarantee as to which files have been copied, including the root folder.

Parameters:

original - the folder to be copied

destination - the folder where the original folder is to be copied to

filter - a filter used to choose which files to copy

Returns:

true if the folder and its contents were copied successfully, false otherwise

copyFolder

public static boolean copyFolder(File original,
                                 File destination)

Copy a folder, and all its contents, to another location.
If the destination folder already contains a folder with the same name as the original then the contents of the original folder will be merged into that folder, overwriting any writable files already in the destination (read-only files will not be overwritten, but will cause this copy to be incomplete, acknowledged by a false return value).
This copy method will recurse through all sub-folders of the original folder. If one file or folder cannot be copied the routine will continue copying the remaining contents.
This method returns true if all files and sub-folders were successfully copied. This method returns false if any file or folder could not be deleted.
I.e.
• A return value of true indicates the destination folder will be an exact copy of the original. • A return value of false indicates the destination folder may not exist. • In the case of a security exception, there is no guarantee as to which files have been copied, including the root folder.

Parameters:

original - the folder to be copied

destination - the folder where the original folder is to be copied to

Returns:

true if the folder and its contents were copied successfully, false otherwise

copyFolderContents

public static boolean copyFolderContents(File original,
                                         File destination,
                                         FilenameFilter filter)

Copy the contents of a folder to another location.
The contents of the original folder will overwrite any writable files already in the destination (read-only files will not be overwritten, but will cause this copy to be incomplete, acknowledged by a false return value).
This copy method will recurse through all sub-folders of the original folder. If one file or folder cannot be copied the routine will continue copying the remaining contents.
This method returns true if all files and sub-folders were successfully copied. This method returns false if any file or folder could not be deleted.
I.e.
• A return value of true indicates the destination folder will contain all the files and folder in the original. • A return value of false indicates the destination folder may not contain any of the files or folders from the original. • In the case of a security exception, there is no guarantee as to which files have been copied.

Parameters:

original - the folder whose content is to be copied

destination - the folder where the content is to be copied to

filter - a filter used to choose which files to copy

Returns:

true if the contents were copied successfully, false otherwise

copyFolderContents

public static boolean copyFolderContents(File original,
                                         File destination,
                                         FileFilter filter)

Copy the contents of a folder to another location.
The contents of the original folder will overwrite any writable files already in the destination (read-only files will not be overwritten, but will cause this copy to be incomplete, acknowledged by a false return value).
This copy method will recurse through all sub-folders of the original folder. If one file or folder cannot be copied the routine will continue copying the remaining contents.
This method returns true if all files and sub-folders were successfully copied. This method returns false if any file or folder could not be deleted.
I.e.
• A return value of true indicates the destination folder will contain all the files and folder in the original. • A return value of false indicates the destination folder may not contain any of the files or folders from the original. • In the case of a security exception, there is no guarantee as to which files have been copied.

Parameters:

original - the folder whose content is to be copied

destination - the folder where the content is to be copied to

filter - a filter used to choose which files to copy

Returns:

true if the contents were copied successfully, false otherwise

copyFolderContents

public static boolean copyFolderContents(File original,
                                         File destination)

Copy the contents of a folder to another location.
The contents of the original folder will overwrite any writable files already in the destination (read-only files will not be overwritten, but will cause this copy to be incomplete, acknowledged by a false return value).
This copy method will recurse through all sub-folders of the original folder. If one file or folder cannot be copied the routine will continue copying the remaining contents.
This method returns true if all files and sub-folders were successfully copied. This method returns false if any file or folder could not be deleted.
I.e.
• A return value of true indicates the destination folder will contain all the files and folder in the original. • A return value of false indicates the destination folder may not contain any of the files or folders from the original. • In the case of a security exception, there is no guarantee as to which files have been copied.

Parameters:

original - the folder whose content is to be copied

destination - the folder where the content is to be copied to

Returns:

true if the contents were copied successfully, false otherwise

deleteFolder

public static boolean deleteFolder(File folder)

Delete a folder and all files and sub-folders.
This method returns true if all files and sub-folders were successfully deleted. This method returns false if any file or folder could not be deleted.
I.e.
• A return value of true indicates the folder will no longer exist. • A return value of false indicates the folder will still exist, however there is no guarantee that any of its files or sub-folders will still exist. • In the case of a security exception, there is no guarantee as to which files have been deleted, including the specified folder.

Parameters:

folder - the folder to be deleted

Returns:

boolean value indicating whether the delete was totally successful

Throws:

SecurityException - delete access to the folder was denied by the security manager

createPatch

public static List createPatch(File currentFolder,
                               File oldFolder,
                               File destFolder)

Create a patch for an old set of files.
This method will compare the content of two folders and deduce which files in the 'current' set of files need to be copied into the 'old' set of files in order to bring the old set of files up-to-date.
No changes will be made to the old set of files, i.e. this method does not perform a patch, it creates a patch by copying the new or modified files into a blank 'destination' folder. The patch is created in such a way that copying the 'destination' folder over the 'old' folder will patch the old set of files and bring them up-to-date with the 'current' set of files.

This method will automatically recurse into sub folders and include modified files in the patch. (The definition of 'modified' being those files whose timestamp is more recent than the old copy of the file).

This method does not throw an I/O exception. If a file cannot be copied for any reason it will be added to a list of failed files. The process then continues until all files have been checked. The list of failed files is then returned. You should check the list is empty to ensure the patch has completed successfully.

Parameters:

currentFolder - the root folder containing the current set of files (latest version)

oldFolder - the root folder containing the old set of files

destFolder - the folder where the patch is to be created (this folder need not exist, it will automatically be created) it is recommended the folder either does not exist or is empty before this method is called

Returns:

a List of File references to files in the 'current' folder that could not be copied/included in the patch due to an I/O exception - the value is never null - always check the list is empty to ensure the patch was complete

createPatch

public static List createPatch(File currentFolder,
                               File oldFolder,
                               File destFolder,
                               boolean patchModifiedFiles)

Create a patch for an old set of files.
This method will compare the content of two folders and deduce which files in the 'current' set of files need to be copied into the 'old' set of files in order to bring the old set of files up-to-date.
No changes will be made to the old set of files, i.e. this method does not perform a patch, it creates a patch by copying the new or modified files into a blank 'destination' folder. The patch is created in such a way that copying the 'destination' folder over the 'old' folder will patch the old set of files and bring them up-to-date with the 'current' set of files.

This method will automatically recurse into sub folders. It will only include modified files in the patch if instructed to, by setting the patchModifiedFiles parameter to true. (The definition of 'modified' being those files whose timestamp is more recent than the old copy of the file).

This method does not throw an I/O exception. If a file cannot be copied for any reason it will be added to a list of failed files. The process then continues until all files have been checked. The list of failed files is then returned. You should check the list is empty to ensure the patch has completed successfully.

Parameters:

currentFolder - the root folder containing the current set of files (latest version)

oldFolder - the root folder containing the old set of files

destFolder - the folder where the patch is to be created (this folder need not exist, it will automatically be created) it is recommended the folder either does not exist or is empty before this method is called

patchModifiedFiles - indicates if modified files should be included in the patch

Returns:

a List of File references to files in the 'current' folder that could not be copied/included in the patch due to an I/O exception - the value is never null - always check the list is empty to ensure the patch was complete

createPatch

public static List createPatch(File currentFolder,
                               boolean recursive,
                               File oldFolder,
                               File destFolder)

Create a patch for an old set of files.
This method will compare the content of two folders and deduce which files in the 'current' set of files need to be copied into the 'old' set of files in order to bring the old set of files up-to-date.
No changes will be made to the old set of files, i.e. this method does not perform a patch, it creates a patch by copying the new or modified files into a blank 'destination' folder. The patch is created in such a way that copying the 'destination' folder over the 'old' folder will patch the old set of files and bring them up-to-date with the 'current' set of files.

This method will only recurse into sub folders if instructed to, by setting the recursive parameter to true. It will automatically include modified files in the patch. (The definition of 'modified' being those files whose timestamp is more recent than the old copy of the file).

This method does not throw an I/O exception. If a file cannot be copied for any reason it will be added to a list of failed files. The process then continues until all files have been checked. The list of failed files is then returned. You should check the list is empty to ensure the patch has completed successfully.

Parameters:

currentFolder - the root folder containing the current set of files (latest version)

recursive - indicates if the patch should include sub-folders

oldFolder - the root folder containing the old set of files

destFolder - the folder where the patch is to be created (this folder need not exist, it will automatically be created) it is recommended the folder either does not exist or is empty before this method is called

Returns:

a List of File references to files in the 'current' folder that could not be copied/included in the patch due to an I/O exception - the value is never null - always check the list is empty to ensure the patch was complete

createPatch

public static List createPatch(File currentFolder,
                               boolean recursive,
                               File oldFolder,
                               File destFolder,
                               boolean patchModifiedFiles)

Create a patch for an old set of files.
This method will compare the content of two folders and deduce which files in the 'current' set of files need to be copied into the 'old' set of files in order to bring the old set of files up-to-date.
No changes will be made to the old set of files, i.e. this method does not perform a patch, it creates a patch by copying the new or modified files into a blank 'destination' folder. The patch is created in such a way that copying the 'destination' folder over the 'old' folder will patch the old set of files and bring them up-to-date with the 'current' set of files.

This method will only recurse into sub folders if instructed to, by setting the recursive parameter to true. It will only include modified files in the patch if instructed to, by setting the patchModifiedFiles parameter to true. (The definition of 'modified' being those files whose timestamp is more recent than the old copy of the file).

This method does not throw an I/O exception. If a file cannot be copied for any reason it will be added to a list of failed files. The process then continues until all files have been checked. The list of failed files is then returned. You should check the list is empty to ensure the patch has completed successfully.

Parameters:

currentFolder - the root folder containing the current set of files (latest version)

recursive - indicates if the patch should include sub-folders

oldFolder - the root folder containing the old set of files

destFolder - the folder where the patch is to be created (this folder need not exist, it will automatically be created) it is recommended the folder either does not exist or is empty before this method is called

patchModifiedFiles - indicates if modified files should be included in the patch

Returns:

a List of File references to files in the 'current' folder that could not be copied/included in the patch due to an I/O exception - the value is never null - always check the list is empty to ensure the patch was complete

createPatch

public static List<File> createPatch(File currentFolder,
                                     boolean recursive,
                                     File oldFolder,
                                     File destFolder,
                                     boolean patchModifiedFiles,
                                     Comparator<File> fileComparator)

Create a patch for an old set of files.
This method will compare the content of two folders and deduce which files in the 'current' set of files need to be copied into the 'old' set of files in order to bring the old set of files up-to-date.
No changes will be made to the old set of files, i.e. this method does not perform a patch, it creates a patch by copying the new or modified files into a blank 'destination' folder. The patch is created in such a way that copying the 'destination' folder over the 'old' folder will patch the old set of files and bring them up-to-date with the 'current' set of files.

This method will only recurse into sub folders if instructed to, by setting the recursive parameter to true. It will only include modified files in the patch if instructed to, by setting the patchModifiedFiles parameter to true.
Whether a file has been modified is determined by the fileComparator. If the fileComparator concludes the current file is 'greater' than the old file, then the file is considered more recent and therefore needs replacing.

This method does not throw an I/O exception. If a file cannot be copied for any reason it will be added to a list of failed files. The process then continues until all files have been checked. The list of failed files is then returned. You should check the list is empty to ensure the patch has completed successfully.

Parameters:

currentFolder - the root folder containing the current set of files (latest version)

recursive - indicates if the patch should include sub-folders

oldFolder - the root folder containing the old set of files

destFolder - the folder where the patch is to be created (this folder need not exist, it will automatically be created) it is recommended the folder either does not exist or is empty before this method is called

patchModifiedFiles - indicates if modified files should be included in the patch

fileComparator - the comparator used to determine which file is more recent and therefore if it needs to be patched

Returns:

a List of File references to files in the 'current' folder that could not be copied/included in the patch due to an I/O exception - the value is never null - always check the list is empty to ensure the patch was complete