EAF 7.6 Util

com.lutris.classloader
Class MultiClassLoader

java.lang.Object
  extended by java.lang.ClassLoader
      extended by com.lutris.classloader.MultiClassLoader

public class MultiClassLoader
extends java.lang.ClassLoader

Summary:

A class loader that can load classes from class files and zip files residing in a specified class path.

This class loader can also load resources that reside on the class path and return them as is, as input streams, or as byte arrays.

Features:

Class Path

If classes are to be loaded from a class path, it must be set by the setClassPath or addClassPath methods or by the constructor prior to calling loadClass. If the class path is not set, the class will be loaded with the system class loader.

The class path can consist of directories, files, and/or URLs.

Example valid class path entries are:

     Files and directories on the local file system
     ../../java/classes
     /users/kristen/java/classes
     /users/kristen/java/classes/
     /users/kristen/java/zipfiles/MyClasses.zip
     /users/kristen/java/jarfiles/MyClasses.jar
     file:///users/kristen/java/classes
     file://localhost/users/kristen/java/classes
     
Files and directories on a remote file system (must be in URL format) ftp://www.foo.com/pub/java/classes file://www.foo.com/pub/java/classes/ http://www.foo.com/web/java/classes/ file://www.foo.com:8080/pub/java/zipfiles/MyClasses.zip http://www.foo.com:8080/web/java/jarfiles/MyClasses.jar

Note that the location of the entry includes the protocol, the host name, and the port while the file name is everything else. For example,

     http://www.foo.com:8080/web/java/jarfiles/MyClasses.jar
 
has the form [location][name] or
     [http://www.foo.com:8080/][/web/java/jarfiles/MyClasses.jar]
 
so the location is "http://www.foo.com:8080/" and the name is "/web/java/jarfiles/MyClasses.jar".

Note that the two references

     /users/kristen/java/classes/
     file:///users/kristen/java/classes/
 
represent the same directory on a Unix machine, and
     C|/windows/java/classes/
     file:///C|/windows/java/classes/
 
are equivalent directories on a Windows box.

But the two references

     /users/kristen/java/classes/
     file://monet.lutris.com/users/kristen/java/classes/
 
are not equivalent even if the directory /users/kristen/java/classes/ lives on the machine named monet.lutris.com and all development is on this machine. Why? Because the web (browser?) protocol is different for URLs with host information and those without. If no host is specified, the file is assumed to be on the local machine and the path is determined from the ROOT of the machine. If the host is specified, then the ftp protocol is used and the path is determined from the ftp ROOT (e.g. /users/ftp/) rather than the machine's ROOT. Thus, on a machine that support's anonymous ftp, the following two directories are the same:
     /users/ftp/pub/classes/
     file://picasso.lutris.com/pub/classes/
 
assuming the development is being done on picasso.lutris.com.

System Class Path

The system class path is the system-dependent path of directories and files (e.g. CLASSPATH on Unix and Windows) used by the system class loader to load classes. This class path is usually configured prior to executing a Java program but can be dynamically configured during runtime if desired. If you want to use the system class path for this class loader, the convenience method getSystemClassPath has been provided.

Valid system class path entries are directories and zip files, specified by absolute path or relative path on the system. Any valid system class path entry is also valid for this class loader.

Example

Here is an example of how to use this class loader:

     MultiClassLoader loader = new MultiClassLoader();
     loader.setClassPath("/web/java/lutris.jar");
     loader.addClassPath("/users/kristen/java/");
     loader.addClassPath("/usr/local/lib/graphics.zip");
     try {
         Class c = loader.loadClass("com.lutris.util.MyClass");
         System.out.println("My loader is " + c.getClassLoader());
         Object o = (Object) c.newInstance();
         System.out.println("My class is " + o.getClass());
     } catch (ClassNotFoundException e) {
         Throwable t = new Throwable();
         t.printStackTrace();
     }
 

Warning: This class loader is not yet fully compliant with Java 1.2. It maybe used on 1.2, but not all features are available. The parent loader, secondary loader, and filter may change in a future release without maintaining compatibility.

Version:
$Revision : 1.0 $
Author:
Kristen Pol, Lutris Technologies
See Also:
ClassLoader, Resource, URL

Nested Class Summary
static interface MultiClassLoader.ClassFilter
          A filter interface, used in deciding if a class should be loaded by this class loader.
static class MultiClassLoader.ClassResource
          Information kept about a loaded class.
 
Field Summary
static java.lang.String LOG_LEVEL
          Log level symbolic name
 
Constructor Summary
MultiClassLoader(java.lang.ClassLoader parent, java.lang.ClassLoader secondary, com.lutris.logging.LogChannel loadLogChannel)
          Constructs class loader with no initial class path and a specified parent class loader.
MultiClassLoader(java.io.File[] path, com.lutris.logging.LogChannel loadLogChannel)
          Constructs class loader with specified class path.
MultiClassLoader(java.io.File path, com.lutris.logging.LogChannel loadLogChannel)
          Constructs class loader with specified class path.
MultiClassLoader(com.lutris.logging.LogChannel loadLogChannel)
          Constructs class loader with no initial class path and the system class loader as the secondary.
MultiClassLoader(java.lang.String[] path, com.lutris.logging.LogChannel loadLogChannel)
          Constructs class loader with specified class path.
MultiClassLoader(java.lang.String path, com.lutris.logging.LogChannel loadLogChannel)
          Constructs class loader with specified class path.
MultiClassLoader(java.net.URL[] path, com.lutris.logging.LogChannel loadLogChannel)
          Constructs class loader with specified class path.
MultiClassLoader(java.net.URL path, com.lutris.logging.LogChannel loadLogChannel)
          Constructs class loader with specified class path.
 
Method Summary
 void addClassFilter(MultiClassLoader.ClassFilter filter)
          Add a filter to the list of filters that check if a class maybe loaded by this class loader.
 void addClassPath(java.io.File path)
          Adds specified class path to beginning of existing path.
 void addClassPath(java.io.File[] path)
          Adds specified class path to beginning of existing path.
 void addClassPath(java.lang.String path)
          Adds specified class path to beginning of existing path.
 void addClassPath(java.lang.String[] path)
          Adds specified class path to beginning of existing path.
 void addClassPath(java.net.URL path)
          Adds specified class path to beginning of existing path.
 void addClassPath(java.net.URL[] path)
          Adds specified class path to beginning of existing path.
 void clearClassPath()
          Clears class path entries.
 void enableAutoReloadForSecLoader(boolean enable)
          Sets flag to enable Auto Reloading possibility when Secondary ClassLoader usage is forced (refer to forceSecondaryLoader() method for more help).
 void forceSecondaryLoader(boolean force)
          Sets flag to indicate forsing of Secondary ClassLoader usage or not.
 java.net.URL[] getClassPath()
          Gets class path for class loader defined previously by constructor and setClassPath/addClassPath methods.
 com.lutris.classloader.Resource getClassResource(java.lang.String className)
          Get the resource for a class loaded by this class loader.
 com.lutris.logging.LogChannel getLogChannel()
          Get the log channel associated this class loader.
 java.net.URL getResource(java.lang.String name)
          Gets specified resource as URL.
 byte[] getResourceAsByteArray(java.lang.String name)
          Gets specified resource as array of bytes.
 com.lutris.classloader.Resource getResourceAsIs(java.lang.String name)
          Gets specified resource object.
 java.io.InputStream getResourceAsStream(java.lang.String name)
          Gets specified resource as input stream.
 com.lutris.classloader.Resource getResourceObject(java.lang.String name)
          Gets specified resource object.
 java.lang.ClassLoader getSecondary()
          Get the secondary class loader.
static java.net.URL[] getSystemClassPath()
          Gets class path from system.
 java.lang.Class loadClass(java.lang.String className)
           
 java.lang.Class loadClass(java.lang.String className, boolean resolve)
          Loads and, optionally, resolves the specified class.
static java.lang.String[] parseClassPath(java.lang.String path)
          Parse a class-path string using the system path separator.
 void removeLoadedClass()
          Removes stored data about already loaded classes
 void setClassPath(java.io.File path)
          Sets class loader with specified class path.
 void setClassPath(java.io.File[] path)
          Sets class loader with specified class path.
 void setClassPath(java.lang.String path)
          Sets class loader with specified class path.
 void setClassPath(java.lang.String[] path)
          Sets class loader with specified class path.
 void setClassPath(java.net.URL path)
          Sets class loader with specified class path.
 void setClassPath(java.net.URL[] path)
          Sets class loader with specified class path.
 void setParent(java.lang.ClassLoader parent)
          Set the parent class loader for delegation.
 void setSecondary(java.lang.ClassLoader secondary)
          Set the secondary class loader.
 boolean shouldReload()
          Determine if the classes loaded by this class loader have been modified.
 
Methods inherited from class java.lang.ClassLoader
clearAssertionStatus, defineClass, defineClass, defineClass, defineClass, definePackage, findClass, findLibrary, findLoadedClass, findResource, findResources, findSystemClass, getPackage, getPackages, getParent, getResources, getSystemClassLoader, getSystemResource, getSystemResourceAsStream, getSystemResources, resolveClass, setClassAssertionStatus, setDefaultAssertionStatus, setPackageAssertionStatus, setSigners
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

LOG_LEVEL

public static final java.lang.String LOG_LEVEL
Log level symbolic name

See Also:
Constant Field Values
Constructor Detail

MultiClassLoader

public MultiClassLoader(java.lang.ClassLoader parent,
                        java.lang.ClassLoader secondary,
                        com.lutris.logging.LogChannel loadLogChannel)
Constructs class loader with no initial class path and a specified parent class loader.

Parameters:
parent - The parent class loader for delegation, or null if no parent is defined.
secondary - The secondary class loader. Use getSysClassLoader to get the system class loader to specify as the secondary.
loadLogChannel - The log channel, maybe null.
See Also:
getSysClassLoader

MultiClassLoader

public MultiClassLoader(com.lutris.logging.LogChannel loadLogChannel)
Constructs class loader with no initial class path and the system class loader as the secondary.

Parameters:
loadLogChannel - The log channel, maybe null.

MultiClassLoader

public MultiClassLoader(java.lang.String path,
                        com.lutris.logging.LogChannel loadLogChannel)
Constructs class loader with specified class path. The parameter is assumed to be either a directory, URL, or zip file.

Parameters:
path - The class path represented by a String.
loadLogChannel - The log channel, maybe null.

MultiClassLoader

public MultiClassLoader(java.lang.String[] path,
                        com.lutris.logging.LogChannel loadLogChannel)
Constructs class loader with specified class path. The parameter is assumed to be an array of directories, URLs, and/or zip files.

Parameters:
path - The class path represented by a String array.
loadLogChannel - The log channel, maybe null.

MultiClassLoader

public MultiClassLoader(java.io.File path,
                        com.lutris.logging.LogChannel loadLogChannel)
Constructs class loader with specified class path. The parameter is assumed to be either a zip file or directory.

Parameters:
path - The class path represented by a File.
loadLogChannel - The log channel, maybe null.

MultiClassLoader

public MultiClassLoader(java.io.File[] path,
                        com.lutris.logging.LogChannel loadLogChannel)
Constructs class loader with specified class path. The parameter is assumed to be an array of zip files and/or directories.

Parameters:
path - The class path represented by a File array.
loadLogChannel - The log channel, maybe null.

MultiClassLoader

public MultiClassLoader(java.net.URL path,
                        com.lutris.logging.LogChannel loadLogChannel)
Constructs class loader with specified class path. The parameter is represent a directory or zip file on the local machine or a remote machine.

Parameters:
path - The class path represented by a URL.
loadLogChannel - The log channel, maybe null.

MultiClassLoader

public MultiClassLoader(java.net.URL[] path,
                        com.lutris.logging.LogChannel loadLogChannel)
Constructs class loader with specified class path. The parameter is represent directories and/or zip files on the local machine and/or on remote machines.

Parameters:
path - The class path represented by a URL array.
loadLogChannel - The log channel, maybe null.
Method Detail

forceSecondaryLoader

public void forceSecondaryLoader(boolean force)
Sets flag to indicate forsing of Secondary ClassLoader usage or not.

Parameters:
force - true when the MultiClassLoader is used as utility wrapper class for passed secondary ClassLoader. All resource loads will be forced via passed Secondary ClassLoader. If parameter is set to false, then the MultyClassLoader will work in standard maner.

enableAutoReloadForSecLoader

public void enableAutoReloadForSecLoader(boolean enable)
Sets flag to enable Auto Reloading possibility when Secondary ClassLoader usage is forced (refer to forceSecondaryLoader() method for more help). This flag has no efect when MultiClassLoader is used in standard maner (as realy ClassLoader, not only as wrapper class for external ClassLoader)

Parameters:
enable - true when the AutoReloading should be used.

removeLoadedClass

public void removeLoadedClass()
Removes stored data about already loaded classes


setClassPath

public void setClassPath(java.lang.String path)
Sets class loader with specified class path. The parameter is assumed to be either a directory, URL, or zip file.

Parameters:
path - The class path to be used when loading classes.

setClassPath

public void setClassPath(java.lang.String[] path)
Sets class loader with specified class path. The parameter is assumed to be an array of directories, URLs, and/or zip files.

Parameters:
path - The class path to be used when loading classes.

setClassPath

public void setClassPath(java.io.File path)
Sets class loader with specified class path. The parameter is assumed to be either a zip file or directory.

Parameters:
path - The class path to be used when loading classes.

setClassPath

public void setClassPath(java.io.File[] path)
Sets class loader with specified class path. The parameter is assumed to be an array of zip files and/or directories.

Parameters:
path - The class path to be used when loading classes.

setClassPath

public void setClassPath(java.net.URL path)
Sets class loader with specified class path. The parameter is represent a directory or zip file on the local machine or a remote machine.

Parameters:
path - The class path to be used when loading classes.

setClassPath

public void setClassPath(java.net.URL[] path)
Sets class loader with specified class path. The parameter is represent directories and/or zip files on the local machine and/or on remote machines.

Parameters:
path - The class path to be used when loading classes.

addClassPath

public void addClassPath(java.lang.String path)
Adds specified class path to beginning of existing path. The parameter is assumed to be either a directory, URL, or zip file.

Parameters:
path - The class path to be added to current class path.

addClassPath

public void addClassPath(java.lang.String[] path)
Adds specified class path to beginning of existing path. The parameter is assumed to be an array of directories, URLs, and/or zip files.

Parameters:
path - The class path to be added to current class path.

addClassPath

public void addClassPath(java.io.File path)
Adds specified class path to beginning of existing path. The parameter is assumed to be either a zip file or directory.

Parameters:
path - The class path to be added to current class path.

addClassPath

public void addClassPath(java.io.File[] path)
Adds specified class path to beginning of existing path. The parameter is assumed to be an array of zip files and/or directories.

Parameters:
path - The class path to be added to current class path.

addClassPath

public void addClassPath(java.net.URL path)
Adds specified class path to beginning of existing path. The parameter is represent a directory or zip file on the local machine or a remote machine.

Parameters:
path - The class path to be added to current class path.

addClassPath

public void addClassPath(java.net.URL[] path)
Adds specified class path to beginning of existing path. The parameter is represent directories and/or zip files on the local machine and/or on remote machines.

Parameters:
path - The class path to be added to current class path.

clearClassPath

public void clearClassPath()
Clears class path entries.

See Also:
setClassPath(java.lang.String)

getClassPath

public java.net.URL[] getClassPath()
Gets class path for class loader defined previously by constructor and setClassPath/addClassPath methods.

Returns:
the class path represented by an Enumeration of URL objects.
See Also:
setClassPath(java.lang.String),

parseClassPath

public static java.lang.String[] parseClassPath(java.lang.String path)
Parse a class-path string using the system path separator.


getSystemClassPath

public static java.net.URL[] getSystemClassPath()
Gets class path from system.

Returns:
the system class path represented by an array of URL objects.

setParent

public void setParent(java.lang.ClassLoader parent)
Set the parent class loader for delegation.


getSecondary

public java.lang.ClassLoader getSecondary()
Get the secondary class loader.


setSecondary

public void setSecondary(java.lang.ClassLoader secondary)
Set the secondary class loader.


getLogChannel

public com.lutris.logging.LogChannel getLogChannel()
Get the log channel associated this class loader.


addClassFilter

public void addClassFilter(MultiClassLoader.ClassFilter filter)
Add a filter to the list of filters that check if a class maybe loaded by this class loader.


loadClass

public java.lang.Class loadClass(java.lang.String className,
                                 boolean resolve)
                          throws java.lang.ClassNotFoundException
Loads and, optionally, resolves the specified class. If the class needs to be instantiated, the class must be resolved. If only the existence of the class needs verification, class resolution is unnecessary. Calling loadClass(String className) is equivalent to calling this method with resolve set to true. Purposely not synchronized. If class is not found in loadedClasses table, then doLoadClass will do the operation in a synchronized manner.

Overrides:
loadClass in class java.lang.ClassLoader
Parameters:
className - The name of the class to be loaded, e.g. "com.lutris.util.Table".
resolve - Set to true for class resolution, false for no resolution.
Returns:
the loaded Class.
Throws:
java.lang.ClassNotFoundException - if the class could not be load.
See Also:
setClassPath(java.lang.String), addClassPath(java.lang.String)

loadClass

public java.lang.Class loadClass(java.lang.String className)
                          throws java.lang.ClassNotFoundException
Overrides:
loadClass in class java.lang.ClassLoader
Throws:
java.lang.ClassNotFoundException

getClassResource

public com.lutris.classloader.Resource getClassResource(java.lang.String className)
                                                 throws java.lang.ClassNotFoundException
Get the resource for a class loaded by this class loader.

Throws:
java.lang.ClassNotFoundException

getResource

public java.net.URL getResource(java.lang.String name)
Gets specified resource as URL. Doing a getContent() on the URL may return an Image, an AudioClip, or an InputStream.

Overrides:
getResource in class java.lang.ClassLoader
Parameters:
name - The name of the resource.
Returns:
the resource represented by a URL, or null if not found.

getResourceObject

public com.lutris.classloader.Resource getResourceObject(java.lang.String name)
Gets specified resource object.

Parameters:
name - The name of the resource.
Returns:
the resource if found, null if not.
See Also:
MultiClassLoader.ClassResource

getResourceAsIs

public com.lutris.classloader.Resource getResourceAsIs(java.lang.String name)
Gets specified resource object.

See Also:
Use getResourceObject(), getResourceObject

getResourceAsStream

public java.io.InputStream getResourceAsStream(java.lang.String name)
Gets specified resource as input stream.

Overrides:
getResourceAsStream in class java.lang.ClassLoader
Parameters:
name - The name of the resource.
Returns:
an input stream representing the specified resource or null if the resource is not found.

getResourceAsByteArray

public byte[] getResourceAsByteArray(java.lang.String name)
Gets specified resource as array of bytes.

Parameters:
name - The name of the resource.
Returns:
an array of bytes representing the specified resource or null if the resource is not found.

shouldReload

public boolean shouldReload()
Determine if the classes loaded by this class loader have been modified. If any file associated with loaded in the class loader's class path has changed, the classes should be reloaded. If the classes need to be reloaded, a new instance of this class loader must be created because a particular class loader instance can only load classes once.

Returns:
true if the classes should be reloaded, false if not.

EAF 7.6 Util