icy.system

Class ClassPatcher

java.lang.Object

icy.system.ClassPatcher

public class ClassPatcher
extends java.lang.Object

The code hacker provides a mechanism for altering the behavior of classes before they are loaded, for the purpose of injecting new methods and/or altering existing ones.

In ImageJ, this mechanism is used to provide new seams into legacy ImageJ1 code, so that (e.g.) the modern UI is aware of IJ1 events as they occur.

Author:

Curtis Rueden, Rick Lentz, Stephane Dallongeville

Constructor Summary

Constructors

Constructor and Description
ClassPatcher(java.lang.ClassLoader classLoader, java.lang.String patchPackage, java.lang.String patchSuffix)
ClassPatcher(java.lang.String patchPackage, java.lang.String patchSuffix)

Method Summary

Methods

Modifier and Type	Method and Description
void	insertAfterMethod(java.lang.String fullClass, java.lang.String methodSig) Modifies a class by injecting additional code at the end of the specified method's body.
void	insertAfterMethod(java.lang.String fullClass, java.lang.String methodSig, java.lang.String newCode) Modifies a class by injecting the provided code string at the end of the specified method's body.
void	insertBeforeMethod(java.lang.String fullClass, java.lang.String methodSig) Modifies a class by injecting additional code at the start of the specified method's body.
void	insertBeforeMethod(java.lang.String fullClass, java.lang.String methodSig, java.lang.String newCode) Modifies a class by injecting the provided code string at the start of the specified method's body.
void	insertMethod(java.lang.String fullClass, java.lang.String methodSig) Modifies a class by injecting a new method.
void	insertMethod(java.lang.String fullClass, java.lang.String methodSig, java.lang.String newCode) Modifies a class by injecting the provided code string as a new method.
java.lang.Class<?>	loadClass(java.lang.String fullClass) Loads the given, possibly modified, class.
java.lang.Class<?>	loadClass(java.lang.String fullClass, java.lang.ClassLoader classLoader, java.security.ProtectionDomain protectionDomain) Loads the given, possibly modified, class.
void	replaceMethod(java.lang.String fullClass, java.lang.String methodSig) Modifies a class by replacing the specified method.
void	replaceMethod(java.lang.String fullClass, java.lang.String methodSig, java.lang.String newCode) Modifies a class by replacing the specified method with the provided code string.

Methods inherited from class java.lang.Object

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

Constructor Detail

ClassPatcher

public ClassPatcher(java.lang.ClassLoader classLoader,
            java.lang.String patchPackage,
            java.lang.String patchSuffix)

ClassPatcher

public ClassPatcher(java.lang.String patchPackage,
            java.lang.String patchSuffix)

Method Detail

insertAfterMethod

public void insertAfterMethod(java.lang.String fullClass,
                     java.lang.String methodSig)

Modifies a class by injecting additional code at the end of the specified method's body.

The extra code is defined in the imagej.legacy.patches package, as described in the documentation for insertMethod(String, String).

Parameters:

fullClass - Fully qualified name of the class to modify.

methodSig - Method signature of the method to modify; e.g., "public void updateAndDraw()"

insertAfterMethod

public void insertAfterMethod(java.lang.String fullClass,
                     java.lang.String methodSig,
                     java.lang.String newCode)

Modifies a class by injecting the provided code string at the end of the specified method's body.

Parameters:

fullClass - Fully qualified name of the class to modify.

methodSig - Method signature of the method to modify; e.g., "public void updateAndDraw()"

newCode - The string of code to add; e.g., System.out.println(\"Hello World!\");

insertBeforeMethod

public void insertBeforeMethod(java.lang.String fullClass,
                      java.lang.String methodSig)

Modifies a class by injecting additional code at the start of the specified method's body.

The extra code is defined in the imagej.legacy.patches package, as described in the documentation for insertMethod(String, String).

Parameters:

fullClass - Fully qualified name of the class to override.

methodSig - Method signature of the method to override; e.g., "public void updateAndDraw()"

insertBeforeMethod

public void insertBeforeMethod(java.lang.String fullClass,
                      java.lang.String methodSig,
                      java.lang.String newCode)

Modifies a class by injecting the provided code string at the start of the specified method's body.

Parameters:

fullClass - Fully qualified name of the class to override.

methodSig - Method signature of the method to override; e.g., "public void updateAndDraw()"

newCode - The string of code to add; e.g., System.out.println(\"Hello World!\");

insertMethod

public void insertMethod(java.lang.String fullClass,
                java.lang.String methodSig)

Modifies a class by injecting a new method.

The body of the method is defined in the imagej.legacy.patches package, as described in the insertMethod(String, String) method documentation.

The new method implementation should be declared in the imagej.legacy.patches package, with the same name as the original class plus "Methods"; e.g., overridden ij.gui.ImageWindow methods should be placed in the imagej.legacy.patches.ImageWindowMethods class.

New method implementations must be public static, with an additional first parameter: the instance of the class on which to operate.

Parameters:

fullClass - Fully qualified name of the class to override.

methodSig - Method signature of the method to override; e.g., "public void setVisible(boolean vis)"

insertMethod

public void insertMethod(java.lang.String fullClass,
                java.lang.String methodSig,
                java.lang.String newCode)

Modifies a class by injecting the provided code string as a new method.

Parameters:

fullClass - Fully qualified name of the class to override.

methodSig - Method signature of the method to override; e.g., "public void updateAndDraw()"

newCode - The string of code to add; e.g., System.out.println(\"Hello World!\");

replaceMethod

public void replaceMethod(java.lang.String fullClass,
                 java.lang.String methodSig)

Modifies a class by replacing the specified method.

The new code is defined in the imagej.legacy.patches package, as described in the documentation for insertMethod(String, String).

Parameters:

fullClass - Fully qualified name of the class to override.

methodSig - Method signature of the method to replace; e.g., "public void setVisible(boolean vis)"

replaceMethod

public void replaceMethod(java.lang.String fullClass,
                 java.lang.String methodSig,
                 java.lang.String newCode)

Modifies a class by replacing the specified method with the provided code string.

Parameters:

fullClass - Fully qualified name of the class to override.

methodSig - Method signature of the method to replace; e.g., "public void setVisible(boolean vis)"

newCode - The string of code to add; e.g., System.out.println(\"Hello World!\");

loadClass

public java.lang.Class<?> loadClass(java.lang.String fullClass)

Loads the given, possibly modified, class.

This method must be called to confirm any changes made with insertAfterMethod(java.lang.String, java.lang.String), insertBeforeMethod(java.lang.String, java.lang.String), insertMethod(java.lang.String, java.lang.String) or replaceMethod(java.lang.String, java.lang.String).

Parameters:

fullClass - Fully qualified class name to load.

Returns:

the loaded class

loadClass

public java.lang.Class<?> loadClass(java.lang.String fullClass,
                           java.lang.ClassLoader classLoader,
                           java.security.ProtectionDomain protectionDomain)

Loads the given, possibly modified, class.

This method must be called to confirm any changes made with insertAfterMethod(java.lang.String, java.lang.String), insertBeforeMethod(java.lang.String, java.lang.String), insertMethod(java.lang.String, java.lang.String) or replaceMethod(java.lang.String, java.lang.String).

Parameters:

fullClass - Fully qualified class name to load.

Returns:

the loaded class