uk.org.ogsadai.common.files
Class FileUtilities

java.lang.Object
  |
  +--uk.org.ogsadai.common.files.FileUtilities

public class FileUtilities

extends java.lang.Object

Provides utilities for reading, writing and deleting files. Keeps files locked whilst in use, but allows many threads to read from the same file concurrently.

Author:

The OGSA-DAI Project Team

COPYRIGHT_NOTICE

private static final java.lang.String COPYRIGHT_NOTICE

See Also:

Constant Field Values

LOG

private static final DAILogger LOG

SINGLETON

private static final FileUtilities SINGLETON

LOCK

private static final FileLock LOCK

BUFFER_SIZE

private static final int BUFFER_SIZE

See Also:

Constant Field Values

FileUtilities

private FileUtilities()

A private constructor for the Singleton instance.

getInstance

public static FileUtilities getInstance()

Gets the singleton instance of this class.

Returns:

the singleton instance.

readStringFromFile

public static java.lang.String readStringFromFile(java.lang.String fileName)
                                           throws DAIFileNotFoundException,
                                                  DAIFileNotFileException,
                                                  DAIFileReadIOException

Reads the contents of a file into a string.

Parameters:

fileName - Name of file to read.

Returns:

the contents of the file.

Throws:

DAIFileNotFoundException - if the file cannot be found.

DAIFileNotFileException - if the file is not a file e.g. it's a directory.

DAIFileReadIOException - if there is an IO error when reading the file.

java.lang.IllegalArgumentException - if fileName is null.

replaceWriteStringToFile

public static void replaceWriteStringToFile(java.lang.String fileName,
                                            java.lang.String data)
                                     throws DAIFileNotFileException,
                                            DAIFileWriteIOException

Writes the contents of a string to a file. If the file does not exist will be created.

Parameters:

fileName - Name of file to write to.

data - The data to write to the file.

Throws:

DAIFileNotFileException - if the specified file is a non-file, for example a directory.

DAIFileWriteIOException - if there is an error writing to the file.

java.lang.IllegalArgumentException - if fileName is null.

writeStringToFile

public static void writeStringToFile(java.lang.String fileName,
                                     java.lang.String data)
                              throws DAIFileNotFileException,
                                     DAIFileWriteIOException,
                                     DAIFileAlreadyExistsException

Writes the contents of a string to a new file.

Parameters:

fileName - Name of file to write to.

data - The data to write to the file.

Throws:

DAIFileAlreadyExistsException - if the file already exists.

DAIFileNotFileException - if the specified file is a non-file, for example a directory.

DAIFileWriteIOException - if there is an error writing to the file.

java.lang.IllegalArgumentException - if fileName is null.

readByteArrayFromFile

public static byte[] readByteArrayFromFile(java.lang.String fileName)
                                    throws DAIFileNotFoundException,
                                           DAIFileNotFileException,
                                           DAIFileReadIOException

Reads the contents of a file into a byte array.

Parameters:

fileName - Name of file to read.

Returns:

the contents of the file.

Throws:

DAIFileNotFoundException - if the file cannot be found.

DAIFileNotFileException - if the file is not a file e.g. it's a directory.

DAIFileReadIOException - if there is an IO error when reading the file.

java.lang.IllegalArgumentException - if fileName is null.

writeByteArrayToFile

public static void writeByteArrayToFile(java.lang.String fileName,
                                        byte[] data)
                                 throws DAIFileNotFileException,
                                        DAIFileWriteIOException,
                                        DAIFileAlreadyExistsException

Writes the contents of a string to a byte array to a new file.

Parameters:

fileName - Name of file to write to.

data - The data to write to the file.

Throws:

DAIFileAlreadyExistsException - if the file already exists.

DAIFileNotFileException - if the specified file is a non-file, for example a directory.

DAIFileWriteIOException - if there is an error writing to the file.

java.lang.IllegalArgumentException - if either argument is null.

openStreamFromFile

public static java.io.InputStream openStreamFromFile(java.lang.String fileName)
                                              throws DAIFileNotFoundException,
                                                     DAIFileNotFileException,
                                                     DAIFileReadIOException

Open an InputStream for a file.

Parameters:

fileName - Name of file.

Returns:

InputStream.

Throws:

DAIFileNotFoundException - if the file cannot be found.

DAIFileNotFileException - if the file is not a file e.g. it's a directory.

DAIFileReadIOException - if there is an IO error when reading the file.

java.lang.IllegalArgumentException - if fileName is null.

closeStreamFromFile

public static void closeStreamFromFile(java.lang.String fileName,
                                       java.io.InputStream fileDataStream)
                                throws DAIFileReadIOException

Close an InputStream for a file.

Assumes that the InputStream was created using openStreamFromFile()

Parameters:

fileName - Name of file.

fileDataStream - File InputStream.

Throws:

DAIFileReadIOException - if there is an IO error when reading the file.

java.lang.IllegalArgumentException - if either argument is null.

readStringFromStream

public static java.lang.String readStringFromStream(java.io.InputStream inputStream)
                                             throws java.io.IOException

Reads data from a given stream and returns it as a string.

Parameters:

inputStream - Stream to read from.

Returns:

the data in the stream as a string.

Throws:

java.lang.IllegalArgumentException - if inputStream is null

java.io.IOException - if there is an error reading from the stream.

openStreamToFile

public static java.io.OutputStream openStreamToFile(java.lang.String fileName)
                                             throws DAIFileNotFileException,
                                                    DAIFileWriteIOException

Open an OutputStream for a new file.

Parameters:

fileName - Name of file.

Returns:

OutputStream.

Throws:

DAIFileNotFileException - if the file is not a file e.g. it's a directory.

DAIFileWriteIOException - if there is an IO error when writing the file.

java.lang.IllegalArgumentException - if fileName is null.

closeStreamToFile

public static void closeStreamToFile(java.lang.String fileName,
                                     java.io.OutputStream fileDataStream)
                              throws DAIFileWriteIOException

Close an OutputStream for a file.

Assumes that the OutputStream was created using openStreamToFile()

Parameters:

fileName - Name of file.

fileDataStream - File OutputStream.

Throws:

DAIFileWriteIOException - if there is an IO error when reading the file.

java.lang.IllegalArgumentException - if either argument is null.

renameFile

public static void renameFile(java.lang.String fileName,
                              java.lang.String newFileName)
                       throws DAIFileNotFileException,
                              DAIFileWriteIOException,
                              DAIFileRenameException,
                              DAIFileAlreadyExistsException,
                              DAIFileNotFoundException

Renames a file.

Parameters:

fileName - Name of file to rename.

newFileName - New file name.

Throws:

DAIFileNotFileException - if the specified files are a non-file, for example a directory.

DAIFileNotFoundException - if the specified file is non-existant.

DAIFileRenameException - if the file just didn't rename.

DAIFileWriteIOException - if there is an error renaming the file.

DAIFileAlreadyExistsException - if the file already exists.

java.lang.IllegalArgumentException - if fileName or newFileName is null.

deleteFile

public static void deleteFile(java.lang.String fileName)
                       throws DAIFileNotFileException,
                              DAIFileWriteIOException,
                              DAIFileDeleteException,
                              DAIFileNotFoundException

Deletes a file.

Parameters:

fileName - Name of file to delete.

Throws:

DAIFileDeleteException - if the file just didn't delete.

DAIFileNotFileException - if the specified file is a non-file, for example a directory.

DAIFileNotFoundException - if the specified file does not exist.

DAIFileWriteIOException - if there is an error deleting the file.

java.lang.IllegalArgumentException - if fileName is null.

getFile

public static java.io.File getFile(java.lang.String baseDir,
                                   java.lang.String filename)

Gets the file specified by the given filename and possibly also the given base directory. If the given filename is absolute then the coresponding file is returned, otherwise the given base directory is added to create the filename of the file returned.

Parameters:

baseDir - Absolute path to base directory.

filename - Name of file.

Returns:

the file specified by the filename and base directory.

Throws:

java.lang.IllegalArgumentException - if either argument is null.

replaceTokensInDirectory

public static void replaceTokensInDirectory(java.io.File dir,
                                            java.util.Map tokensAndValues)
                                     throws DAIFileReadIOException,
                                            DAIFileWriteIOException,
                                            DAIDirectoryNotFoundException,
                                            DAIDirectoryNotDirectoryException

Replaces all occurrences of token regular expressions in each file in the specified directory with the corresponding value strings. Sub-directories are also processed.

Parameters:

dir - Directory to process

tokensAndValues - Mappings of token regular expressions to value strings. All occurences of each token regular expression within the file will be replaced by the corresponding value string.

Throws:

DAIDirectoryNotFoundException - if the specified directory is not found.

DAIDirectoryNotDirectoryException - if the specified directory is not actually a directory.

DAIFileReadIOException - if there is an IO error reading a file.

DAIFileWriteIOException - if there is an IO error writing to a file.

java.lang.IllegalArgumentException - if dir or tokensAndValues are null.

replaceTokensInFile

public static void replaceTokensInFile(java.io.File file,
                                       java.util.Map tokensAndValues)
                                throws DAIFileNotFoundException,
                                       DAIFileNotFileException,
                                       DAIFileReadIOException,
                                       DAIFileWriteIOException

Replaces all occurrences of token regular expressions in a file with the corresponding value strings.

Parameters:

file - File to be altered.

tokensAndValues - Mappings of token strings to value strings. All occurences of each token regular expression within the file will be replaced by the corresponding value string.

Throws:

DAIFileNotFoundException - if the file does not exist.

DAIFileNotFileException - if the specified file is not a file, for example it is a directory.

DAIFileReadIOException - if there is an IO error reading a file.

DAIFileWriteIOException - if there is an IO error writing to a file.

java.lang.IllegalArgumentException - if file or tokensAndValues are null.

deleteDir

public static boolean deleteDir(java.io.File dir)

Deletes the given directory and all files and subdirectories below it.

Parameters:

dir - Directory to delete

Returns:

true if the delete is successfull, false otherwise.

Throws:

java.lang.IllegalArgumentException - if dir is null.

deleteDirContents

public static boolean deleteDirContents(java.io.File dir)

Deletes the contents of the directory including all subdirectories. The directory itself will remain undeleted.

Parameters:

dir - Directory whose contents are to be deleted.

Returns:

true if the delete is successfull, false otherwise.

Throws:

java.lang.IllegalArgumentException - if dir is null.

copyFile

public static void copyFile(java.io.File sourceFile,
                            java.io.File destinationFile)
                     throws DAIFileNotFoundException,
                            DAIFileReadIOException,
                            DAIFileWriteIOException,
                            DAIFileNotFileException

Copies the source file to the destination file. If the destination file exists it will be overwritten.

Parameters:

sourceFile - Source file.

destinationFile - Destination file.

Throws:

DAIFileNotFileException - if the source file is not a file e.g. it's a directory.

DAIFileNotFoundException - if the source file cannot be found or the destination file cannot be reached.

DAIFileReadIOException - if there is an IO error when reading from to the source file.

DAIFileWriteIOException - if there is an IO error when writing to the destination file.

java.lang.IllegalArgumentException - if either argument is null.

copyDirectoryContents

public static void copyDirectoryContents(java.io.File sourceDir,
                                         java.io.File destinationDir)
                                  throws DAIDirectoryNotFoundException,
                                         DAIDirectoryNotDirectoryException,
                                         DAIFileReadIOException,
                                         DAIFileWriteIOException

Copies the contents of the source directory to the destination directory. Sub-directories and their contents will also be copied.

Parameters:

sourceDir - Source directory.

destinationDir - Destination directory.

Throws:

DAIDirectoryNotFoundException - if either the source or destination directory cannot be found.

DAIDirectoryNotDirectoryException - if either the source or destination directory is not a directory.

DAIFileWriteIOException - if there is an IO error when writing a file.

DAIFileReadIOException - if there is an IO error when reading a file.

java.lang.IllegalArgumentException - if either argument is null.

fileExists

public static void fileExists(java.io.File file)
                       throws DAIFileNotFoundException

A utility method to test whether a file exists.

Parameters:

file - File to test.

Throws:

DAIFileNotFoundException - if the file does not exist.

fileDoesntExist

public static void fileDoesntExist(java.io.File file)
                            throws DAIFileFoundException

A utility method to test whether a file does not exist.

Parameters:

file - File to test.

Throws:

DAIFileFoundException - if the file exists.

directoryExists

public static void directoryExists(java.io.File dir)
                            throws DAIDirectoryNotFoundException

A utility method to test whether a directory exists.

Parameters:

dir - Directory to test.

Throws:

DAIDirectoryNotFoundException - if the directory does not exist.

directoryDoesntExist

public static void directoryDoesntExist(java.io.File dir)
                                 throws DAIDirectoryFoundException

A utility method to test whether a directory does not exist.

Parameters:

dir - Directory to test.

Throws:

DAIDirectoryFoundException - if the directory exists.

isDirectory

public static void isDirectory(java.io.File file)
                        throws DAIDirectoryNotDirectoryException

A utility method to test whether a given File represents a directory.

Parameters:

file - File to test.

Throws:

DAIDirectoryNotDirectoryException - if file does not represent a directory.

isFileReadable

public static void isFileReadable(java.io.File file)
                           throws DAIFileReadIOException

A utility method to test whether a file is readable.

Parameters:

file - File to test.

Throws:

DAIFileReadIOException - if the file is not readable.

isFileWritable

public static void isFileWritable(java.io.File file)
                           throws DAIFileWriteIOException

A utility method to test whether a file is writable.

Parameters:

file - File to test.

Throws:

DAIFileWriteIOException - if the file is not writable.

isDirectoryReadable

public static void isDirectoryReadable(java.io.File dir)
                                throws DAIDirectoryReadException

A utility method to test whether a directory is readable.

Parameters:

dir - Directory to test.

Throws:

DAIDirectoryReadException - if the file is not readable.