anon.util
Class ResourceLoader

java.lang.Object
  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