Package javassist

# Class Loader

java.lang.Object
java.lang.ClassLoader
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 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:
  - `ClassPool`
  - `Translator`

## Nested Class Summary

Nested Classes
Modifier and Type
Class
Description
`static class`
`Loader.Simple`
A simpler class loader.

## Field Summary

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

## Constructor Summary

Constructors
Constructor
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
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.
`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, getDefinedPackage, getDefinedPackages, getName, getParent, getPlatformClassLoader, getResource, getResourceAsStream, getResources, getSystemClassLoader, getSystemResource, getSystemResourceAsStream, getSystemResources, getUnnamedModule, isRegisteredAsParallelCapable, loadClass, resources, setClassAssertionStatus, setDefaultAssertionStatus, setPackageAssertionStatus`

### Methods inherited from class java.lang.Object

`equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

## Field Details

### 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 Details

### 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 Details

### 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:
  - `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`