com.softnetConsult.utils.files
Class FileTools

java.lang.Object
  com.softnetConsult.utils.files.FileTools

public final class FileTools
extends java.lang.Object

This is a collection of static utility methods for dealing with files and parths.

This product includes software developed by the SoftNet-Consult Java Utility Library project and its contributors.
(http://java-tools.sourceforge.net)
Copyright (c) 2007-2008 SoftNet-Consult.
Copyright (c) 2007-2008 G. Paperin.
All rights reserved.

File: FileTools.java
Library API version: "2.02"
Java compliance version: "1.5"

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following terms and conditions are met:

1. Redistributions of source code must retain the above acknowledgement of the SoftNet-Consult Java Utility Library project, the above copyright notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above acknowledgement of the SoftNet-Consult Java Utility Library project, the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
3. All advertising materials mentioning features or use of this software or any derived software must display the following acknowledgement:
This product includes software developed by the SoftNet-Consult Java Utility Library project and its contributors.

THIS SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS, CONTRIBUTORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Version:

"2.02"

Author:

Greg Paperin (http://www.paperin.org)

Field Summary

static java.lang.String	FILE_EXTENSION_SEPARATOR
static java.lang.String	FILE_NAME_UNIQUE_MAKER_TAG

Constructor Summary

private

FileTools() Prevents instances of this class from being created as this class contains only static utility methods.

Method Summary

static java.lang.String	concatDirFile(java.lang.String dirName, java.lang.String fileName) Concatenates a directory name and a file name to build a path by inserting a file separator ('/' or '\\') between them if necessary. For example all of the following calls will produce the same result: - concatDirFile("dir/subdir", "file.name") - concatDirFile("dir/subdir/", "file.name") - concatDirFile("dir/subdir", "/file.name") - concatDirFile("dir/subdir/", "/file.name") RESULT: "dir/subdir/file.name" Note that '/' is used in the example, but '\\' is equally supported.
static java.lang.String	concatFileExt(java.lang.String fileBaseName, java.lang.String fileExt) Concatenates a file base nameand a file extension to build a full file name by inserting a file extension separator ('.') between them if necessary. For example all of the following calls will produce the same result: - concatDirFile("basename", "ext") - concatDirFile("basename.", "ext") - concatDirFile("basename", ".ext") - concatDirFile("basename.", ".ext") RESULT: "basename.ext"
static boolean	deleteAllRecursively(java.io.File file) Deletes the specified file; if the file specifies a directory all contained files and subdirectories are also deleted recursively.
static boolean	deleteAllRecursively(java.io.File file, java.util.List<java.io.File> deleted, java.util.List<java.io.File> failed) Deletes the specified file; if the file specifies a directory all contained files and subdirectories are also deleted recursively.
static boolean	deleteAllRecursively(java.lang.String path) Deletes the specified file; if the path specifies a directory all contained files and subdirectories are also deleted recursively.
static boolean	deleteAllRecursively(java.lang.String path, java.util.List<java.io.File> deleted, java.util.List<java.io.File> failed) Deletes the specified file; if the path specifies a directory all contained files and subdirectories are also deleted recursively.
static boolean	deleteRecursively(java.io.File file) Deletes the specified file, if the file specifies a directory all contained files and subdirectories are also deleted recursively.
static boolean	deleteRecursively(java.lang.String path) Deletes the specified file, if the file specifies a directory all contained files and subdirectories are also deleted recursively.
static java.io.File	findUniqueFile(java.lang.String fileName, java.lang.String fileExt, boolean alwaysUseTimestamp) Creates a File object describing a file with the specified base name and extension as well as an optional timestamp and an optional counter to make the file name unique; the program start directory is used for the path. This methos works generally in the same way as findUniqueFileName(String, String, String, boolean) and is equivalent to findUniqueFile(System.getProperty("user.dir"), fileName, fileExt, alwaysUseTimestamp).
static java.io.File	findUniqueFile(java.lang.String fileDir, java.lang.String fileName, java.lang.String fileExt, boolean alwaysUseTimestamp) Creates a File object describing a file with the specified base name, extension and directory as well as an optional timestamp and an optional counter to make the file name unique.
static java.lang.String	findUniqueFileName(java.lang.String fileName, java.lang.String fileExt, boolean alwaysUseTimestamp) Creates an absolute file name describing a file with the specified base name and extension as well as an optional timestamp and an optional counter to make the file name unique; the program start directory is used for the path. This methos works generally in the same way as findUniqueFileName(String, String, String, boolean) and is equivalent to findUniqueFile(fileName, fileExt, alwaysUseTimestamp).getAbsolutePath().
static java.lang.String	findUniqueFileName(java.lang.String fileDir, java.lang.String fileName, java.lang.String fileExt, boolean alwaysUseTimestamp) Creates an absolute file name describing a file with the specified base name, extension and directory as well as an optional timestamp and an optional counter to make the file name unique. This methos works generally in the same way as findUniqueFileName(String, String, String, boolean) and is equivalent to findUniqueFile(fileDir, fileName, fileExt, alwaysUseTimestamp).getAbsolutePath().
static java.lang.String	getBaseName(java.io.File file) Gets the base name of the specified name.
static java.lang.String	getBaseName(java.lang.String fileName) Gets the base name of the specified file name.
static java.lang.String	getExtension(java.io.File file) Gets the extension of the specified file including the extension delimeter (".").
static java.lang.String	getExtension(java.io.File file, boolean includeExtSep) Gets the extension of the specified file.
static java.lang.String	getExtension(java.lang.String fileName) Gets the extension of the specified file name including the extension delimeter (".").
static java.lang.String	getExtension(java.lang.String fileName, boolean includeExtSep) Gets the extension of the specified file name.
static boolean	writeToFile(java.lang.String fileName, java.lang.String str) Writes a specified string to the specified file; the file is always overwritten.
static boolean	writeToFile(java.lang.String fileName, java.lang.String str, boolean append) Writes a specified string to the specified file.

Methods inherited from class java.lang.Object

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

Field Detail

FILE_EXTENSION_SEPARATOR

public static final java.lang.String FILE_EXTENSION_SEPARATOR

See Also:

Constant Field Values

FILE_NAME_UNIQUE_MAKER_TAG

public static final java.lang.String FILE_NAME_UNIQUE_MAKER_TAG

See Also:

Constant Field Values

Constructor Detail

FileTools

private FileTools()

Prevents instances of this class from being created as this class contains only static utility methods.

Method Detail

getExtension

public static java.lang.String getExtension(java.lang.String fileName)

Gets the extension of the specified file name including the extension delimeter ("."). The extension is the part of the file name after the last occurence of the extension delimeter.

Parameters:

fileName - A file name.

Returns:

The extension of the specified file name including the extension delimeter; if the file name does not include an extension delimeter, an empty string is returned.

getExtension

public static java.lang.String getExtension(java.lang.String fileName,
                                            boolean includeExtSep)

Gets the extension of the specified file name. The extension is the part of the file name after the last occurence of the extension delimeter (".").

Parameters:

fileName - A file name.

includeExtSep - Whether the extension delimeter (".") will be returned as part of the extension.

Returns:

The extension of the specified file name; if the file name does not include an extension delimeter, an empty string is returned.

getExtension

public static java.lang.String getExtension(java.io.File file)

Gets the extension of the specified file including the extension delimeter ("."). The extension is the part of the file name after the last occurence of the extension delimeter.

Parameters:

file - A file

Returns:

The extension of the specified file including the extension delimeter; if the file name does not include an extension delimeter, an empty string is returned.

getExtension

public static java.lang.String getExtension(java.io.File file,
                                            boolean includeExtSep)

Gets the extension of the specified file. The extension is the part of the file name after the last occurence of the extension delimeter (".").

Parameters:

file - A file.

includeExtSep - Whether the extension delimeter (".") will be returned as part of the extension.

Returns:

The extension of the specified name; if the file name does not include an extension delimeter, an empty string is returned.

getBaseName

public static java.lang.String getBaseName(java.lang.String fileName)

Gets the base name of the specified file name. The base name is the part of the file name before the last occurence of the extension delimeter (".").

Parameters:

fileName - A file name.

Returns:

The base name of the specified file name.

getBaseName

public static java.lang.String getBaseName(java.io.File file)

Gets the base name of the specified name. The base name is the part of the file name before the last occurence of the extension delimeter (".").

Parameters:

file - A file.

Returns:

The base name of the specified file.

concatDirFile

public static final java.lang.String concatDirFile(java.lang.String dirName,
                                                   java.lang.String fileName)

Concatenates a directory name and a file name to build a path by inserting a file separator ('/' or '\\') between them if necessary.
For example all of the following calls will produce the same result:
- concatDirFile("dir/subdir", "file.name")
- concatDirFile("dir/subdir/", "file.name")
- concatDirFile("dir/subdir", "/file.name")
- concatDirFile("dir/subdir/", "/file.name")
RESULT: "dir/subdir/file.name"
Note that '/' is used in the example, but '\\' is equally supported.

Parameters:

dirName - A directory name.

fileName - A file name

Returns:

A file path.

concatFileExt

public static final java.lang.String concatFileExt(java.lang.String fileBaseName,
                                                   java.lang.String fileExt)

Concatenates a file base nameand a file extension to build a full file name by inserting a file extension separator ('.') between them if necessary.
For example all of the following calls will produce the same result:
- concatDirFile("basename", "ext")
- concatDirFile("basename.", "ext")
- concatDirFile("basename", ".ext")
- concatDirFile("basename.", ".ext")
RESULT: "basename.ext"

Parameters:

fileBaseName - A file base name.

fileExt - A file extension.

Returns:

The complete file name.

findUniqueFileName

public static java.lang.String findUniqueFileName(java.lang.String fileName,
                                                  java.lang.String fileExt,
                                                  boolean alwaysUseTimestamp)

Creates an absolute file name describing a file with the specified base name and extension as well as an optional timestamp and an optional counter to make the file name unique; the program start directory is used for the path.
This methos works generally in the same way as findUniqueFileName(String, String, String, boolean) and is equivalent to findUniqueFile(fileName, fileExt, alwaysUseTimestamp).getAbsolutePath().

Parameters:

fileName - The base name for the unique albolute file name to be created.

fileExt - The extension for the unique albolute file name to be created.

alwaysUseTimestamp - Whether to use a timestamp if no timestamp position marker is specified.

Returns:

An absolute file name decribing a path based on the specified parameters modified as above to make sure that no file with the same name/path already exists.

findUniqueFileName

public static java.lang.String findUniqueFileName(java.lang.String fileDir,
                                                  java.lang.String fileName,
                                                  java.lang.String fileExt,
                                                  boolean alwaysUseTimestamp)

Creates an absolute file name describing a file with the specified base name, extension and directory as well as an optional timestamp and an optional counter to make the file name unique.
This methos works generally in the same way as findUniqueFileName(String, String, String, boolean) and is equivalent to findUniqueFile(fileDir, fileName, fileExt, alwaysUseTimestamp).getAbsolutePath().

Parameters:

fileDir - The directory for the unique albolute file name to be created.

fileName - The base name for the unique albolute file name to be created.

fileExt - The extension for the unique-path File object to be created.

alwaysUseTimestamp - Whether to use a timestamp if no timestamp position marker is specified.

Returns:

An absolute file name decribing a path based on the specified parameters modified as above to make sure that no file with the same name/path already exists.

findUniqueFile

public static java.io.File findUniqueFile(java.lang.String fileName,
                                          java.lang.String fileExt,
                                          boolean alwaysUseTimestamp)

Creates a File object describing a file with the specified base name and extension as well as an optional timestamp and an optional counter to make the file name unique; the program start directory is used for the path.
This methos works generally in the same way as findUniqueFileName(String, String, String, boolean) and is equivalent to findUniqueFile(System.getProperty("user.dir"), fileName, fileExt, alwaysUseTimestamp).

Parameters:

fileName - The base name for the unique-path File object to be created.

fileExt - The extension for the unique-path File object to be created.

alwaysUseTimestamp - Whether to use a timestamp if no timestamp position marker is specified.

Returns:

A File object decribing a path based on the specified parameters modified to make sure that no file with the same name/path already exists.

findUniqueFile

public static java.io.File findUniqueFile(java.lang.String fileDir,
                                          java.lang.String fileName,
                                          java.lang.String fileExt,
                                          boolean alwaysUseTimestamp)

Creates a File object describing a file with the specified base name, extension and directory as well as an optional timestamp and an optional counter to make the file name unique. This method works as follows:
1) A file name is created on the basis of the specified directory, base name and extension. (e.g. "directory/basename.ext").
2) If the specified file name contains a substring that defines a timestamp marker (the string ""%ts""), the marker is replaced by a timestamp based on the current system time. If the specified file name does not contain a timestamp marker and alwaysUseTimestamp is true, a timestamp is inserted after the filename and before the extension. If the specified file name does not contain a timestamp marker and alwaysUseTimestamp is false, no timespamp is inserted. Executed on 20 Jan 2008 at 18:30:15 the result may look like this: "directory/basename.08.01.20-18.30.15.ext".
3) If no physical file with the resulting file name exists already, the corresponding File object is returned. If a file with the resulting path exists, a counter is inserted just before the extension. The result may look like this: "directory/basename.08.01.20-18.30.15(1).ext".
4) The uniqueness counter is increased (starting with 1) until the resulting file name does not describe a physical file that already exists.
Note that this method does not attempt to synchronise on the file system, i.e. if this method is invoked by different processes/threads at the same time the resulting file paths may or may not be be the same.

Parameters:

fileDir - The directory for the unique-path File object to be created.

fileName - The base name for the unique-path File object to be created.

fileExt - The extension for the unique-path File object to be created.

alwaysUseTimestamp - Whether to use a timestamp if no timestamp position marker is specified.

Returns:

A File object decribing a path based on the specified parameters modified as above to make sure that no file with the same name/path already exists.

writeToFile

public static boolean writeToFile(java.lang.String fileName,
                                  java.lang.String str)

Writes a specified string to the specified file; the file is always overwritten.

Parameters:

fileName - The name of the file to write to.

str - The string to write to the file.

Returns:

false if the specified file name was null or if an IO exception occured; true otherwise.

writeToFile

public static boolean writeToFile(java.lang.String fileName,
                                  java.lang.String str,
                                  boolean append)

Writes a specified string to the specified file.

Parameters:

fileName - The name of the file to write to.

str - The string to write to the file.

append - If true than the string will be appended at the end of the file, otherwise the file will be overwritten.

Returns:

false if the specified file name was null or if an IO exception occured; true otherwise.

deleteRecursively

public static boolean deleteRecursively(java.lang.String path)

Deletes the specified file, if the file specifies a directory all contained files and subdirectories are also deleted recursively. Note that if an error occurs during the recursive deletion of files contained within a directory, some of the directory contents and the directory itself may not be deleted. (This is on contrary to the deleteAllRecursively-methods in this class that proceed attempting to delete as many of the contained files and subdirectories as possible.)

Parameters:

path - The file or directory to delete.

Returns:

If the specified file or directory as well as all contained files and subdirectories are successfully deleted this method returns true, otherwise it returns false.

deleteRecursively

public static boolean deleteRecursively(java.io.File file)

Deletes the specified file, if the file specifies a directory all contained files and subdirectories are also deleted recursively. Note that if an error occurs during the recursive deletion of files contained within a directory, some of the directory contents and the directory itself may not be deleted. (This is on contrary to the deleteAllRecursively-methods in this class that proceed attempting to delete as many of the contained files and subdirectories as possible.)

Parameters:

file - The file or directory to delete.

Returns:

If the specified file or directory as well as all contained files and subdirectories are successfully deleted this method returns true, otherwise it returns false.

deleteAllRecursively

public static boolean deleteAllRecursively(java.lang.String path)

Deletes the specified file; if the path specifies a directory all contained files and subdirectories are also deleted recursively. If an error occurs during the recursive deletion of files this method proceeds attempting to delete as many of the contained files and subdirectories as possible (this is on contrary to the deleteRecursively-methods in this class that return immediately if an error is encountered).
This method is equivalent to deleteAllRecursively(new File(path), null, null).

Parameters:

path - The file or directory to delete.

Returns:

If the specified file or directory as well as all contained files and subdirectories are successfully deleted this method returns true, otherwise it returns false.

deleteAllRecursively

public static boolean deleteAllRecursively(java.lang.String path,
                                           java.util.List<java.io.File> deleted,
                                           java.util.List<java.io.File> failed)

Deletes the specified file; if the path specifies a directory all contained files and subdirectories are also deleted recursively. If an error occurs during the recursive deletion of files this method proceeds attempting to delete as many of the contained files and subdirectories as possible (this is on contrary to the deleteRecursively-methods in this class that return immediately if an error is encountered).
If the list deleted is null it is ignored, otherwise all files that are successfully deteted will be added to the deleted-list. If the list failed is null it is ignored, otherwise all files that could not be successfully deteted will be added to the failed-list.
This method is equivalent to deleteAllRecursively(new File(path), deleted, failed).

Parameters:

path - The file or directory to delete.

deleted - A list to which all successfully deleted files are to be added (may be null in which case it is ignored).

failed - A list to which all files that could not be successfully deleted are to be added (may be null in which case it is ignored).

Returns:

If the specified file or directory as well as all contained files and subdirectories are successfully deleted this method returns true, otherwise it returns false.

deleteAllRecursively

public static boolean deleteAllRecursively(java.io.File file)

Deletes the specified file; if the file specifies a directory all contained files and subdirectories are also deleted recursively. If an error occurs during the recursive deletion of files this method proceeds attempting to delete as many of the contained files and subdirectories as possible (this is on contrary to the deleteRecursively-methods in this class that return immediately if an error is encountered).
This method is equivalent to deleteAllRecursively(file, null, null).

Parameters:

file - The file or directory to delete.

Returns:

If the specified file or directory as well as all contained files and subdirectories are successfully deleted this method returns true, otherwise it returns false.

deleteAllRecursively

public static boolean deleteAllRecursively(java.io.File file,
                                           java.util.List<java.io.File> deleted,
                                           java.util.List<java.io.File> failed)

Deletes the specified file; if the file specifies a directory all contained files and subdirectories are also deleted recursively. If an error occurs during the recursive deletion of files this method proceeds attempting to delete as many of the contained files and subdirectories as possible (this is on contrary to the deleteRecursively-methods in this class that return immediately if an error is encountered).
If the list deleted is null it is ignored, otherwise all files that are successfully deteted will be added to the deleted-list. If the list failed is null it is ignored, otherwise all files that could not be successfully deteted will be added to the failed-list.

Parameters:

file - The file or directory to delete.

deleted - A list to which all successfully deleted files are to be added (may be null in which case it is ignored).

failed - A list to which all files that could not be successfully deleted are to be added (may be null in which case it is ignored).

Returns:

If the specified file or directory as well as all contained files and subdirectories are successfully deleted this method returns true, otherwise it returns false.