com.antelmann.io
Class MyFile

java.lang.Object
  java.io.File
      com.antelmann.io.MyFile

All Implemented Interfaces:

Serializable, Comparable<File>

Direct Known Subclasses:

ServerLogFile

public class MyFile
extends File

A specialized File class that provides some additional functionality. MyFile adds no members to class File, only methods.

Since:

3/23/2002

Author:

Holger Antelmann

See Also:

Serialized Form

Field Summary

Fields inherited from class java.io.File

pathSeparator, pathSeparatorChar, separator, separatorChar

Constructor Summary

MyFile(File file)

MyFile(File parent, String child)

MyFile(String pathname)

MyFile(String parent, String child)

MyFile(URI uri)

Method Summary

void	append(File file) appends the content of the given file to this file
void	clear() deletes the content of the file
boolean	compareContent(File file) returns true only if both files have the exact same content
boolean	compareContent(long beginIndexThisFile, File otherFile, long beginIndexOtherFile, long maxBytes) returns true only if both files have the exact same content beginning at beginIndex and up to maxBytes number of bytes.
MyFile	compress(boolean deleteOriginal) compresses the file using gzip to a file named by adding the type gz to the original name.
void	compressTo(File file) writes a gzip compressed file that can be uncompressed to its original form using uncompressTo(File).
void	copyTo(File destinationFile) copies this file to the given destination file.
void	copyTo(File destinationFile, byte[] searchPattern, byte[] replacePattern) copies this file to the given destination file while searchPattern is replaced with replacePattern
int	count(byte[] pattern) returns how many times the given byte pattern occurs within the file
static MyFile	createTempDir(String prefix, String suffix) creates a new empty directory in the default temporary-file directory, using the given prefix and suffix to generate its name.
static MyFile	createTempDir(String prefix, String suffix, File dir) creates a new empty directory in the given dir, using the given prefix and suffix to generate its name.
void	decrypt(String password) uses a com.antelmann.util.CipherKey
String	digestMD5() returns a digest that can be used to verity the content of a file
String	digestSHA1() returns a digest that can be used to verity the content of a file
void	directoryCompare(File dir, PrintStream ps) compares this directory with the given one and prints results to the given stream
void	directoryCompare(File dir, PrintStream ps, Monitor monitor)
void	encrypt(String password) uses a com.antelmann.util.CipherKey
MyFile	ensureExtension(String extension) returns a file that has the given file extension based on this file.
String	fileCompareText(File file) returns a text describing as to how this file compares to the given file
String	fileCompareText(long beginIndexThisFile, File otherFile, long beginIndexOtherFile, long maxBytes) returns a text describing as to how this file compares to the given file
byte[]	getContentAsBytes() returns the entire file content as a byte array.
String	getContentAsString() returns the entire file content as a String (using default encoding).
String	getContentAsString(String charsetName) returns the entire file content as a String.
String	getContentAsUTF8()
String	getFileExtension() returns the lower-case file type denoted by its file extension.
MyFile	getFileRelativeTo(File dir) returns the file as a relative reference from the given directory.
static String[]	getFileTypes(File[] file) returns the different file extensions that occur in the given array
String	getNameWithoutExtension() returns the file name without the type extension
static MyFile	getWorkingDir()
boolean	hasParent(File dir) returns true only if this MyFile is in the given dir (or sub-dir)
long	indexOf(byte[] pattern) returns the index of the beginning of the given pattern within the file (beginning the search at beginIndex) or -1
long	indexOf(byte[] pattern, int beginIndex) returns the index of the beginning of the given pattern within the file (beginning the search at beginIndex) or -1
int	indexOf(String pattern) returns the index within the content of this file of the first occurrence of the specified pattern; -1 is returned if pattern is not found.
long	length() in case of a directory, the combined size of all files within the tree is returned; otherwise the file size.
MyFile[]	listFilesInTree() returns all files including those in subdirectories recursively
MyFile[]	listFilesInTree(FileFilter filter)
MyFile[]	listFilesInTree(FilenameFilter filter)
File[]	listSubDirs() assuming the current MyFile is a directory, all sub-directories are returned.
Object	loadObject() calls loadObject(false)
Object	loadObject(boolean useDeserialization) loads a single object from the file into memory and returns it.
Properties	loadProperties()
Enumeration	objectEnumerator() returns an Enumeration over the objects contained in this binary file with serialized objects written with an ObjectOutputStream
Enumeration	objectEnumerator(boolean useDeserialization) returns an Enumeration over the objects contained in this binary file with serialized objects written with an ObjectOutputStream.
Enumeration	objectEnumerator(boolean useDeserialization, Logger exceptionLogger) convenience method
boolean	removeTree(boolean includingThisRoot) If the MyFile at hand is a directory, this method attempts to delete the entire subtree; therefore use it with caution!
void	replace(byte[] searchPattern, byte[] replacePattern) searches for the first pattern and replaces all occurrences with the second pattern.
void	replace(String searchPattern, String replacePattern) searches for the first pattern and replaces all occurrences with the second pattern (no regular expressions used).
void	storeProperties(Properties props, String comment)
MyFile[]	synchronizeDir(File destinationDir) Assuming the current MyFile is a directory, this method synchronizes it with the destination directory by writing all files into the destination directory that exist in the origin directory.
MyFile[]	synchronizeDir(File destinationDir, FileFilter filter) synchronizes only those files that are accepted by the filter
MyFile[]	synchronizeDir(File destinationDir, FileFilter filter, Logger logger, Monitor monitor)
MyFile[]	synchronizeDir(File destinationDir, Logger logger) This method allows for intermediate feedback through the logger; otherwise it's the same as the other synchronizeDir() method.
MyFile[]	synchronizeDir(File destinationDir, Logger logger, Monitor monitor) This method allows for intermediate feedback and interactive stopping; otherwise it's the same as the other synchronizeDir() method.
boolean	touch() returns setLastModified(System.currentTimeMillis()) after possibly creating the file if it didn't exist before.
void	uncompress(boolean deleteCompressedFile) assuming the file is a *.gz file, it will be uncompressed to the same file w/o the gz extension.
void	uncompressTo(File file) restores a gzip compressed file written with compressTo(File).
void	unzipTo(File directory) calls unzipTo(directory, true)
void	unzipTo(File directory, boolean overwriteExistingFiles)
void	unzipTo(File directory, boolean overwriteExistingFiles, Monitor monitor)
void	unzipTo(File directory, FileFilter filter, Monitor monitor) allows to react individually per file on whether to unzip it or nor
void	writeBytes(byte[] bytes, boolean append) writes the given bytes directly to the file and flushes; if append is false, all previous content will be overwritten.
void	writeln() appends a platform specific linebreak into a text file
void	writeObject(Object obj, boolean append) serializes the given object, writes it to the file and flushes.
boolean	writeStackTrace(Thread t, Throwable e, boolean append) prints the stack trace of the given Throwable to a PrintWriter.
void	writeStackTrace(Throwable t, boolean append) prints the stack trace of the given Throwable
void	writeText(String text, boolean append) writes the given text to the file and flushes; if append is false, all previous content will be overwritten.
void	writeUTF8(String text, boolean append) writes the given text encoded as UTF8
void	zipTo(File file) zips either this file this directory three to the given file
void	zipTo(File file, FileFilter filter, String comment, Monitor monitor) only the file parameter must not be null
void	zipTo(File file, String comment, Monitor monitor)

Methods inherited from class java.io.File

canRead, canWrite, compareTo, createNewFile, createTempFile, createTempFile, delete, deleteOnExit, equals, exists, getAbsoluteFile, getAbsolutePath, getCanonicalFile, getCanonicalPath, getName, getParent, getParentFile, getPath, hashCode, isAbsolute, isDirectory, isFile, isHidden, lastModified, list, list, listFiles, listFiles, listFiles, listRoots, mkdir, mkdirs, renameTo, setLastModified, setReadOnly, toString, toURI, toURL

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

MyFile

public MyFile(File file)

MyFile

public MyFile(String pathname)

MyFile

public MyFile(String parent,
              String child)

MyFile

public MyFile(File parent,
              String child)

MyFile

public MyFile(URI uri)

Method Detail

touch

public boolean touch()
              throws IOException

returns setLastModified(System.currentTimeMillis()) after possibly creating the file if it didn't exist before.

Throws:

IOException

clear

public void clear()
           throws IOException

deletes the content of the file

Throws:

IOException

getWorkingDir

public static MyFile getWorkingDir()

length

public long length()

in case of a directory, the combined size of all files within the tree is returned; otherwise the file size.

Overrides:

length in class File

digestMD5

public String digestMD5()
                 throws IOException

returns a digest that can be used to verity the content of a file

Throws:

IOException

See Also:

Data.digestMD5(java.io.InputStream), Strings.hexString(byte...)

digestSHA1

public String digestSHA1()
                  throws IOException

returns a digest that can be used to verity the content of a file

Throws:

IOException

See Also:

Data.digestSHA1(java.io.InputStream), Strings.hexString(byte...)

createTempDir

public static MyFile createTempDir(String prefix,
                                   String suffix)
                            throws IOException

creates a new empty directory in the default temporary-file directory, using the given prefix and suffix to generate its name.

Throws:

IOException

See Also:

File.createTempFile(String, String, File)

createTempDir

public static MyFile createTempDir(String prefix,
                                   String suffix,
                                   File dir)
                            throws IOException

creates a new empty directory in the given dir, using the given prefix and suffix to generate its name.

Throws:

IOException

See Also:

File.createTempFile(String, String, File)

ensureExtension

public MyFile ensureExtension(String extension)

returns a file that has the given file extension based on this file. The extension is only added if it didn't already apply to this file.

Parameters:

extension - a file extension (without the dot), i.e. "txt" for "*.txt"-files

Returns:

either this file (if the given file extension already applies to this file) or a new file where the given extension was added

getFileExtension

public String getFileExtension()

returns the lower-case file type denoted by its file extension. The extension is the String of those characters that follow the last 'dot' (".") in the file name in lowercase. If no extension is present, null is returned.

getNameWithoutExtension

public String getNameWithoutExtension()

returns the file name without the type extension

hasParent

public boolean hasParent(File dir)

returns true only if this MyFile is in the given dir (or sub-dir)

getFileRelativeTo

public MyFile getFileRelativeTo(File dir)

returns the file as a relative reference from the given directory. The given directory should be a parent of the file at hand; if not, the absolute file path is returned.

listSubDirs

public File[] listSubDirs()

assuming the current MyFile is a directory, all sub-directories are returned.

listFilesInTree

public MyFile[] listFilesInTree()

returns all files including those in subdirectories recursively

listFilesInTree

public MyFile[] listFilesInTree(FileFilter filter)

listFilesInTree

public MyFile[] listFilesInTree(FilenameFilter filter)

copyTo

public void copyTo(File destinationFile)
            throws IOException

copies this file to the given destination file. The last modified time of the copied file will be set equal to the original file. The read-only attribute is NOT applied to the copied file even if the original file was read-only.

Throws:

IOException

copyTo

public void copyTo(File destinationFile,
                   byte[] searchPattern,
                   byte[] replacePattern)
            throws IOException

copies this file to the given destination file while searchPattern is replaced with replacePattern

Throws:

IOException

compareContent

public boolean compareContent(File file)
                       throws IOException

returns true only if both files have the exact same content

Throws:

IOException

compareContent

public boolean compareContent(long beginIndexThisFile,
                              File otherFile,
                              long beginIndexOtherFile,
                              long maxBytes)
                       throws IOException

returns true only if both files have the exact same content beginning at beginIndex and up to maxBytes number of bytes.

Parameters:

maxBytes - if 0, the entire content is compared to EOF

Throws:

IOException

fileCompareText

public String fileCompareText(File file)
                       throws IOException

returns a text describing as to how this file compares to the given file

Throws:

IOException

fileCompareText

public String fileCompareText(long beginIndexThisFile,
                              File otherFile,
                              long beginIndexOtherFile,
                              long maxBytes)
                       throws IOException

returns a text describing as to how this file compares to the given file

Throws:

IOException

directoryCompare

public void directoryCompare(File dir,
                             PrintStream ps)
                      throws IOException

compares this directory with the given one and prints results to the given stream

Throws:

IOException

directoryCompare

public void directoryCompare(File dir,
                             PrintStream ps,
                             Monitor monitor)
                      throws IOException

Throws:

IOException

synchronizeDir

public MyFile[] synchronizeDir(File destinationDir)
                        throws IOException

Assuming the current MyFile is a directory, this method synchronizes it with the destination directory by writing all files into the destination directory that exist in the origin directory.

The procedure follows the follwing rules:

• All files that only exist in the first directory, will be copied over
• If a file already exists at the destination, it will only be overwritten if it is more recent or if the length is different
• Files at the destination that do not exist at the origin will be deleted
• The above will be performed recursively for each subdirectory

Note that file attributes are ignored, i.e. if a file is copied, the default attributes are kept and may be different from those of the originating file. If a directory is to be removed in the destination dir, the method makes a best effort to do so.

Returns:

array of files that could not be copied or deleted; if no errors occurred, this array would be empty

Throws:

IllegalArgumentException - if either the current MyFile or the given destination are not directories

IOException

synchronizeDir

public MyFile[] synchronizeDir(File destinationDir,
                               FileFilter filter)
                        throws IOException

synchronizes only those files that are accepted by the filter

Throws:

IOException

synchronizeDir

public MyFile[] synchronizeDir(File destinationDir,
                               Logger logger)
                        throws IOException

This method allows for intermediate feedback through the logger; otherwise it's the same as the other synchronizeDir() method.

This method allows e.g. GUIs to display status messages by implementing a special LogWriter.
The given logger may be null, otherwise its usage is as follows:

• Every processed directory produces a level Level.FINE message naming the given directory
• Every copied/deleted file produces a level Level.FINER message naming the file
• Every unsuccessfull copy/delete operation produces a level Level.WARNING message naming the file/directory and containing the IOException as a parameter

Returns:

array of files that could not be copied or deleted; if no errors occurred, this array would be empty

Throws:

IOException

See Also:

synchronizeDir(File), Backup

synchronizeDir

public MyFile[] synchronizeDir(File destinationDir,
                               Logger logger,
                               Monitor monitor)
                        throws IOException

This method allows for intermediate feedback and interactive stopping; otherwise it's the same as the other synchronizeDir() method.

This method allows monitoring threads to abort the synchronization by disabling the given monitor during processing. The monitor/logger may be null; monitor checks occur for each directory and after each copy operation - right after the logger was called to log the operation.

Returns:

array of files that could not be copied or deleted; if no errors occurred, this array would be empty

Throws:

IOException

See Also:

synchronizeDir(File, Logger), Backup

synchronizeDir

public MyFile[] synchronizeDir(File destinationDir,
                               FileFilter filter,
                               Logger logger,
                               Monitor monitor)
                        throws IOException

Throws:

IOException

removeTree

public boolean removeTree(boolean includingThisRoot)

If the MyFile at hand is a directory, this method attempts to delete the entire subtree; therefore use it with caution!

If the MyFile is not a directory, false is returned immediately (nothing gets deleted). If it is a directory but it is not empty, it will attempt to first delete all content recursively and then again the top directory. The method makes an effort to delete every file/directory; if the removal of a file or directory fails, it still tries to delete the rest.

Parameters:

includingThisRoot - if true, this directory is deleted along with the sub-tree

Returns:

true only if MyFile is a directory and the entire subtree was successfully removed

indexOf

public int indexOf(String pattern)
            throws IOException,
                   OutOfMemoryError

returns the index within the content of this file of the first occurrence of the specified pattern; -1 is returned if pattern is not found. This method is to be used with smaller/medium sized text files; the entire file must fit into memory.

Throws:

OutOfMemoryError - if the file doesn't fit into memory

IOException

indexOf

public long indexOf(byte[] pattern)
             throws IOException

returns the index of the beginning of the given pattern within the file (beginning the search at beginIndex) or -1

Throws:

IOException

indexOf

public long indexOf(byte[] pattern,
                    int beginIndex)
             throws IOException

returns the index of the beginning of the given pattern within the file (beginning the search at beginIndex) or -1

Throws:

IOException

count

public int count(byte[] pattern)
          throws IOException

returns how many times the given byte pattern occurs within the file

Throws:

IOException

replace

public void replace(String searchPattern,
                    String replacePattern)
             throws IOException,
                    OutOfMemoryError

searches for the first pattern and replaces all occurrences with the second pattern (no regular expressions used). This method is to be used with smaller/medium sized text files; the entire file must fit into memory (twice, actually).

Throws:

OutOfMemoryError - if the file doesn't fit into memory

IOException

replace

public void replace(byte[] searchPattern,
                    byte[] replacePattern)
             throws IOException

searches for the first pattern and replaces all occurrences with the second pattern. Uses a temp file for the replacement; data is then copied back to the original file

Throws:

IOException

getContentAsString

public String getContentAsString()
                          throws IOException,
                                 OutOfMemoryError

returns the entire file content as a String (using default encoding). This method is better to be used with smaller/medium sized text files; the entire file must fit into memory.

Throws:

OutOfMemoryError - if the file doesn't fit into memory

IOException

See Also:

getContentAsBytes()

getContentAsString

public String getContentAsString(String charsetName)
                          throws IOException,
                                 OutOfMemoryError

returns the entire file content as a String. This method is better to be used with smaller/medium sized text files; the entire file must fit into memory.

Throws:

OutOfMemoryError - if the file doesn't fit into memory

IOException

See Also:

getContentAsBytes()

getContentAsBytes

public byte[] getContentAsBytes()
                         throws IOException,
                                OutOfMemoryError

returns the entire file content as a byte array. This method is better to be used with smaller/medium sized binary files; the entire file must fit into memory.

Throws:

OutOfMemoryError - if the file doesn't fit into memory

IOException

See Also:

getContentAsString()

append

public void append(File file)
            throws IOException

appends the content of the given file to this file

Throws:

IOException

writeText

public void writeText(String text,
                      boolean append)
               throws IOException

writes the given text to the file and flushes; if append is false, all previous content will be overwritten. Suitable for text files only

Throws:

IOException

See Also:

writeObject(Object, boolean)

writeln

public void writeln()
             throws IOException

appends a platform specific linebreak into a text file

Throws:

IOException

writeBytes

public void writeBytes(byte[] bytes,
                       boolean append)
                throws IOException

writes the given bytes directly to the file and flushes; if append is false, all previous content will be overwritten. Suitable for binary files.

Throws:

IOException

See Also:

writeObject(Object, boolean)

writeObject

public void writeObject(Object obj,
                        boolean append)
                 throws IOException

serializes the given object, writes it to the file and flushes. Use with binary files only. Note: appending different objects to an existing file may result into ClassCastException in ObjectInputStream when reading back from the file; one solution is to simply write byte arrays as objects that contain the already serialized object.

Throws:

IOException

See Also:

writeText(String, boolean), writeBytes(byte[], boolean), Data.serialize(java.lang.Object)

writeStackTrace

public void writeStackTrace(Throwable t,
                            boolean append)
                     throws FileNotFoundException

prints the stack trace of the given Throwable

Throws:

FileNotFoundException

writeStackTrace

public boolean writeStackTrace(Thread t,
                               Throwable e,
                               boolean append)
                        throws FileNotFoundException

prints the stack trace of the given Throwable to a PrintWriter.

Returns:

true only if the stack was successfully written.

Throws:

FileNotFoundException

writeUTF8

public void writeUTF8(String text,
                      boolean append)
               throws IOException

writes the given text encoded as UTF8

Throws:

IOException

getContentAsUTF8

public String getContentAsUTF8()
                        throws IOException

Throws:

IOException

compressTo

public void compressTo(File file)
                throws IOException

writes a gzip compressed file that can be uncompressed to its original form using uncompressTo(File).

Throws:

IOException

See Also:

uncompressTo(File)

uncompress

public void uncompress(boolean deleteCompressedFile)
                throws IOException,
                       IllegalArgumentException

assuming the file is a *.gz file, it will be uncompressed to the same file w/o the gz extension.

Throws:

IOException

IllegalArgumentException

uncompressTo

public void uncompressTo(File file)
                  throws IOException

restores a gzip compressed file written with compressTo(File).

Throws:

IOException

See Also:

compressTo(File)

compress

public MyFile compress(boolean deleteOriginal)
                throws IOException

compresses the file using gzip to a file named by adding the type gz to the original name.

Parameters:

deleteOriginal - if true, the uncompressed original file will be deleted

Returns:

the compressed file

Throws:

IOException

loadObject

public Object loadObject()
                  throws IOException,
                         ClassNotFoundException

calls loadObject(false)

Throws:

IOException

ClassNotFoundException

loadObject

public Object loadObject(boolean useDeserialization)
                  throws IOException,
                         ClassNotFoundException

loads a single object from the file into memory and returns it.

Parameters:

useDeserialization - if true, this method attepts deserialization on byte arrays

Throws:

IOException

ClassNotFoundException

loadProperties

public Properties loadProperties()
                          throws IOException

Throws:

IOException

storeProperties

public void storeProperties(Properties props,
                            String comment)
                     throws IOException

Throws:

IOException

encrypt

public void encrypt(String password)
             throws IOException

uses a com.antelmann.util.CipherKey

Throws:

IOException

decrypt

public void decrypt(String password)
             throws IOException

uses a com.antelmann.util.CipherKey

Throws:

IOException

objectEnumerator

public Enumeration objectEnumerator()
                             throws IOException

returns an Enumeration over the objects contained in this binary file with serialized objects written with an ObjectOutputStream

Throws:

IOException

See Also:

writeObject(Object, boolean), ObjectEnumerator

objectEnumerator

public Enumeration objectEnumerator(boolean useDeserialization)
                             throws IOException

returns an Enumeration over the objects contained in this binary file with serialized objects written with an ObjectOutputStream.

Parameters:

useDeserialization - specifies whether - in case the object to be returned is a byte[] - automatic deserialization should be used. If the deserialization fails, a byte[] is always returned if present.

Throws:

IOException

See Also:

writeObject(Object, boolean), Data.deserialize(byte[]), ObjectEnumerator

objectEnumerator

public Enumeration objectEnumerator(boolean useDeserialization,
                                    Logger exceptionLogger)
                             throws IOException

convenience method

Throws:

IOException

See Also:

ObjectEnumerator

zipTo

public void zipTo(File file)
           throws IOException

zips either this file this directory three to the given file

Throws:

IOException

zipTo

public void zipTo(File file,
                  String comment,
                  Monitor monitor)
           throws IOException

Throws:

IOException

zipTo

public void zipTo(File file,
                  FileFilter filter,
                  String comment,
                  Monitor monitor)
           throws IOException

only the file parameter must not be null

Throws:

IOException

unzipTo

public void unzipTo(File directory)
             throws IOException

calls unzipTo(directory, true)

Throws:

IOException

unzipTo

public void unzipTo(File directory,
                    boolean overwriteExistingFiles)
             throws IOException

Throws:

IOException

unzipTo

public void unzipTo(File directory,
                    boolean overwriteExistingFiles,
                    Monitor monitor)
             throws IOException

Throws:

IOException

unzipTo

public void unzipTo(File directory,
                    FileFilter filter,
                    Monitor monitor)
             throws IOException

allows to react individually per file on whether to unzip it or nor

Throws:

IOException

getFileTypes

public static String[] getFileTypes(File[] file)

returns the different file extensions that occur in the given array