edu.tum.cs.commons.filesystem
Class FileSystemUtils

java.lang.Object
  edu.tum.cs.commons.filesystem.FileSystemUtils

public class FileSystemUtils
extends Object

File system utilities.

Version:

$Rev: 29722 $

Author:

Florian Deissenboeck, Benjamin Hummel, $Author: deissenb $

Rating:

GREEN Hash: C0A48F2C854364D0F04BB664D5A318A6

Field Summary

static Charset	UTF8_CHARSET Charset for UTF-8.
static String	UTF8_ENCODING Encoding for UTF-8.

Constructor Summary

FileSystemUtils()

Method Summary

static InputStream	autoDecompressStream(InputStream in) Transparently creates a stream for decompression if the provided stream is compressed.
static File	canonize(File file) Deprecated.
static String	canonize(String path) Deprecated.
static void	close(Closeable closeable) Convenience method for calling close(Closeable, ILogger) with a null-logger.
static void	close(Closeable closeable, ILogger logger) This method can be used to simplify the typical finally -block of code dealing with streams and readers/writers.
static File	commonRoot(Iterable<? extends File> files) Determines the root directory from a collection of files.
static int	copy(InputStream input, OutputStream output) Copy an input stream to an output stream.
static void	copyFile(File sourceFile, File targetFile) Copy a file.
static void	copyFile(String sourceFilename, String targetFilename) Copy a file.
static int	copyFiles(File sourceDirectory, File targetDirectory, FileFilter fileFilter) Copy all files specified by a file filter from one directory to another.
static int	createJARFile(File jarFile, File directory, FileFilter filter) Create jar file from all files in a directory.
static String	createRelativePath(File path, File relativeTo) Returns a string describing the relative path to the given directory.
static void	deleteFile(File file) Deletes the given file and throws an exception if this fails.
static void	deleteRecursively(File directory) Recursively delete directories and files.
static void	ensureDirectoryExists(File file) Checks if a directory exists.
static void	ensureParentDirectoryExists(File file) Checks if the parent directory of a file exists.
static File	extractJarFileFromJarURL(URL url) Returns the JAR file for an URL with protocol 'jar'.
static String	getFileExtension(File file) Returns the extension of the file.
static boolean	isAbsolutePath(String filename) Returns whether a filename represents an absolute path.
static List<File>	listFilesRecursively(File directory) Returns a list of all files and directories contained in the given directory and all subdirectories.
static List<File>	listFilesRecursively(File directory, FileFilter filter) Returns a list of all files and directories contained in the given directory and all subdirectories matching the filter provided.
static void	mergeTemplate(File templateFile, File outFile, Object... arguments) Loads template file with a Format string, formats it and writes result to file.
static InputStream	mergeTemplate(InputStream inStream, Object... arguments) Loads template file with a Format string, formats it and provides result as stream.
static void	mkdir(File dir) Creates a directory and throws an exception if this fails.
static void	mkdirs(File dir) Creates a directory and all required parent directories.
static File	newFile(File parent, String... elements) This method is similar to the constructor File.File(File, String) but allows to define multiple child levels.
static String	normalizeSeparators(String path) Replace platform dependent separator char with forward slashes to create system-independent paths.
static String	readFile(File file) Read file content into a string using the default encoding for the platform.
static String	readFile(File file, String encoding) Read file content into a string using the given encoding.
static String	readFileUTF8(File file) Read file content into a string using UTF-8 encoding.
static Properties	readPropertiesFile(File propertiesFile) Reads properties from a properties file.
static String	readStream(InputStream input) Read input stream into string.
static String	readStream(InputStream input, String encoding) Read input stream into string.
static String	readStreamUTF8(InputStream input) Read input stream into string.
static void	renameFileTo(File file, File dest) Renames the given file and throws an exception if this fails.
static void	safeRead(InputStream in, byte[] data) Reads bytes of data from the input stream into an array of bytes until the array is full.
static void	safeRead(InputStream in, byte[] data, int offset, int length) Reads length bytes of data from the input stream into an array of bytes and stores it at position offset.
static void	sort(List<File> files) Compares files based on the lexical order of their fully qualified names.
static void	unjar(File jarFile, File targetDirectory) Extract a JAR file to a directory.
static void	writeFile(File file, String content) Write string to a file with the default encoding.
static void	writeFile(File file, String content, String encoding) Write string to a file.
static void	writeFileUTF8(File file, String content) Write string to a file with UTF8 encoding.
static void	writeFileWithBOM(File file, String content, EByteOrderMark bom) Write string to a file using a UTF encoding.

Methods inherited from class java.lang.Object

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

Field Detail

UTF8_ENCODING

public static final String UTF8_ENCODING

Encoding for UTF-8.

See Also:

Constant Field Values

UTF8_CHARSET

public static final Charset UTF8_CHARSET

Charset for UTF-8.

Constructor Detail

FileSystemUtils

public FileSystemUtils()

Method Detail

copy

public static int copy(InputStream input,
                       OutputStream output)
                throws IOException

Copy an input stream to an output stream. This does not close the streams.

Parameters:

input - input stream

output - output stream

Returns:

number of bytes copied

Throws:

IOException - if an IO exception occurs.

copyFile

public static void copyFile(File sourceFile,
                            File targetFile)
                     throws IOException

Copy a file. This creates all necessary directories.

Throws:

IOException

copyFile

public static void copyFile(String sourceFilename,
                            String targetFilename)
                     throws IOException

Copy a file. This creates all necessary directories.

Throws:

IOException

copyFiles

public static int copyFiles(File sourceDirectory,
                            File targetDirectory,
                            FileFilter fileFilter)
                     throws IOException

Copy all files specified by a file filter from one directory to another. This automatically creates all necessary directories.

Parameters:

sourceDirectory - source directory

targetDirectory - target directory

fileFilter - filter to specify file types. If all files should be copied, use FileOnlyFilter.

Returns:

number of files copied

Throws:

IOException - if an exception occurs.

createJARFile

public static int createJARFile(File jarFile,
                                File directory,
                                FileFilter filter)
                         throws IOException

Create jar file from all files in a directory.

Parameters:

jarFile - jar file to create.

directory - source directory.

filter - filter to specify file types. If all files should be copied, use FileOnlyFilter.

Returns:

number of files added to the jar file

Throws:

IOException - if an exception occurs.

createRelativePath

public static String createRelativePath(File path,
                                        File relativeTo)
                                 throws IOException

Returns a string describing the relative path to the given directory. If there is no relative path, as the directories do not share a common parent, the absolute path is returned.

Parameters:

path - the path to convert to a relative path (must describe an existing directory)

relativeTo - the anchor (must describe an existing directory)

Returns:

a relative path

Throws:

IOException - if creation of canonical pathes fails.

deleteRecursively

public static void deleteRecursively(File directory)

Recursively delete directories and files. This method ignores the return value of delete(), i.e. if anything fails, some files might still exist.

deleteFile

public static void deleteFile(File file)
                       throws IOException

Deletes the given file and throws an exception if this fails.

Throws:

IOException

See Also:

File.delete()

renameFileTo

public static void renameFileTo(File file,
                                File dest)
                         throws IOException

Renames the given file and throws an exception if this fails.

Throws:

IOException

See Also:

File.renameTo(File)

mkdir

public static void mkdir(File dir)
                  throws IOException

Creates a directory and throws an exception if this fails.

Throws:

IOException

See Also:

File.mkdir()

mkdirs

public static void mkdirs(File dir)
                   throws IOException

Creates a directory and all required parent directories. Throws an exception if this fails.

Throws:

IOException

See Also:

File.mkdirs()

ensureDirectoryExists

public static void ensureDirectoryExists(File file)
                                  throws IOException

Checks if a directory exists. If not it creates the directory and all necessary parent directories.

Parameters:

file - the directory

Throws:

IOException - if directories couldn't be created.

ensureParentDirectoryExists

public static void ensureParentDirectoryExists(File file)
                                        throws IOException

Checks if the parent directory of a file exists. If not it creates the directory and all necessary parent directories.

Parameters:

file - the file

Throws:

IOException - if directories couldn't be created.

listFilesRecursively

public static List<File> listFilesRecursively(File directory)

Returns a list of all files and directories contained in the given directory and all subdirectories. The given directory itself is not included in the result.

This method knows nothing about (symbolic and hard) links, so care should be taken when traversing directories containing recursive links.

Parameters:

directory - the directory to start the search from.

Returns:

the list of files found (the order is determined by the file system).

listFilesRecursively

public static List<File> listFilesRecursively(File directory,
                                              FileFilter filter)

Returns a list of all files and directories contained in the given directory and all subdirectories matching the filter provided. The given directory itself is not included in the result.

The file filter may or may not exclude directories.

This method knows nothing about (symbolic and hard) links, so care should be taken when traversing directories containing recursive links.

Parameters:

directory - the directory to start the search from. If this is null or the directory does not exists, an empty list is returned.

filter - the filter used to determine whether the result should be included. If the filter is null, all files and directories are included.

Returns:

the list of files found (the order is determined by the file system).

getFileExtension

public static String getFileExtension(File file)

Returns the extension of the file.

Returns:

File extension, i.e. "java" for "FileSystemUtils.java", or null, if the file has no extension (i.e. if a filename contains no '.'), returns the empty string if the '.' is the filename's last character.

newFile

public static File newFile(File parent,
                           String... elements)

This method is similar to the constructor File.File(File, String) but allows to define multiple child levels.

Parameters:

parent - parent file

elements - list of elements. If this is empty, the parent is returned.

Returns:

the new file.

readFile

public static String readFile(File file)
                       throws IOException

Read file content into a string using the default encoding for the platform. If the file starts with a UTF byte order mark (BOM), the encoding is ignored and the correct encoding based on this BOM is used for reading the file.

Throws:

IOException

See Also:

EByteOrderMark

readFileUTF8

public static String readFileUTF8(File file)
                           throws IOException

Read file content into a string using UTF-8 encoding. If the file starts with a UTF byte order mark (BOM), the encoding is ignored and the correct encoding based on this BOM is used for reading the file.

Throws:

IOException

See Also:

EByteOrderMark

readFile

public static String readFile(File file,
                              String encoding)
                       throws IOException,
                              UnsupportedEncodingException

Read file content into a string using the given encoding. If the file starts with a UTF byte order mark (BOM), the encoding is ignored and the correct encoding based on this BOM is used for reading the file.

Throws:

IOException

UnsupportedEncodingException

See Also:

EByteOrderMark

unjar

public static void unjar(File jarFile,
                         File targetDirectory)
                  throws IOException

Extract a JAR file to a directory.

Parameters:

jarFile - jar file to extract

targetDirectory - target directory.

Throws:

IOException - if an exception occurs.

writeFile

public static void writeFile(File file,
                             String content)
                      throws IOException

Write string to a file with the default encoding. This ensures all directories exist.

Throws:

IOException

writeFileUTF8

public static void writeFileUTF8(File file,
                                 String content)
                          throws IOException

Write string to a file with UTF8 encoding. This ensures all directories exist.

Throws:

IOException

writeFile

public static void writeFile(File file,
                             String content,
                             String encoding)
                      throws IOException

Write string to a file. This ensures all directories exist.

Throws:

IOException

writeFileWithBOM

public static void writeFileWithBOM(File file,
                                    String content,
                                    EByteOrderMark bom)
                             throws IOException

Write string to a file using a UTF encoding. The file will be prefixed with a byte-order mark. This ensures all directories exist.

Throws:

IOException

mergeTemplate

public static void mergeTemplate(File templateFile,
                                 File outFile,
                                 Object... arguments)
                          throws IOException

Loads template file with a Format string, formats it and writes result to file.

Parameters:

templateFile - the template file with the format string

outFile - the target file, parent directories are created automatically.

arguments - the formatting arguments.

Throws:

IOException - if an IO exception occurs or the template file defines an illegal format.

mergeTemplate

public static InputStream mergeTemplate(InputStream inStream,
                                        Object... arguments)
                                 throws IOException

Loads template file with a Format string, formats it and provides result as stream. No streams are closed by this method.

Parameters:

inStream - stream that provides the template format string

arguments - the formatting arguments.

Throws:

IOException - if an IOException occurs or the template file defines an illegal format.

readStream

public static String readStream(InputStream input)
                         throws IOException

Read input stream into string.

Throws:

IOException

readStreamUTF8

public static String readStreamUTF8(InputStream input)
                             throws IOException

Read input stream into string.

Throws:

IOException

readStream

public static String readStream(InputStream input,
                                String encoding)
                         throws IOException

Read input stream into string.

Throws:

IOException

readPropertiesFile

public static Properties readPropertiesFile(File propertiesFile)
                                     throws IOException

Reads properties from a properties file.

Throws:

IOException

commonRoot

public static File commonRoot(Iterable<? extends File> files)
                       throws IOException

Determines the root directory from a collection of files. The root directory is the lowest common ancestor directory of the files in the directory tree.

This method does not require the input files to exist.

Parameters:

files - Collection of files for which root directory gets determined. This collection is required to contain at least 2 files. If it does not, an AssertionError is thrown.

Returns:

Root directory, or null, if the files do not have a common root directory.

Throws:

PreconditionException - If less than two different files are provided whereas fully qualified canonical names are used for comparison.

IOException - Since canonical paths are used for determination of the common root, and File.getCanonicalPath() can throw IOExceptions.

canonize

@Deprecated
public static String canonize(String path)

Deprecated.

See canonize(File)

canonize

@Deprecated
public static File canonize(File file)

Deprecated.

Creates a canonical path from a file path. This method wraps File.getCanonicalPath() and wraps IOExceptions thrown by it into AssertionErrors, since we expect this method not to throw IOExceptions.

autoDecompressStream

public static InputStream autoDecompressStream(InputStream in)
                                        throws IOException

Transparently creates a stream for decompression if the provided stream is compressed. Otherwise the stream is just handed through. Currently the following compression methods are supported:

• GZIP via GZIPInputStream

Throws:

IOException

close

public static void close(Closeable closeable)

Convenience method for calling close(Closeable, ILogger) with a null-logger.

close

public static void close(Closeable closeable,
                         ILogger logger)

This method can be used to simplify the typical finally -block of code dealing with streams and readers/writers. It checks if the provided closeable is null. If not it closes it. An exception thrown during the close operation is logged with the provided logger with level warn. If the provided logger is null, no logging is performed. If no logging is required, method close(Closeable) may also be used.

sort

public static void sort(List<File> files)

Compares files based on the lexical order of their fully qualified names. Files must not null.

normalizeSeparators

public static String normalizeSeparators(String path)

Replace platform dependent separator char with forward slashes to create system-independent paths.

extractJarFileFromJarURL

public static File extractJarFileFromJarURL(URL url)

Returns the JAR file for an URL with protocol 'jar'. If the protocol is not 'jar' an assertion error will be caused!

isAbsolutePath

public static boolean isAbsolutePath(String filename)

Returns whether a filename represents an absolute path. This method returns the same result, independent on which operating system it gets executed. In contrast, the behavior of File.isAbsolute() is operating system specific.

safeRead

public static void safeRead(InputStream in,
                            byte[] data)
                     throws IOException,
                            EOFException

Reads bytes of data from the input stream into an array of bytes until the array is full. This method blocks until input data is available, end of file is detected, or an exception is thrown. The reason for this method is that InputStream.read(byte[]) may read less than the requested number of bytes, while this method ensures the data is complete.

Parameters:

in - the stream to read from.

data - the stream to read from.

Throws:

IOException - if reading the underlying stream causes an exception.

EOFException - if the end of file was reached before the requested data was read.

safeRead

public static void safeRead(InputStream in,
                            byte[] data,
                            int offset,
                            int length)
                     throws IOException,
                            EOFException

Reads length bytes of data from the input stream into an array of bytes and stores it at position offset. This method blocks until input data is available, end of file is detected, or an exception is thrown. The reason for this method is that InputStream.read(byte[], int, int) may read less than the requested number of bytes, while this method ensures the data is complete.

Parameters:

in - the stream to read from.

data - the stream to read from.

offset - the offset in the array where the first read byte is stored.

length - the length of data read.

Throws:

IOException - if reading the underlying stream causes an exception.

EOFException - if the end of file was reached before the requested data was read.