ccl.util
Class FileUtil

java.lang.Object
  |
  +--ccl.util.FileUtil

public class FileUtil
extends java.lang.Object

Utility class for file operations.

Simple but most commonly used methods of this class are:
- readFile
- writeFile
- appendFile
- concatPath
- exists
- existsDir
- existsFile

Other less frequently used but still handy methods are:
- getResourceAsString
- normalizeFileName to take the current user directory into account via the 'user.dir' system property
- deleteRecursively

There are also the standard file operation methods available. Some of these are named for convenience and easy memorization after their Unix counterparts, like mv, rm, mkdir (md), and cp.


Method Summary
static java.util.Vector _getFilteredDirContent(java.lang.String sDir_, java.io.FilenameFilter pFilenameFilter_)
          Deprecated.  
static void appendFile(java.lang.String sFileName_, java.lang.String sAddedContent_)
          Append string to a file content.
static boolean areAllPathsAbsolute(java.lang.String sPathList_)
          Tests if the file represented by this File object is an absolute pathname.
static java.lang.String concatPath(java.lang.String sPath_, java.lang.String sFile_)
          Concatenates a file path with the file name.
static boolean copy(java.io.BufferedInputStream pBufferedInputStream_, java.io.BufferedOutputStream pBufferedOutputStream_)
          Copy content of an buffered input stream into an buffered output stream.
static boolean copy(java.io.InputStream pInputStream_, java.io.OutputStream pOutputStream_)
          Copy content of an input stream into an output stream.
static boolean copy(java.lang.String sSourceFile_, java.lang.String sDestinationFile_)
          Copy file.
static boolean copyDir(java.lang.String sDir_, java.lang.String sDestination_)
          Like: cp -r sDir_ sDestination_ No consideration for links are in place, so be aware of possible infinite loops.
static boolean cp(java.lang.String sSourceFile_, java.lang.String sDestinationFile_)
          Copy file.
static void createBackupFile(java.lang.String sFileName_)
          Copy the specified file to the same location and append ".bak" to its file name.
static java.lang.String createTempDir()
          Unlike 'getTempDir()' which returns something like "/tmp" this method creates a new temporary directory which has no other files inside.
static boolean delete(java.lang.String sFileName_)
          Remove file on file system.
static boolean deleteRecursively(java.lang.String sFileName_)
          Delete file or directory.
static boolean equalsFile(java.lang.String sFileNameA_, java.lang.String sFileNameB_)
          Reads two files and compares them.
static boolean equalsPath(java.lang.String sFirstPath_, java.lang.String sSecondPath_)
          Checks weather two paths point to the same object on the file system.
static boolean exists(java.lang.String sFileOrDirName_)
          True if a specified object on the file system is either a file or a directory.
static boolean existsDir(java.lang.String sDirName_)
          Tests, if a given directory exists.
static boolean existsFile(java.lang.String sFileName_)
          True if a specified file exists.
static java.lang.String getAbsoluteFileName(java.lang.String sFileName_)
           
static java.lang.String getAbsolutePath(java.lang.String sFileName_)
          The same as getAbsoluteFileName(..).
static java.lang.String getAbsolutePathList(java.lang.String sPathList_)
          Converts each path element to an aboslute path and concatenates these again using the platforms path separator character.
static java.lang.String getApplicationHome(java.lang.Object oClass)
          Deprecated. use ClassPathUtil.getApplicationHome instead.
static java.lang.String getBaseFileName(java.lang.String sFileName_)
          Deprecated. use getBaseName.
static java.lang.String getBaseName(java.lang.String sFileName_)
          Get the base name of a file.
static java.lang.String getClassPath(java.lang.Object oClass_)
          Does work only when class exists outside a zip or jar file.
static java.lang.String getClassPath(java.lang.String sFullClassName_)
          Does work only when class exists outside a zip or jar file.
static java.lang.String getDir(java.lang.String sFile_)
          Returns the directory as a string of the given file.
static java.lang.String getDirName(java.lang.String sFileName)
          Equivalent to unix dirname command.
static java.util.Vector getFiles(java.lang.String sDir_)
          Returns a Vector with all files of the given directory.
static java.util.Vector getFiles(java.lang.String sDir_, java.lang.String sSuffix_)
          Returns a Vector with all file names that are inside the specified directory.
static java.util.Vector getFiles(java.lang.String sDir_, java.lang.String sPrefix_, java.lang.String sSuffix_)
          Returns a Vector with all file (and dir) names that are inside the specified directory.
static java.util.Vector getFilteredDirContent(java.lang.String sDir_, java.io.FilenameFilter pFilenameFilter_)
          Returns a Vector with all file names that are inside the specified directory.
static java.lang.String getPackagePath(java.lang.String sPackageName_)
          You give it a package name and it looks with the help of the classpath on the file system if it can find a directory that relates to this package.
static java.lang.String getPackagePath(java.lang.String sPackageName_, java.lang.String sClassPath_)
          You give it a package name and it looks with the help of the classpath on the file system if it can find a directory that relates to this package.
static java.util.Vector getRecursiveDir(java.lang.String sFileName_)
          Be aware that symbolic links might lead to infinite loops.
static java.io.InputStream getResourceAsStream(java.lang.Object pObject_, java.lang.String sRecourceName_)
          There is one big advantage this method has over Class.getResourceAsStream(..).
static java.lang.String getResourceAsString(java.lang.Object pObject_, java.lang.String sRecourceName_)
          There is one big advantage this method has over Class.getResourceAsStream(..).
static java.util.Vector getSubDirs(java.lang.String sDir_)
          Liefert einen Vector mit allen Unter-Directories zur?ck.
static java.lang.String getSwingHome()
          It searchs in the classpath for swingall.jar, then for swing.jar and last for com/sun/java/swing on the file system.
static java.lang.String getTempDir()
          Returns a temporary directory.
static java.lang.String getTempFileName()
          Creates a path with a temp directory plus a 5 digit random file name.
static boolean isAbsolute(java.lang.String sFileName_)
          Tests if the file represented by this File object is an absolute pathname.
static boolean isFileReadable(java.lang.String sFileName_)
          This method checks if it is save to use a file or if for example someone else is currently writing into this file.
static boolean isQuitInStdin()
          Checks if the next word in the standard input stream is quit followed by a linefeed.
static boolean md(java.lang.String sFullDirName)
          Creates the specified directory and if necessary any parent directories.
static boolean mkdir(java.lang.String sFullDirName)
          Creates the specified directory and if necessary any parent directories.
static boolean move(java.lang.String sSource_, java.lang.String sDest_)
          Renames or moves a file.
static boolean mv(java.lang.String sSource_, java.lang.String sDest_)
          Renames or moves a file.
static java.lang.String normalizeFileName(java.lang.String sFile)
          This method returns an absolute (canonical) file name.
static java.lang.String normalizeFileName(java.lang.String sFile, java.lang.String sUserDir)
          This method returns an absolute (canonical) file name.
static java.io.DataInputStream openFile(java.lang.String sFile)
          Get a DataInputStream for a specified file.
static java.io.DataOutputStream openOutputFile(java.lang.String sFile)
          Get a DataOutputStream for a specified file.
static void printAndWaitUntilQuit()
          Prints a user message and reads standard input until someone types 'quit' and <enter>.
static java.lang.Byte[] readBinaryFile(java.lang.String sFileName_)
          Deprecated. Method has no implementation.
static java.lang.String readFile(java.lang.String sFileName_)
          Reads a File and returns the content in a String.
static java.lang.String readFile(java.net.URL location)
          Reads the content of a URL and returns a string.
static java.lang.String readStream(java.io.InputStream stream_)
          Reads a stream, gives back a string.
static boolean rm(java.lang.String sFileName_)
          Remove file on file system.
static void writeDosFile(java.lang.String sFileName_, java.lang.String sContent_)
          Like writeFile but converts LFs to CRLFs.
static void writeFile(java.lang.String sFileName, java.lang.String sContent)
          Writes a String into a given File.
static void writeFileWithBackup(java.lang.String sFileName_, java.lang.String sContent_)
          Writes a String into a given File and does move the old file if existent to sFileName + ".bak".
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

getPackagePath

public static java.lang.String getPackagePath(java.lang.String sPackageName_)
You give it a package name and it looks with the help of the classpath on the file system if it can find a directory that relates to this package.

Returns:
Includes the local path of the package too. If no path could be found, "" is returned.

getPackagePath

public static java.lang.String getPackagePath(java.lang.String sPackageName_,
                                              java.lang.String sClassPath_)
You give it a package name and it looks with the help of the classpath on the file system if it can find a directory that relates to this package.

Todo: what happens with an empty classpath? That should be equivalent to a "." classpath.

Returns:
includes the local path of the package too. If no path could be found, "" is returned.

getClassPath

public static java.lang.String getClassPath(java.lang.Object oClass_)
Does work only when class exists outside a zip or jar file.

Returns:
Includes the local path of the package too.

getClassPath

public static java.lang.String getClassPath(java.lang.String sFullClassName_)
Does work only when class exists outside a zip or jar file.

Returns:
Includes the local path of the package too.

getSwingHome

public static java.lang.String getSwingHome()
It searchs in the classpath for swingall.jar, then for swing.jar and last for com/sun/java/swing on the file system. If user renamed the swing archive, we are out of luck.

Returns:
null or "" if swing was not found in the classpath, otherwise returns the home directory. It's unspecified if the home dir has a separator char at the end.

concatPath

public static java.lang.String concatPath(java.lang.String sPath_,
                                          java.lang.String sFile_)
Concatenates a file path with the file name. If necessary it adds a File.separator between the path and file name. For example "/home" or "/home/" and "clemens" both become "/home/clemens".

This method is inspired from the FrIJDE project out of the gCollins.File.FileTools class.

FrIJDE Homepage: http://amber.wpi.edu/~thethe/Document/Besiex/Java/FrIJDE/

Parameters:
sPath_ - a directory path. Is not allowed to be null.
sFile_ - the base name of a file.
Returns:
sPath_ if sFile_ is empty.

openFile

public static java.io.DataInputStream openFile(java.lang.String sFile)
Get a DataInputStream for a specified file.


openOutputFile

public static java.io.DataOutputStream openOutputFile(java.lang.String sFile)
Get a DataOutputStream for a specified file.


readStream

public static java.lang.String readStream(java.io.InputStream stream_)
                                   throws java.io.IOException,
                                          java.io.FileNotFoundException
Reads a stream, gives back a string.

Throws:
java.io.FileNotFoundException - if file does not exist.
java.io.IOException - if any file operation fails.

readFile

public static java.lang.String readFile(java.lang.String sFileName_)
                                 throws java.io.IOException,
                                        java.io.FileNotFoundException
Reads a File and returns the content in a String. CRLF -> LF conversion takes place. This is a convenience method so you don't need to bother creating a file reader object and closing it after it has been used.

Parameters:
sFileName_ - the name of the file to read.
Returns:
a string with the content of the file but without any CR characters.
Throws:
java.io.FileNotFoundException - if file does not exist.
java.io.IOException - if any file operation fails.

readBinaryFile

public static java.lang.Byte[] readBinaryFile(java.lang.String sFileName_)
Deprecated. Method has no implementation.

Read binary file.


readFile

public static java.lang.String readFile(java.net.URL location)
                                 throws java.net.MalformedURLException,
                                        java.io.IOException
Reads the content of a URL and returns a string. CRLF are converted to LF.

Throws:
java.io.IOException - if any file operation fails.
java.net.MalformedURLException - if given location is wrong.

appendFile

public static void appendFile(java.lang.String sFileName_,
                              java.lang.String sAddedContent_)
                       throws java.io.IOException
Append string to a file content. On unix this is an atomic operation.

Throws:
java.io.IOException - if writing file fails.

writeFile

public static void writeFile(java.lang.String sFileName,
                             java.lang.String sContent)
                      throws java.io.IOException
Writes a String into a given File.

Throws:
java.io.IOException - if writing file fails.

writeFileWithBackup

public static void writeFileWithBackup(java.lang.String sFileName_,
                                       java.lang.String sContent_)
                                throws java.io.IOException
Writes a String into a given File and does move the old file if existent to sFileName + ".bak".

java.io.IOException
See Also:
writeFile(java.lang.String, java.lang.String)

createBackupFile

public static void createBackupFile(java.lang.String sFileName_)
                             throws java.io.IOException
Copy the specified file to the same location and append ".bak" to its file name.

Throws:
java.io.IOException - when creating backup file fails.

writeDosFile

public static void writeDosFile(java.lang.String sFileName_,
                                java.lang.String sContent_)
                         throws java.io.IOException
Like writeFile but converts LFs to CRLFs.

java.io.IOException
See Also:
writeFile(java.lang.String, java.lang.String)

equalsFile

public static boolean equalsFile(java.lang.String sFileNameA_,
                                 java.lang.String sFileNameB_)
Reads two files and compares them. Be carefull, this is not a binary comparison like with unix diff. Instead both files are loaded and compared as strings after CRLF -> LR line conversion has taken place.


existsFile

public static boolean existsFile(java.lang.String sFileName_)
True if a specified file exists.


existsDir

public static boolean existsDir(java.lang.String sDirName_)
Tests, if a given directory exists.


exists

public static boolean exists(java.lang.String sFileOrDirName_)
True if a specified object on the file system is either a file or a directory.


getFilteredDirContent

public static java.util.Vector getFilteredDirContent(java.lang.String sDir_,
                                                     java.io.FilenameFilter pFilenameFilter_)
Returns a Vector with all file names that are inside the specified directory.
For example: FileUtil.getFiles("C:\", ".txt")

Returns:
Not the full path names are returned, just the simple file names.
See Also:
getFiles(java.lang.String, java.lang.String)

_getFilteredDirContent

public static java.util.Vector _getFilteredDirContent(java.lang.String sDir_,
                                                      java.io.FilenameFilter pFilenameFilter_)
Deprecated.  

See Also:
getFilteredDirContent(java.lang.String, java.io.FilenameFilter)

getSubDirs

public static java.util.Vector getSubDirs(java.lang.String sDir_)
Liefert einen Vector mit allen Unter-Directories zur?ck.

Returns:
Es werden nicht die vollen Pfadangaben bei den Sub-Directories angegeben, sondern nur der einfache Name.

getFiles

public static java.util.Vector getFiles(java.lang.String sDir_)
Returns a Vector with all files of the given directory.

Returns:
Not the full path names are returned, only the simple names.

getFiles

public static java.util.Vector getFiles(java.lang.String sDir_,
                                        java.lang.String sSuffix_)
Returns a Vector with all file names that are inside the specified directory.
For example: Util.getFiles("C:\", ".txt")

Parameters:
sSuffix_ - A list of suffixes (separated with the File.pathSeparatorChar) the file names must match. Otherwise they are not selected.
For example: ".gif;.jpg" or ".gif:.jpg" depending on your operating system.
Returns:
Not the full path names are returned, just the simple file names.

getFiles

public static java.util.Vector getFiles(java.lang.String sDir_,
                                        java.lang.String sPrefix_,
                                        java.lang.String sSuffix_)
Returns a Vector with all file (and dir) names that are inside the specified directory.
For example: Util.getFiles("C:\", ".txt")

Parameters:
sPrefix_ - A prefix which each file must have to be returned on the list.
sSuffix_ - A list of suffixes (separated with the File.pathSeparatorChar) the file names must match. Otherwise they are not selected.
For example: ".gif;.jpg" or ".gif:.jpg" depending on your operating system.
Returns:
Not the full path names are returned, just the simple file names.

equalsPath

public static boolean equalsPath(java.lang.String sFirstPath_,
                                 java.lang.String sSecondPath_)
Checks weather two paths point to the same object on the file system.


delete

public static boolean delete(java.lang.String sFileName_)
Remove file on file system.

Returns:
true if error.

rm

public static boolean rm(java.lang.String sFileName_)
Remove file on file system. This is a shortcut for the 'delete' method. Unlike the Unix 'rm' this one also deletes directories, but only empty ones.

Returns:
true if error.
See Also:
delete(java.lang.String), deleteRecursively(java.lang.String)

deleteRecursively

public static boolean deleteRecursively(java.lang.String sFileName_)
Delete file or directory. Do the same to all sub files and directories.

Returns:
true on error.

move

public static boolean move(java.lang.String sSource_,
                           java.lang.String sDest_)
Renames or moves a file. Be aware that the old file at the destination will be deleted without a warning.

Returns:
true if an error occurred. false if sSource_ is not existent.
See Also:
mv(java.lang.String, java.lang.String)

mv

public static boolean mv(java.lang.String sSource_,
                         java.lang.String sDest_)
Renames or moves a file. Be aware that the old file at the destination will be deleted without a warning. This is a shortcut for method 'move'.

Returns:
true if an error occurred. false if sSource_ is not existent.
See Also:
move(java.lang.String, java.lang.String)

md

public static boolean md(java.lang.String sFullDirName)
Creates the specified directory and if necessary any parent directories. It is a shortcut for 'mkdir'.

Returns:
true if an error occured. Note that this is vice versa to the File.mkdirs() behavior.
See Also:
File.mkdirs()

mkdir

public static boolean mkdir(java.lang.String sFullDirName)
Creates the specified directory and if necessary any parent directories.

Returns:
true if an error occured. Note that this is vice versa to the File.mkdirs() behavior.
See Also:
File.mkdirs()

getAbsoluteFileName

public static java.lang.String getAbsoluteFileName(java.lang.String sFileName_)
Returns:
It's the canonical path of sFileName_.

getAbsolutePath

public static java.lang.String getAbsolutePath(java.lang.String sFileName_)
The same as getAbsoluteFileName(..).

Returns:
It's the canonical path of sFileName_.

normalizeFileName

public static java.lang.String normalizeFileName(java.lang.String sFile)
This method returns an absolute (canonical) file name. The difference to getAbsoluteFileName is that this method uses the system property "user.dir" instead of the native system's current directory. This way you get a chance of changing the current directory inside Java and let your program reflect that change.


normalizeFileName

public static java.lang.String normalizeFileName(java.lang.String sFile,
                                                 java.lang.String sUserDir)
This method returns an absolute (canonical) file name. The difference to getAbsoluteFileName is that this method uses the system property sUserDir instead of the native system's current directory. This way you get a chance of changing the current directory inside Java and let your program reflect that change.


getTempFileName

public static java.lang.String getTempFileName()
Creates a path with a temp directory plus a 5 digit random file name. If 5 generated temporary file names are already in use, null is returned.


getTempDir

public static java.lang.String getTempDir()
Returns a temporary directory. This method will be upwards compatible to jdk 1.2. It uses the java property "java.io.tempdir". If this is not set like in jdk 1.1, "user.home" + "/tmp" will be used. If it does not yet exist we take the freedom to create it. If a $HOME/tmp _file_ exists already, it will be deleted!!!


createTempDir

public static java.lang.String createTempDir()
                                      throws java.io.IOException
Unlike 'getTempDir()' which returns something like "/tmp" this method creates a new temporary directory which has no other files inside.

Returns:
the name of the newly created temporary directory.
Throws:
java.io.IOException - if the creation of the temporary directory failed.

isAbsolute

public static boolean isAbsolute(java.lang.String sFileName_)
Tests if the file represented by this File object is an absolute pathname. The definition of an absolute pathname is system dependent. For example, on UNIX, a pathname is absolute if its first character is the separator character. On Windows platforms, a pathname is absolute if its first character is an ASCII '\' or '/', or if it begins with a letter followed by a colon.


areAllPathsAbsolute

public static boolean areAllPathsAbsolute(java.lang.String sPathList_)
Tests if the file represented by this File object is an absolute pathname. The definition of an absolute pathname is system dependent. For example, on UNIX, a pathname is absolute if its first character is the separator character. On Windows platforms, a pathname is absolute if its first character is an ASCII '\' or '/', or if it begins with a letter followed by a colon.


getAbsolutePathList

public static java.lang.String getAbsolutePathList(java.lang.String sPathList_)
Converts each path element to an aboslute path and concatenates these again using the platforms path separator character.

For example: .;C:\jdk1.1.7\lib\classes.zip -> C:\java\projects;C:\jdk1.1.7\lib\classes.zip


getRecursiveDir

public static java.util.Vector getRecursiveDir(java.lang.String sFileName_)
Be aware that symbolic links might lead to infinite loops. The directory itself is always the first element. If sFileName_ doesn't exist an empty vector is returned.

Returns:
Vector with strings of file and directory names.

copyDir

public static boolean copyDir(java.lang.String sDir_,
                              java.lang.String sDestination_)
Like: cp -r sDir_ sDestination_ No consideration for links are in place, so be aware of possible infinite loops.

Returns:
true if any file error has happened.

cp

public static boolean cp(java.lang.String sSourceFile_,
                         java.lang.String sDestinationFile_)
Copy file. If destination directory does not exist, it will be created as well. Shortcut in the Unix style for method 'copy'.

Returns:
true on error.

copy

public static boolean copy(java.lang.String sSourceFile_,
                           java.lang.String sDestinationFile_)
Copy file. If destination directory does not exist, it will be created as well.

Returns:
true on error.

copy

public static boolean copy(java.io.InputStream pInputStream_,
                           java.io.OutputStream pOutputStream_)
Copy content of an input stream into an output stream.

Returns:
error.

copy

public static boolean copy(java.io.BufferedInputStream pBufferedInputStream_,
                           java.io.BufferedOutputStream pBufferedOutputStream_)
Copy content of an buffered input stream into an buffered output stream.

Returns:
error.

getResourceAsStream

public static java.io.InputStream getResourceAsStream(java.lang.Object pObject_,
                                                      java.lang.String sRecourceName_)
There is one big advantage this method has over Class.getResourceAsStream(..). There are three different circumstances from where you want to load a resource, only two work by the default JDK ClassLoader resource location method. First case, your resource file is in the same directory as your class file just on a normal file system. Second case, your resource file is inside a jar file. This both is handled by the normal ClassLoader. But what if you have a src and a classes directory. Then you want your resource file in the src directory tree without the need to copy the resource file over to the classes directory tree. If you stick to the 'classes' and 'src' directory name convention, this method still finds the resource in the src directory.

See Also:
Class.getResourceAsStream(java.lang.String)

getResourceAsString

public static java.lang.String getResourceAsString(java.lang.Object pObject_,
                                                   java.lang.String sRecourceName_)
                                            throws java.io.IOException
There is one big advantage this method has over Class.getResourceAsStream(..). There are three different circumstances from where you want to load a resource, only two work by the default JDK ClassLoader resource location method. First case, your resource file is in the same directory as your class file just on a normal file system. Second case, your resource file is inside a jar file. This both is handled by the normal ClassLoader. But what if you have a src and a classes directory. Then you want your resource file in the src directory tree without the need to copy the resource file over to the classes directory tree. If you stick to the 'classes' and 'src' directory name convention, this method still finds the resource in the src directory.

java.io.IOException
See Also:
Class.getResourceAsStream(java.lang.String)

printAndWaitUntilQuit

public static void printAndWaitUntilQuit()
Prints a user message and reads standard input until someone types 'quit' and <enter>.

Shouldn't this method be in Util and not FileUtil? No, because this is stdio and therefore also file related.


isQuitInStdin

public static boolean isQuitInStdin()
Checks if the next word in the standard input stream is quit followed by a linefeed.


getDir

public static java.lang.String getDir(java.lang.String sFile_)
Returns the directory as a string of the given file.


isFileReadable

public static boolean isFileReadable(java.lang.String sFileName_)
This method checks if it is save to use a file or if for example someone else is currently writing into this file. Warning, this method does not work for ftp. Downloading a file via ftp and checking if it is readable or not results in true, thought we want false. Copied from usenet from Mark Rozas.


getBaseFileName

public static java.lang.String getBaseFileName(java.lang.String sFileName_)
Deprecated. use getBaseName.

Get the base name of a file. This is the name only, without the path information.

Parameters:
sFileName_ - a string with a file name.
Returns:
the name of the file itself, e.g. "foo/README.TXT" -> "README.TXT".

getBaseName

public static java.lang.String getBaseName(java.lang.String sFileName_)
Get the base name of a file. This is the name only, without the path information.

Parameters:
sFileName_ - a string with a file name.
Returns:
the name of the file itself, e.g. "foo/README.TXT" -> "README.TXT".

getDirName

public static java.lang.String getDirName(java.lang.String sFileName)
Equivalent to unix dirname command. Returns the parent of the given file.

Returns:
"." not null when given a base file name.

getApplicationHome

public static java.lang.String getApplicationHome(java.lang.Object oClass)
Deprecated. use ClassPathUtil.getApplicationHome instead.

This method searches in the current classpath for the given object. That class should be either in a jar file which is located inside a lib directory or as a pure class file under a classes directory. The directory containing either the classes or the lib directory will be returned as the applicaton home directory. If this is not found, null is returned.

Parameters:
oClass - An instantiated class which belongs to the application.
Returns:
null if no home directory was found.