org.openimaj.aop.classloader

Class ClassLoaderTransform

java.lang.Object

org.openimaj.aop.classloader.ClassLoaderTransform

public class ClassLoaderTransform
extends Object

ClassLoaderTransform provides an alternative to using a java agent to perform byte-code manipulation by providing a classloader that will automatically transform classes as they are loaded.

Author:

Jonathon Hare (jsh2@ecs.soton.ac.uk)

Field Summary

Fields

Modifier and Type	Field and Description
static String	MAIN_CLASS Manifest property key for specifying the actual main class when using the loading technique provided by main(String[]).
static String	TRANSFORMERS Manifest property key for specifying the ClassTransformer classes when using the loading technique provided by main(String[]).
static String	TRANSFORMERS_SEPARATOR Separator character for separating multiple ClassTransformers when using the loading technique provided by main(String[]).

Constructor Summary

Constructors

Constructor and Description
ClassLoaderTransform()

Method Summary

Modifier and Type	Method and Description
static String	getMainClass(File jarFile) Get the main class from the manifest of the given jar file
static void	main(String[] args) Main method for an alternative in-place loading strategy.
static boolean	run(Class<?> clz, String[] args, ClassTransformer transformer, ClassTransformer... transformers) If the the given class has not already been loaded in by Loader, load it in a newly created Loader that is configured to apply the given transform(s), run the main method and return true.
protected static javassist.Loader	run(ClassLoader parent, javassist.ClassPool pool, MultiTransformClassFileTransformer tf, String mainClass, String[] args)
static javassist.Loader	run(javassist.ClassPool pool, MultiTransformClassFileTransformer tf, File jarFile, String[] args) Run the main method of the given jar file, passing all classes as they are loaded through the transformer to modify the bytecode.
static javassist.Loader	run(javassist.ClassPool pool, MultiTransformClassFileTransformer tf, String classpath, String mainClass, String[] args) Run the main method of the given class, transforming any classes found on the given classpath as they are loaded.
static void	run(MultiTransformClassFileTransformer transformer, Class<?> clz, String[] args) Re-load the given class in a newly created Loader that is configured to apply the given transform(s), and then run the main method.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

MAIN_CLASS

public static final String MAIN_CLASS

Manifest property key for specifying the actual main class when using the loading technique provided by main(String[]).

See Also:

Constant Field Values

TRANSFORMERS

public static final String TRANSFORMERS

Manifest property key for specifying the ClassTransformer classes when using the loading technique provided by main(String[]).

See Also:

Constant Field Values

TRANSFORMERS_SEPARATOR

public static final String TRANSFORMERS_SEPARATOR

Separator character for separating multiple ClassTransformers when using the loading technique provided by main(String[]).

See Also:

Constant Field Values

Constructor Detail

ClassLoaderTransform

public ClassLoaderTransform()

Method Detail

run

public static javassist.Loader run(javassist.ClassPool pool,
                                   MultiTransformClassFileTransformer tf,
                                   File jarFile,
                                   String[] args)
                            throws Throwable

Run the main method of the given jar file, passing all classes as they are loaded through the transformer to modify the bytecode. The main method must be specified by the "Main-Class" manifest entry.

Parameters:

pool - the classpool to hold classes as they are loaded

tf - the transform(s) to apply

jarFile - the jar file to run

args - the arguments to pass to the main method

Returns:

the classloader used for loading the classes in the jar file

Throws:

Throwable - if an error occurs

getMainClass

public static String getMainClass(File jarFile)
                           throws IOException

Get the main class from the manifest of the given jar file

Parameters:

jarFile - the jar file

Returns:

the main class or null if not found

Throws:

IOException - if an error occurs when reading

run

public static javassist.Loader run(javassist.ClassPool pool,
                                   MultiTransformClassFileTransformer tf,
                                   String classpath,
                                   String mainClass,
                                   String[] args)
                            throws Throwable

Run the main method of the given class, transforming any classes found on the given classpath as they are loaded.

Parameters:

pool - the classpool to hold classes as they are loaded

tf - the transform(s) to apply

classpath - the classpath on which to search for classes

mainClass - the main class with the main(String[]) method

args - the arguments to pass to the main method

Returns:

the classloader used for loading the classes in the jar file

Throws:

Throwable - if an error occurs

run

public static void run(MultiTransformClassFileTransformer transformer,
                       Class<?> clz,
                       String[] args)
                throws Throwable

Re-load the given class in a newly created Loader that is configured to apply the given transform(s), and then run the main method.

Parameters:

transformer - the transformer

clz - the class

args - the arguments

Throws:

Throwable - if an error occurs

run

protected static javassist.Loader run(ClassLoader parent,
                                      javassist.ClassPool pool,
                                      MultiTransformClassFileTransformer tf,
                                      String mainClass,
                                      String[] args)
                               throws Throwable

Throws:

Throwable

run

public static boolean run(Class<?> clz,
                          String[] args,
                          ClassTransformer transformer,
                          ClassTransformer... transformers)
                   throws Throwable

If the the given class has not already been loaded in by Loader, load it in a newly created Loader that is configured to apply the given transform(s), run the main method and return true. If the class's classload is a Loader then return false.

Parameters:

clz - the class to load, transform and run

args - the arguments to the main method

transformer - the first transformer

transformers - any additional transformers

Returns:

true if the class has been reloaded; false otherwise

Throws:

Throwable - if an error occurs.

main

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

Main method for an alternative in-place loading strategy. Allows a self-contained program jar to automatically run ClassTransformers on itself.

Modify the assembled jar file so that the Main-Class is set as this class (org.openimaj.aop.classloader.ClassLoaderTransform) and add additional keys to the manifest to point at the actual class main ( MAIN_CLASS) and the transformer classes (TRANSFORMERS, separated by TRANSFORMERS_SEPARATOR).

The specified transformer classes must all be instances of ClassTransformer and also have a no-args constructor.

Parameters:

args - the arguments to pass to the program being run

Throws:

Throwable - if an error occurs