net.sf.mmm.util.file.api

Interface FileUtil

All Superinterfaces:

FileUtilLimited

All Known Implementing Classes:

FileUtilImpl

@ComponentSpecification
public interface FileUtil
extends FileUtilLimited

This is the interface for a collection of utility functions for File handling and manipulation.
NOTE:
Since Java7 there is also Files that offers similar and additional features. However this is not supported in limited environments such as e.g. GWT.

Since:

1.0.2

Author:

Joerg Hohwiller (hohwille at users.sourceforge.net)

See Also:

FileUtilImpl

Field Summary

Fields inherited from interface net.sf.mmm.util.file.api.FileUtilLimited

NO_FILES, PATH_SEGMENT_CURRENT, PATH_SEGMENT_PARENT, PROPERTY_TMP_DIR, PROPERTY_USER_HOME

Method Summary

Modifier and Type	Method and Description
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.
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 current user.
void	setPermissions(File file, FileAccessPermissions permissions) This method sets the permissions of the given file.

Methods inherited from interface net.sf.mmm.util.file.api.FileUtilLimited

getBasename, getDirname, getExtension, normalizePath, normalizePath

Method Detail

getUserHomeDirectory

File getUserHomeDirectory()

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

Returns:

the home directory of the user.

getTemporaryDirectory

File getTemporaryDirectory()

This method gets the File representing the temporary directory.

Returns:

the tmp directory.

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 '?').