anon.util
Class ResourceLoader

java.lang.Object
  extended by anon.util.ResourceLoader

public final class ResourceLoader
extends java.lang.Object

This class loads resources from the file system. It allows to specify resource paths like "dir1/dir2/resource" or "dir1/dir2/" relative to the classpath or the current directory. It allows also for going up directories like "dir1/dir2/../resource" that would be translated to "dir1/resource".

Author:
Rolf Wendolsky

Nested Class Summary
private  class ResourceLoader.ByteArrayInstantiator
          This class is used to get resources as byte arrays.
private  class ResourceLoader.FileTypeInstantiator
          Does not load or instantiate resources but returns the file type of resources.
 
Field Summary
private static java.lang.String DIR_CURRENT
           
private static java.lang.String DIR_UP
           
private static java.lang.String ms_classpath
           
private static java.util.Vector ms_classpathFiles
           
private static java.lang.Object ms_classpathResourceLock
           
private static java.util.Vector ms_classpathResourceTypes
           
private static java.io.File ms_parentResourceFile
           
private static java.lang.String ms_parentResourceFileResourceType
           
private static java.lang.String ms_parentResourceFileResourceURL
           
private static int READ_BUFFER
           
private static java.lang.String RESOURCE_NO_CLASSES_FOUND
           
private static java.lang.String SYSTEM_RESOURCE
           
private static java.lang.String SYSTEM_RESOURCE_ENDSIGN
           
static java.lang.String SYSTEM_RESOURCE_TYPE_FILE
           
static java.lang.String SYSTEM_RESOURCE_TYPE_GENERIC
           
static java.lang.String SYSTEM_RESOURCE_TYPE_JAR
           
static java.lang.String SYSTEM_RESOURCE_TYPE_ZIP
           
 
Constructor Summary
private ResourceLoader()
           
 
Method Summary
private  ResourceLoader.ByteArrayInstantiator createByteArrayInstantiator()
          Returns a new ByteArrayInstantiator.
private  ResourceLoader.FileTypeInstantiator createFileTypeInstantiator()
          Returns a new FileTypeInstantiator.
private static java.lang.String formatResourcePath(java.lang.String a_strRelativeResourcePath)
          Reformats a given resource name in a way it can be easily interpreted by the resource loader methods.
private static java.lang.String getCurrentResourcePath(java.io.File a_currentFile, java.io.File a_topDirectory)
          Gets the relative resource path for the currently parsed file.
private static java.lang.String getCurrentResourcePath(java.util.zip.ZipEntry a_currentEntry)
          Gets the relative resource path for the currently parsed zip entry.
static java.util.Vector getFilesInClassPath()
           
static java.net.URL getResourceURL(java.lang.String a_strRelativeResourcePath)
          Gets the absolute URL to a requested resource if the resource is found in the class path or in the local directory.
private static java.net.URL getResourceURL(java.lang.String a_strRelativeResourcePath, java.util.Vector a_resourceFiles, java.util.Vector a_resourceURLs, java.util.Vector a_resourceTypes)
          Gets the absolute URL to a requested resource if the resource is found in the given resource files.
static byte[] getStreamAsBytes(java.io.InputStream a_iStream)
          Reads a java.io.InputStream into a byte array and closes the stream.
protected static java.io.File getSystemResource(java.lang.String a_systemResource)
          Returns a given a requested system resource as a file.
private static boolean isResourceInSearchPath(java.lang.String a_strCurrentResourcePath, java.lang.String a_strResourceSearchPath, boolean a_bRecursive)
          Tests if the currently parsed resource is in the search path.
static byte[] loadResource(java.lang.String a_strRelativeResourcePath)
          Loads a resource from the classpath or the current directory.
static java.io.InputStream loadResourceAsStream(java.lang.String a_strRelativeResourcePath)
          Loads a resource from the classpath or the current directory.
static java.util.Hashtable loadResources(java.lang.String a_strResourceSearchPath, boolean a_bRecursive)
          Loads resources from the classpath or the current directory and instantiates them as byte arrays.
static java.util.Hashtable loadResources(java.lang.String a_strResourceSearchPath, java.io.File a_directory, boolean a_bRecursive)
          Loads resources from a directory and instantiates them as byte arrays.
static java.util.Hashtable loadResources(java.lang.String a_strResourceSearchPath, java.io.File a_directory, IResourceInstantiator a_instantiator, boolean a_bRecursive)
          Loads resources from a directory and instantiates them as objects of a type defined by the resource instantiator.
protected static void loadResources(java.lang.String a_strResourceSearchPath, java.io.File a_Directory, IResourceInstantiator a_instantiator, boolean a_bRecursive, boolean a_bStopAtFirstResource, java.util.Hashtable a_loadedResources)
          Loads resources from a given directory (simple file, directory or zip file) that are found in the given resource search path and instantiates them as objects of a type defined by the resource instantiator.
static java.util.Hashtable loadResources(java.lang.String a_strResourceSearchPath, IResourceInstantiator a_instantiator, boolean a_bRecursive)
          Loads resources from the classpath or the current directory and instantiates them as objects of a type defined by the resource instantiator.
private static void loadResourcesFromFile(java.lang.String a_strResourceSearchPath, java.io.File a_file, java.io.File a_topDirectory, IResourceInstantiator a_instantiator, java.util.Hashtable a_loadedResources, boolean a_bRecursive, boolean a_bStopAtFirstResource)
          Returns all resources in a directory and the directory itself as Objects if they are resources of the type specified by the ResourceInstantiator.
private static java.util.Vector readFilesFromClasspath(boolean a_bPreventLoop)
          Reads all resources from the classpath and stores them as files.
static java.lang.String replaceFileSeparatorsSystemSpecific(java.lang.String a_filename)
          Interprets a String as a filename and converts its file separators to system specific file separators.
private static byte[] trimByteArray(byte[] a_trimmedArray, int a_maxLength, byte[] a_arrayToAppendTo)
          Trims a byte array in a way that all bytes after the given length a_maxLength are cut off.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

SYSTEM_RESOURCE_TYPE_ZIP

public static final java.lang.String SYSTEM_RESOURCE_TYPE_ZIP
See Also:
Constant Field Values

SYSTEM_RESOURCE_TYPE_JAR

public static final java.lang.String SYSTEM_RESOURCE_TYPE_JAR
See Also:
Constant Field Values

SYSTEM_RESOURCE_TYPE_FILE

public static final java.lang.String SYSTEM_RESOURCE_TYPE_FILE
See Also:
Constant Field Values

SYSTEM_RESOURCE_TYPE_GENERIC

public static final java.lang.String SYSTEM_RESOURCE_TYPE_GENERIC
See Also:
Constant Field Values

SYSTEM_RESOURCE

private static final java.lang.String SYSTEM_RESOURCE
See Also:
Constant Field Values

SYSTEM_RESOURCE_ENDSIGN

private static final java.lang.String SYSTEM_RESOURCE_ENDSIGN
See Also:
Constant Field Values

DIR_UP

private static final java.lang.String DIR_UP
See Also:
Constant Field Values

DIR_CURRENT

private static final java.lang.String DIR_CURRENT
See Also:
Constant Field Values

READ_BUFFER

private static final int READ_BUFFER
See Also:
Constant Field Values

RESOURCE_NO_CLASSES_FOUND

private static final java.lang.String RESOURCE_NO_CLASSES_FOUND
See Also:
Constant Field Values

ms_classpathFiles

private static java.util.Vector ms_classpathFiles

ms_classpathResourceLock

private static java.lang.Object ms_classpathResourceLock

ms_classpathResourceTypes

private static java.util.Vector ms_classpathResourceTypes

ms_parentResourceFile

private static java.io.File ms_parentResourceFile

ms_parentResourceFileResourceURL

private static java.lang.String ms_parentResourceFileResourceURL

ms_parentResourceFileResourceType

private static java.lang.String ms_parentResourceFileResourceType

ms_classpath

private static java.lang.String ms_classpath
Constructor Detail

ResourceLoader

private ResourceLoader()
Method Detail

getFilesInClassPath

public static java.util.Vector getFilesInClassPath()

getStreamAsBytes

public static byte[] getStreamAsBytes(java.io.InputStream a_iStream)
                               throws java.io.IOException
Reads a java.io.InputStream into a byte array and closes the stream. If the stream blocks before the first byte is read this method will block, too, until there are any bytes available for reading.

Parameters:
a_iStream - an InputStream
Returns:
the InputStream as bytes
Throws:
java.io.IOException - if an I/O error occurs

getResourceURL

public static java.net.URL getResourceURL(java.lang.String a_strRelativeResourcePath)
Gets the absolute URL to a requested resource if the resource is found in the class path or in the local directory. Loads a single resource only, therefore directory specifications like "home/dir/" are not allowed.

Parameters:
a_strRelativeResourcePath - the relative path to a resource
Returns:
the absolute URL to the requested resource

loadResourceAsStream

public static java.io.InputStream loadResourceAsStream(java.lang.String a_strRelativeResourcePath)
Loads a resource from the classpath or the current directory. The resource may be contained in an archive (ZIP,JAR) or a directory structure. If the resource could not be found in the classpath, it is loaded from the current directory. Loads a single resource only, therefore directory specifications like "home/dir/" are not allowed.

Parameters:
a_strRelativeResourcePath - a relative filename for the resource
Returns:
the contents of the resource or null if resource could not be loaded

loadResource

public static byte[] loadResource(java.lang.String a_strRelativeResourcePath)
Loads a resource from the classpath or the current directory. The resource may be contained in an archive (ZIP,JAR) or a directory structure. If the resource could not be found in the classpath, it is loaded from the current directory. Loads a single resource only, therefore directory specifications like "home/dir/" are not allowed.

Parameters:
a_strRelativeResourcePath - a relative filename for the resource
Returns:
the contents of the resource or null if resource could not be loaded

loadResources

public static java.util.Hashtable loadResources(java.lang.String a_strResourceSearchPath,
                                                boolean a_bRecursive)
Loads resources from the classpath or the current directory and instantiates them as byte arrays. Resources with the same path name are only loaded from the first source that contains the resource. If the resource search path is a directory, the method returns a Hashtable with all instanciated resources. Otherwise, the Hashtable contains only one element or is empty if no resource was found or no resource could not be instantiated. The resources may be contained in an archive (JAR) or a directory structure. If no resources could be found in the classpath or they could not be instanciated by the given resource instantiator, they are loaded from the current directory. The resource search path is relative to the given directory and may either specify a single resource or, if it ends with a slash "/", a (virtual) directory in the given directory. Therefore a resource search path "/" loads all resources in the specified directory. A resource search path "certificates/" loads all resources in the (virtual) directory certificates .

Parameters:
a_strResourceSearchPath - a relative filename for the resource
a_bRecursive - true if (virtual) subdirectories should be searched for resources; false otherwise (has an effect only for resource paths ending with "/")
Returns:
the contents of the resources as byte arrays or an empty Hashtable if no resource could be loaded

loadResources

public static java.util.Hashtable loadResources(java.lang.String a_strResourceSearchPath,
                                                IResourceInstantiator a_instantiator,
                                                boolean a_bRecursive)
Loads resources from the classpath or the current directory and instantiates them as objects of a type defined by the resource instantiator. Resources with the same path name are only loaded from the first source that contains the resource. If the resource search path is a directory, the method returns a Hashtable with all instanciated resources. Otherwise, the Hashtable contains only one element or is empty if no resource was found or no resource could not be instantiated. The resources may be contained in an archive (JAR) or a directory structure. If no resources could be found in the classpath or they could not be instanciated by the given resource instantiator, they are loaded from the current directory. The resource search path is relative to the given directory and may either specify a single resource or, if it ends with a slash "/", a (virtual) directory in the given directory. Therefore a resource search path "/" loads all resources in the specified directory. A resource search path "certificates/" loads all resources in the (virtual) directory certificates .

Parameters:
a_strResourceSearchPath - a relative filename for the resource
a_instantiator - an object that instantiates the loaded resource
a_bRecursive - true if (virtual) subdirectories should be searched for resources; false otherwise (has an effect only for resource paths ending with "/")
Returns:
the contents of the resource or an empty Hashtable if no resource could be loaded

loadResources

public static java.util.Hashtable loadResources(java.lang.String a_strResourceSearchPath,
                                                java.io.File a_directory,
                                                boolean a_bRecursive)
Loads resources from a directory and instantiates them as byte arrays. If the resource search path is a directory, the method returns a Hashtable with all instanciated resources. Otherwise, the Hashtable contains only one element or is empty if no resource was found or no resource could not be instantiated. The resources may be contained in an archive (JAR) or a directory structure. The resource search path is relative to the given directory and may either specify a single resource or, if it ends with a slash "/", a (virtual) directory in the given directory. Therefore a resource search path "/" loads all resources in the specified directory. A resource search path "certificates/" loads all resources in the (virtual) directory certificates .

Parameters:
a_strResourceSearchPath - a relative filename for the resource
a_directory - a simple file, directory or zip file
a_bRecursive - true if (virtual) subdirectories should be searched for resources; false otherwise (has an effect only for resource paths ending with "/")
Returns:
the contents of the resource or an empty Hashtable if no resource could be loaded

loadResources

public static java.util.Hashtable loadResources(java.lang.String a_strResourceSearchPath,
                                                java.io.File a_directory,
                                                IResourceInstantiator a_instantiator,
                                                boolean a_bRecursive)
Loads resources from a directory and instantiates them as objects of a type defined by the resource instantiator. If the resource search path is a directory, the method returns a Hashtable with all instanciated resources. Otherwise, the Hashtable contains only one element or is empty if no resource was found or no resource could not be instantiated. The resources may be contained in an archive (JAR) or a directory structure. The resource search path is relative to the given directory and may either specify a single resource or, if it ends with a slash "/", a (virtual) directory in the given directory. Therefore a resource search path "/" loads all resources in the specified directory. A resource search path "certificates/" loads all resources in the (virtual) directory certificates .

Parameters:
a_strResourceSearchPath - a relative filename for the resource
a_directory - a simple file, directory or zip file
a_instantiator - an object that instantiates the loaded resource
a_bRecursive - true if (virtual) subdirectories should be searched for resources; false otherwise (has an effect only for resource paths ending with "/")
Returns:
the contents of the resource or an empty Hashtable if no resource could be loaded

replaceFileSeparatorsSystemSpecific

public static java.lang.String replaceFileSeparatorsSystemSpecific(java.lang.String a_filename)
Interprets a String as a filename and converts its file separators to system specific file separators.

Parameters:
a_filename - a generic file name
Returns:
a system specific file name

getSystemResource

protected static java.io.File getSystemResource(java.lang.String a_systemResource)
Returns a given a requested system resource as a file. A system resource is either a zip file or a directory that is specified in the classpath (Property java.class.path ). The resource must be specified with by the following protocol syntax:
ZipFile
:systemresource:/ZIP[id]/+/
File
:systemresource:/FILE[id]/+/
[id] may be an integer specifying the resource's position int the classpath (beginning with 0) or an absolute path containing the requested resource. The end sign '/+/' is optional and marks the end of the [id]. The system resource protocol is only used in old JDKs < 1.2.

Parameters:
a_systemResource - a system resource a String
Returns:
The requested system resource as a file or null if the resource could not be found

loadResources

protected static void loadResources(java.lang.String a_strResourceSearchPath,
                                    java.io.File a_Directory,
                                    IResourceInstantiator a_instantiator,
                                    boolean a_bRecursive,
                                    boolean a_bStopAtFirstResource,
                                    java.util.Hashtable a_loadedResources)
Loads resources from a given directory (simple file, directory or zip file) that are found in the given resource search path and instantiates them as objects of a type defined by the resource instantiator. Resources with the same path name are only loaded once according to the given Hashtable. The resource search path is relative to the given directory and may either specify a single resource or, if it ends with a slash "/", a (virtual) directory in the given directory. Therefore a resource search path "/" loads all resources in the specified directory. A resource search path "certificates/" loads all resources in the (virtual) directory certificates .

Parameters:
a_strResourceSearchPath - a (virtual) path in the directory to load resources from
a_Directory - a simple file, directory or zip file
a_instantiator - a ResourceInstantiator that is used to instantiate the loaded resources
a_bRecursive - true if (virtual) subdirectories should be searched for resources; false otherwise (has an effect only for resource paths ending with "/")
a_bStopAtFirstResource - true if the search should stop with the first loaded resource; false otherwise
a_loadedResources - a Hashtable where the loaded and instantiated resources are stored

loadResourcesFromFile

private static void loadResourcesFromFile(java.lang.String a_strResourceSearchPath,
                                          java.io.File a_file,
                                          java.io.File a_topDirectory,
                                          IResourceInstantiator a_instantiator,
                                          java.util.Hashtable a_loadedResources,
                                          boolean a_bRecursive,
                                          boolean a_bStopAtFirstResource)
                                   throws IResourceInstantiator.ResourceInstantiationException
Returns all resources in a directory and the directory itself as Objects if they are resources of the type specified by the ResourceInstantiator.

Parameters:
a_strResourceSearchPath - the (virtual) path in the file to load resources from
a_file - a resource file or directory
a_topDirectory - the directory where all other files and directories reside
a_instantiator - an object that instantiates the loaded resource
a_loadedResources - a Vector where the loaded and instantiated resources are stored
a_bRecursive - true if subdirectories should be visited; false otherwise
a_bStopAtFirstResource - true if the search should stop with the first loaded resource; false otherwise
Throws:
ResourceInstantiator.ResourceInstantiationException - if the ResourceInstantiator has become invalid because of too many errors
IResourceInstantiator.ResourceInstantiationException

getResourceURL

private static java.net.URL getResourceURL(java.lang.String a_strRelativeResourcePath,
                                           java.util.Vector a_resourceFiles,
                                           java.util.Vector a_resourceURLs,
                                           java.util.Vector a_resourceTypes)
Gets the absolute URL to a requested resource if the resource is found in the given resource files. In addition to the resource files, the absolute URLs and file types of the resource files must be given. If the correct values are unknown, the must be replaced by "null".

Parameters:
a_strRelativeResourcePath - the relative path to a resource
a_resourceFiles - the resource files
a_resourceURLs - the absolute URLs to the resource files
a_resourceTypes - the file types of the resource files, either SYSTEM_RESOURCE_TYPE_ZIP or SYSTEM_RESOURCE_TYPE_FILE
Returns:
URL

getCurrentResourcePath

private static java.lang.String getCurrentResourcePath(java.io.File a_currentFile,
                                                       java.io.File a_topDirectory)
Gets the relative resource path for the currently parsed file.

Parameters:
a_currentFile - the currently parsed file
a_topDirectory - the top directory in that this file resides; the resource path is given relative to this directory
Returns:
the relative resource path

getCurrentResourcePath

private static java.lang.String getCurrentResourcePath(java.util.zip.ZipEntry a_currentEntry)
Gets the relative resource path for the currently parsed zip entry.

Parameters:
a_currentEntry - the currently parsed zip entry
Returns:
the relative resource path

isResourceInSearchPath

private static boolean isResourceInSearchPath(java.lang.String a_strCurrentResourcePath,
                                              java.lang.String a_strResourceSearchPath,
                                              boolean a_bRecursive)
Tests if the currently parsed resource is in the search path.

Parameters:
a_strCurrentResourcePath - the currently parsed resource
a_strResourceSearchPath - the resource search path
a_bRecursive - true if subdirectories should be visited; false otherwise
Returns:
true if the current resource path is in the search path; false otherwise

formatResourcePath

private static java.lang.String formatResourcePath(java.lang.String a_strRelativeResourcePath)
Reformats a given resource name in a way it can be easily interpreted by the resource loader methods. The resulting paths are either null or of the form "dir1/dir2/resource", "dir1/dir2/" or "/". All other cases, including going up directory trees by inserting "../", are handled by this method and transformed to one of the four defined forms.

Parameters:
a_strRelativeResourcePath - the relative path to a resource
Returns:
the formatted file name or null if the file name is illegal

trimByteArray

private static byte[] trimByteArray(byte[] a_trimmedArray,
                                    int a_maxLength,
                                    byte[] a_arrayToAppendTo)
Trims a byte array in a way that all bytes after the given length a_maxLength are cut off. Afterwards, a new byte array is constructed with the bytes from the given a_arrayToAppendTo and the trimmed array. If a_maxLength is smaller than or equal to zero a reference to a_arrayToAppendTo is returned.

Parameters:
a_trimmedArray - the byte array to trim
a_maxLength - the maximum length of the trimmed byte array
a_arrayToAppendTo - the array to append the trimmed byte array to
Returns:
the concatenated array

readFilesFromClasspath

private static java.util.Vector readFilesFromClasspath(boolean a_bPreventLoop)
Reads all resources from the classpath and stores them as files. The method does nothing if the classpath has not changed since the last call.

Parameters:
a_bPreventLoop - set true in case there may be an endless loop by calling ClassUtil.getClassPath()
Returns:
all resources from the classpath as files

createByteArrayInstantiator

private ResourceLoader.ByteArrayInstantiator createByteArrayInstantiator()
Returns a new ByteArrayInstantiator. This method is needed due to static centext restrictions.

Returns:
a new ByteArrayInstantiator

createFileTypeInstantiator

private ResourceLoader.FileTypeInstantiator createFileTypeInstantiator()
Returns a new FileTypeInstantiator. This method is needed due to static centext restrictions.

Returns:
a new FileTypeInstantiator