net.sf.mmm.util.file.api
Interface FileUtil

All Known Implementing Classes:

FileUtilImpl

@ComponentSpecification
public interface FileUtil

This is the interface for a collection of utility functions for File handling and manipulation.

Since:

1.0.2

Author:

Joerg Hohwiller (hohwille at users.sourceforge.net)

See Also:

FileUtilImpl

Field Summary

static File[]	NO_FILES An empty file array.
static String	PATH_SEGMENT_CURRENT The path segment indicating the current folder itself.
static String	PATH_SEGMENT_PARENT The path segment indicating the parent folder.
static String	PROPERTY_TMP_DIR The key of the system property "java.io.tmpdir".
static String	PROPERTY_USER_HOME The key of the system property "user.home".

Method Summary

boolean	collectMatchingFiles(File cwd, String path, FileType fileType, List<File> list) This method adds all files matching the given path and fileType to the list.
void	copyFile(File source, File destination) This method copies the file given by source to the file given by destination.
void	copyFile(File source, File destination, boolean keepFlags) This method copies the file given by source to the file given by destination.
void	copyRecursive(File source, File destination, boolean allowOverwrite) This method copies the file or directory given by source into the given destination.
void	copyRecursive(File source, File destination, boolean allowOverwrite, FileFilter filter) This method copies the file or directory given by source into the given destination.
int	deleteChildren(File directory) This method deletes all children of the given directory recursively.
int	deleteRecursive(File path) This method deletes the given path.
String	getBasename(String filename) This method gets the basename of the given filename (path).
String	getDirname(String filename) This method gets the directory-name of the given filename (path).
String	getExtension(String filename) This method extracts the extension from the given filename.
File[]	getMatchingFiles(File cwd, String path, FileType fileType) This method gets all files matching to the given path and fileType.
FileAccessPermissions	getPermissions(File file, FileAccessClass accessClass) This method gets the permissions of the given file.
File	getTemporaryDirectory() This method gets the File representing the temporary directory.
File	getUserHomeDirectory() This method gets the File representing the home directory of the user.
String	normalizePath(String path) This method is a shortcut for normalizePath(path, File.separatorChar).
String	normalizePath(String path, char separator) This method normalizes a given path.
void	setPermissions(File file, FileAccessPermissions permissions) This method sets the permissions of the given file.

Field Detail

PATH_SEGMENT_CURRENT

static final String PATH_SEGMENT_CURRENT

The path segment indicating the current folder itself.

See Also:

Constant Field Values

PATH_SEGMENT_PARENT

static final String PATH_SEGMENT_PARENT

The path segment indicating the parent folder.

See Also:

Constant Field Values

PROPERTY_USER_HOME

static final String PROPERTY_USER_HOME

The key of the system property "user.home". It contains the home directory of the user that started this JVM.
Examples are /home/mylogin or C:\Windows\Profiles\mylogin.

See Also:

Constant Field Values

PROPERTY_TMP_DIR

static final String PROPERTY_TMP_DIR

The key of the system property "java.io.tmpdir". It contains the directory to use for temporary files.
Examples are /tmp, C:\Temp or /usr/local/tomcat/temp.

See Also:

Constant Field Values

NO_FILES

static final File[] NO_FILES

An empty file array.

Method Detail

getUserHomeDirectory

File getUserHomeDirectory()

This method gets the File representing the home directory of the user.

Returns:

the home directory of the user.

getTemporaryDirectory

File getTemporaryDirectory()

This method gets the File representing the temporary directory.

Returns:

the tmp directory.

normalizePath

String normalizePath(String path,
                     char separator)

This method normalizes a given path. It will resolve ".." and "." segments, normalize backslashes and remove duplicated slashes. Further it can resolve "~" at the beginning of the path (like in bash-scripts, etc.). Therefore this method resolves the path in such situations (e.g. to "/home/login/foo") and returns a physical path.
Here are some examples assuming that separator is '/' (backslashes are NOT escaped):

path	normalizePath(path)
"folder/subfolder//../.\some.file"	"folder/some.file"
"../.\some.file"	"../some.file"
"http://www.host.com/foo/bar/./test/.././.."	"http://www.host.com/foo"
"\\unc.host\printers\pr3761"	"\\unc.host\printers\pr3761"
"~/documents/index.html"	getUserHomeDirectory() + "/documents/index.html"
"~root/subfolder/../folder/.//index.html"	"/root/folder/index.html"

ATTENTION:
Normalizing home-directories of other users (e.g. "~user/") makes various assumptions and is NOT guaranteed to be correct in any case.

Parameters:

path - is the path to resolve.

separator - is the character to use as file separator.

Returns:

the resolved path.

normalizePath

String normalizePath(String path)

This method is a shortcut for normalizePath(path, File.separatorChar).

Parameters:

path - is the path to resolve.

Returns:

the resolved path.

See Also:

normalizePath(String, char)

getExtension

String getExtension(String filename)

This method extracts the extension from the given filename.
Example: getExtension("test.java") would return "java".
ATTENTION:
If the filename is just a dot followed by the extension (e.g. ".java"), the empty string is returned.

Parameters:

filename - is the filename and may include an absolute or relative path.

Returns:

the extension of the given filename excluding the dot in lowercase or the empty string if NOT present.

getBasename

String getBasename(String filename)

This method gets the basename of the given filename (path). The basename is the raw name of the file without the path.
Examples:

filename	getBasename(filename)
/	/
\/\	\
/.	.
/foo.bar	foo.bar
/foo/bar/	bar
c:\\
c:\\foo	foo
http://foo.org/bar	bar

Parameters:

filename - is the path to a file or directory.

Returns:

the basename of the given filename.

getDirname

String getDirname(String filename)

This method gets the directory-name of the given filename (path).
Examples:

filename	getDirname(String)
foo	.
/foo	/
/foo/bar	/foo
/foo/bar/	/foo
./foo/bar/	./foo
./foo/bar/../	./foo/bar

Parameters:

filename - is the path to a file or directory.

Returns:

the path to the directory containing the file denoted by the given filename.

See Also:

normalizePath(String)

copyFile

void copyFile(File source,
              File destination)
              throws RuntimeIoException

This method copies the file given by source to the file given by destination.

Parameters:

source - is the existing file to copy from.

destination - is the file to copy to. It will be created if it does NOT exist and overridden otherwise.

Throws:

RuntimeIoException - if the operation fails.

copyFile

void copyFile(File source,
              File destination,
              boolean keepFlags)
              throws RuntimeIoException

This method copies the file given by source to the file given by destination.
ATTENTION:
This method will only work with java 1.6 and above!

Parameters:

source - is the existing file to copy from.

destination - is the file to copy to. It will be created if it does NOT exist and overridden otherwise.

keepFlags - - true if the flags of the file should be copied as well, false otherwise (a new file is created with default flags and only the content is copied).

Throws:

RuntimeIoException - if the operation fails.

getPermissions

FileAccessPermissions getPermissions(File file,
                                     FileAccessClass accessClass)

This method gets the permissions of the given file.
ATTENTION:
This operation is only available since java 6. Further it is limited and can only determine the permissions granted to the current user running this application.

Parameters:

file - is the file for which the permissions are requested.

accessClass - is the distinct class the permission should be applied to in the returned permissions. It may be null to apply the permissions to all distinct classes.

Returns:

the permissions of file.

setPermissions

void setPermissions(File file,
                    FileAccessPermissions permissions)

This method sets the permissions of the given file.
ATTENTION:
This operation is only available since java 6. Further it is limited to the permissions FileAccessClass.OTHERS and FileAccessClass.USER so FileAccessClass.GROUP flags are ignored as well as the global s-bits (sticky, setgid and setuid).

Parameters:

file - is the file to modify.

permissions - are the permissions to set.

copyRecursive

void copyRecursive(File source,
                   File destination,
                   boolean allowOverwrite)
                   throws RuntimeIoException

This method copies the file or directory given by source into the given destination.
ATTENTION:
In order to allow giving the copy of source a new name, the destination has to point to the final place where the copy should appear rather than the directory where the copy will be located in.

E.g. the following code copies the folder "foo" located in "/usr/local" recursively to the directory "/tmp". The copy will have the same name "foo".

 File source = new File("/usr/local/foo");
 File destination = new File("/tmp", source.getName()); // file: "/tmp/foo"
 fileUtil.copyRecursive(source, destination, true);
 

Parameters:

source - is the file or directory to copy.

destination - is the final place where the copy should appear.

allowOverwrite - - if false and the destination already exists, a RuntimeIoException is thrown, else if true the destination will be overwritten.

Throws:

RuntimeIoException - if the operation fails.

copyRecursive

void copyRecursive(File source,
                   File destination,
                   boolean allowOverwrite,
                   FileFilter filter)
                   throws RuntimeIoException

This method copies the file or directory given by source into the given destination.
ATTENTION:
In order to allow giving the copy of source a new name, the destination has to point to the final place where the copy should appear rather than the directory where the copy will be located in.

Parameters:

source - is the file or directory to copy.

destination - is the final place where the copy should appear.

allowOverwrite - - if false and the destination already exists, a RuntimeIoException is thrown, else if true the destination will be overwritten.

filter - is a FileFilter that decides which files should be copied. Only accepted files and directories are copied, others will be ignored.

Throws:

RuntimeIoException - if the operation fails.

See Also:

copyRecursive(File, File, boolean)

deleteRecursive

int deleteRecursive(File path)
                    throws RuntimeIoException

This method deletes the given path. If the path denotes a directory then it will be deleted recursively.

Parameters:

path - is the path to delete.

Returns:

the number of files that have been deleted (excluding the directories).

Throws:

RuntimeIoException - if a file or directory could NOT be deleted.

See Also:

deleteChildren(File)

deleteChildren

int deleteChildren(File directory)
                   throws RuntimeIoException

This method deletes all children of the given directory recursively. If the given directory denotes an existing directory then it will be empty after the call of this method, else this method will have no effect.

Parameters:

directory - is the directory to delete.

Returns:

the number of files that have been deleted (excluding the directories).

Throws:

RuntimeIoException - if a file or directory could NOT be deleted.

getMatchingFiles

File[] getMatchingFiles(File cwd,
                        String path,
                        FileType fileType)

This method gets all files matching to the given path and fileType. The path may contain wildcards.
Examples:

• getMatchingFiles(cwd, "*", FileType.DIRECTORY) will return all directories in cwd
• getMatchingFiles(cwd, "*/*.xml", FileType.FILE) will return all files from all direct sub-folders of cwd that end with ".xml"
• getMatchingFiles(cwd, "**/*.xml", FileType.FILE) will return all files in cwd or any of its transitive sub-folders that end with ".xml"

Parameters:

cwd - is the current working directory and should therefore point to an existing directory. If the given path is NOT absolute it is interpreted relative to this directory.

path - is the path the requested files must match. If this path is NOT absolute it is interpreted relative to the directory given by cwd.

fileType - is the type of the requested files or null if files of any type are acceptable.

Returns:

an array containing all the files that match the given path and apply to ignore

See Also:

collectMatchingFiles(File, String, FileType, List)

collectMatchingFiles

boolean collectMatchingFiles(File cwd,
                             String path,
                             FileType fileType,
                             List<File> list)

This method adds all files matching the given path and fileType to the list. The path may contain wildcards.

Parameters:

cwd - is the current working directory and should therefore point to an existing directory. If the given path is NOT absolute it is interpreted relative to this directory.

path - is the path the files to collect must match. If this path is NOT absolute it is interpreted relative to the directory given by cwd.

fileType - is the type of the files to collect or null if files of any type are acceptable.

list - is the list where to add the collected files.

Returns:

false if the path is a regular string and true if the given path contains at least one wildcard ( '*' or '?').