org.hotswap.agent.javassist

Class Loader

java.lang.Object

java.lang.ClassLoader

org.hotswap.agent.javassist.Loader

Direct Known Subclasses:

Loader

public class Loader
extends ClassLoader

The class loader for Javassist.

This is a sample class loader using ClassPool. Unlike a regular class loader, this class loader obtains bytecode from a ClassPool.

Note that Javassist can be used without this class loader; programmers can define their own versions of class loader. They can run a program even without any user-defined class loader if that program is statically translated with Javassist. This class loader is just provided as a utility class.

Suppose that an instance of MyTranslator implementing the interface Translator is responsible for modifying class files. The startup program of an application using MyTranslator should be something like this:

 import org.hotswap.agent.javassist.*;

 public class Main {
   public static void main(String[] args) throws Throwable {
     MyTranslator myTrans = new MyTranslator();
     ClassPool cp = ClassPool.getDefault();
     Loader cl = new Loader(cp);
     cl.addTranslator(cp, myTrans);
     cl.run("MyApp", args);
   }
 }
 

Class MyApp is the main program of the application.

This program should be executed as follows:

 % java Main arg1 arg2...
 

It modifies the class MyApp with a MyTranslator object before the JVM loads it. Then it calls main() in MyApp with arguments arg1, arg2, ...

This program execution is equivalent to:

 % java MyApp arg1 arg2...
 

except that classes are translated by MyTranslator at load time.

If only a particular class must be modified when it is loaded, the startup program can be simpler; MyTranslator is unnecessary. For example, if only a class test.Rectangle is modified, the main() method above will be the following:

 ClassPool cp = ClassPool.getDefault();
 Loader cl = new Loader(cp);
 CtClass ct = cp.get("test.Rectangle");
 ct.setSuperclass(cp.get("test.Point"));
 cl.run("MyApp", args);

This program changes the super class of the test.Rectangle class.

Note 1:

This class loader does not allow the users to intercept the loading of java.* and javax.* classes (and sun.*, org.xml.*, ...) unless Loader.doDelegation is false. This is because the JVM prohibits a user class loader from loading a system class. Also see Note 2. If this behavior is not appropriate, a subclass of Loader must be defined and loadClassByDelegation() must be overridden.

Note 2:

If classes are loaded with different class loaders, they belong to separate name spaces. If class C is loaded by a class loader CL, all classes that the class C refers to are also loaded by CL. However, if CL delegates the loading of the class C to CL', then those classes that the class C refers to are loaded by a parent class loader CL' instead of CL.

If an object of class C is assigned to a variable of class C belonging to a different name space, then a ClassCastException is thrown.

Because of the fact above, this loader delegates only the loading of javassist.Loader and classes included in package java.* and javax.* to the parent class loader. Other classes are directly loaded by this loader.

For example, suppose that java.lang.String would be loaded by this loader while java.io.File is loaded by the parent class loader. If the constructor of java.io.File is called with an instance of java.lang.String, then it may throw an exception since it accepts an instance of only the java.lang.String loaded by the parent class loader.

See Also:

javassist.ClassPool, javassist.Translator

Field Summary

Fields

Modifier and Type	Field and Description
boolean	doDelegation Specifies the algorithm of class loading.

Constructor Summary

Constructors

Constructor and Description
Loader() Creates a new class loader.
Loader(ClassLoader parent, ClassPool cp) Creates a new class loader using the specified parent class loader for delegation.
Loader(ClassPool cp) Creates a new class loader.

Method Summary

Modifier and Type	Method and Description
void	addTranslator(ClassPool cp, Translator t) Adds a translator, which is called whenever a class is loaded.
void	delegateLoadingOf(String classname) Records a class so that the loading of that class is delegated to the parent class loader.
protected Class	delegateToParent(String classname)
protected Class	findClass(String name) Finds the specified class using ClassPath.
protected Class	loadClass(String name, boolean resolve) Requests the class loader to load a class.
protected Class	loadClassByDelegation(String name)
static void	main(String[] args) Loads a class with an instance of Loader and calls main() of that class.
void	run(String[] args) Loads a class and calls main() in that class.
void	run(String classname, String[] args) Loads a class and calls main() in that class.
void	setClassPool(ClassPool cp) Sets the soruce ClassPool.
void	setDomain(ProtectionDomain d) Sets the protection domain for the classes handled by this class loader.

Methods inherited from class java.lang.ClassLoader

clearAssertionStatus, defineClass, defineClass, defineClass, defineClass, definePackage, findLibrary, findLoadedClass, findResource, findResources, findSystemClass, getClassLoadingLock, getPackage, getPackages, getParent, getResource, getResourceAsStream, getResources, getSystemClassLoader, getSystemResource, getSystemResourceAsStream, getSystemResources, loadClass, registerAsParallelCapable, 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

doDelegation

public boolean doDelegation

Specifies the algorithm of class loading.

This class loader uses the parent class loader for java.* and javax.* classes. If this variable doDelegation is false, this class loader does not delegate those classes to the parent class loader.

The default value is true.

Constructor Detail

Loader

public Loader()

Creates a new class loader.

Loader

public Loader(ClassPool cp)

Creates a new class loader.

Parameters:

cp - the source of class files.

Loader

public Loader(ClassLoader parent,
              ClassPool cp)

Creates a new class loader using the specified parent class loader for delegation.

Parameters:

parent - the parent class loader.

cp - the source of class files.

Method Detail

delegateLoadingOf

public void delegateLoadingOf(String classname)

Records a class so that the loading of that class is delegated to the parent class loader.

If the given class name ends with . (dot), then that name is interpreted as a package name. All the classes in that package and the sub packages are delegated.

setDomain

public void setDomain(ProtectionDomain d)

Sets the protection domain for the classes handled by this class loader. Without registering an appropriate protection domain, the program loaded by this loader will not work with a security manager or a signed jar file.

setClassPool

public void setClassPool(ClassPool cp)

Sets the soruce ClassPool.

addTranslator

public void addTranslator(ClassPool cp,
                          Translator t)
                   throws NotFoundException,
                          CannotCompileException

Adds a translator, which is called whenever a class is loaded.

Parameters:

cp - the ClassPool object for obtaining a class file.

t - a translator.

Throws:

NotFoundException - if t.start() throws an exception.

CannotCompileException - if t.start() throws an exception.

main

public static void main(String[] args)
                 throws Throwable

Loads a class with an instance of Loader and calls main() of that class.

This method calls run().

Parameters:

args - command line parameters.
args[0] is the class name to be loaded.
args[1..n] are parameters passed to the target main().

Throws:

Throwable

See Also:

javassist.Loader#run(String[])

run

public void run(String[] args)
         throws Throwable

Loads a class and calls main() in that class.

Parameters:

args - command line parameters.
args[0] is the class name to be loaded.
args[1..n] are parameters passed to the target main().

Throws:

Throwable

run

public void run(String classname,
                String[] args)
         throws Throwable

Loads a class and calls main() in that class.

Parameters:

classname - the loaded class.

args - parameters passed to main().

Throws:

Throwable

loadClass

protected Class loadClass(String name,
                          boolean resolve)
                   throws ClassFormatError,
                          ClassNotFoundException

Requests the class loader to load a class.

Overrides:

loadClass in class ClassLoader

Throws:

ClassFormatError

ClassNotFoundException

findClass

protected Class findClass(String name)
                   throws ClassNotFoundException

Finds the specified class using ClassPath. If the source throws an exception, this returns null.

This method can be overridden by a subclass of Loader. Note that the overridden method must not throw an exception when it just fails to find a class file.

Overrides:

findClass in class ClassLoader

Returns:

null if the specified class could not be found.

Throws:

ClassNotFoundException - if an exception is thrown while obtaining a class file.

loadClassByDelegation

protected Class loadClassByDelegation(String name)
                               throws ClassNotFoundException

Throws:

ClassNotFoundException

delegateToParent

protected Class delegateToParent(String classname)
                          throws ClassNotFoundException

Throws:

ClassNotFoundException