org.zeroturnaround.javarebel

Interface Integration

public interface Integration

Provides hooks for integrating JRebel with custom containers, frameworks and classloaders. To use it acquire an instance from IntegrationFactory

A typical (classloader) integration will look like this:

 class MyClassLoader extends URLClassLoader {
   public MyClassLoader() {
     ...
     IntegrationFactory.getInstance().registerClassLoader(
      this,
      new FindResourceClassResourceSource(this)));
   }
   ...
   public Class findClass(String classname) {
     synchronized(classloader) {
       Class result =
         classloader.findLoadedClass(classname);
       if (result != null)
         return result;
         
       result = 
         IntegrationFactory.getInstance()
           .findReloadableClass(this, classname);
       if (result != null)
         return result;
     }
      ...
   }   
 }
 

You can use the addIntegrationProcessor(String, ClassBytecodeProcessor) and addIntegrationProcessor(String[], ClassBytecodeProcessor) and makeTransparent(String) instrument specific classes to enhance their behaviour with JRebel.

You can use #addManagedPreProcessor(ClassBytecodeProcessor) to register a preprocessor for all classes managed by JRebel e.g. to enable container-specific AOP

Author:

Jevgeni Kabanov (ekabanov@zeroturnaround.com)

See Also:

IntegrationFactory, ServletIntegration, Configuration, Reloader, Logger, Plugin

Method Summary

Modifier and Type	Method and Description
void	addAfterMainCallback(AfterMainCallback callback) Registers a callback that will be invoked after the main method is called.
void	addBootClassProcessor(String className, ClassBytecodeProcessor processor) Adds a bytecode processor for the given class in boot classloader.
void	addClassLoaderDestructionListener(ClassLoader cl, ClassLoaderDestructionListener listener) Registers a call back invoked when a given class loader is being destroyed.
void	addIntegrationProcessor(ClassBytecodeProcessor processor, boolean managedOnly) Adds a bytecode processor for all classes.
void	addIntegrationProcessor(ClassLoader cl, ClassBytecodeProcessor processor) Adds a bytecode processor for the given classloader.
void	addIntegrationProcessor(ClassLoader cl, ClassBytecodeProcessor processor, boolean managedOnly) AAdds a bytecode processor for the given classloader.
void	addIntegrationProcessor(ClassLoader cl, String[] classNames, ClassBytecodeProcessor processor) Adds a bytecode processor for the set of given classes in the given classloader.
void	addIntegrationProcessor(ClassLoader cl, String className, ClassBytecodeProcessor processor) Adds a bytecode processor for the given class in the given classloader.
void	addIntegrationProcessor(String[] classNames, ClassBytecodeProcessor processor) Adds a bytecode processor for the set of given classes.
void	addIntegrationProcessor(String className, ClassBytecodeProcessor processor) Adds a bytecode processor for the given class.
Class<?>	defineReloadableClass(ClassLoader cl, String className, byte[] bytecode, ProtectionDomain protectionDomain) (Re)defines a class managed by JRebel.
void	disablePlugins(ClassLoader cl) Disable running plugins in given class loader.
void	disableReloadDetection(ClassLoader cl) Disable class reload check in given class loader.
void	disableReloading(ClassLoader cl) Disable class reloading in given class loader.
void	disableSecurityManager() Disables the SecurityManager in the current thread.
void	enableSecurityManager() Re-enables the disabled SecurityManager in the current thread.
URL	findRebelResource(ClassLoader cl, String name) Resolves resources only managed by JRebel.
Enumeration<URL>	findRebelResources(ClassLoader cl, String name) Resolves resources only managed by JRebel.
Class<?>	findReloadableClass(ClassLoader cl, String className) Resolves classes managed by JRebel.
URL	findResource(ClassLoader cl, String name) Resolves resources managed by JRebel.
Enumeration<URL>	findResources(ClassLoader cl, String name) Resolves resources managed by JRebel.
RebelSource[]	getRebelSources(ClassLoader cl) Returns the additional class path of the given ClassLoader managed by JRebel.
URL[]	getRebelURLs(ClassLoader cl) Returns the additional class path of the given ClassLoader managed by JRebel.
URL[]	getRebelURLs(ClassLoader cl, boolean onlyFullMatch) Returns the additional class path of the given ClassLoader managed by JRebel.
ScanHelper	getScanHelper(ClassLoader cl, String name) Returns helper object to perform class path scanning in the given ClassLoader.
URL	getTransparentResource(ClassLoader cl, String name) Returns the original resource with given name.
Enumeration<URL>	getTransparentResources(ClassLoader cl, String name) Returns the original resources with given name.
boolean	isCheckingPluginDependencies(ClassLoader cl) Returns true if Plugin.checkDependencies(ClassLoader, ClassResourceSource) is being called for the given class loader.
boolean	isFilteringMissingMethods() Returns true if we are filtering out parent class methods for OSGI, that the class itself can not see.
boolean	isPartnerPlatform() Validates if JRebel is enabled on a partner's platform
boolean	isResourceReplaced(ClassLoader cl, String name) Returns true if the given resource is managed by JRebel.
void	makeTransparent(String className) Deprecated.
void	recordClassResource(ClassLoader cl, String className, URL url) Record location of found class.
void	redefineClasses(ClassDefinition... classDefinitions) Redefine a set of classes managed by JRebel.
boolean	redefineReloadableClass(Class<?> klass, byte[] bytecode) Redefines a class managed by JRebel.
void	registerClassLoader(ClassLoader cl, ClassResourceSource cfs) Registers a ClassLoader with JRebel associating with it the class-to-file resolution strategy provided by ClassFileSource.
void	registerModularClassLoader(ClassLoader cl) Enable special handling for ClassLoader systems with non-transitive class loading e.g.
void	reinitializeClassLoader(ClassLoader cl) Reinitializes the ClassLoader with JRebel.
void	removeClassLoaderDestructionListener(ClassLoaderDestructionListener listener) Removes a call back invoked when a given class loader is being destroyed.
void	removeIntegrationProcessor(ClassBytecodeProcessor processor) Remove bytecode processor.
void	removeIntegrationProcessors(ClassLoader cl) Remove bytecode processors that are loaded by the ClassLoader
void	setPartnerPlatform(boolean flag) Indicate that JRebel is running on a partner's platform
void	unregisterClassLoader(ClassLoader cl) Unregisters the ClassLoader from JRebel.
void	useSeparateCacheForClassesAndResources(ClassLoader cl) Cache results for class and resource request separately.

Method Detail

registerClassLoader

void registerClassLoader(ClassLoader cl,
                         ClassResourceSource cfs)

Registers a ClassLoader with JRebel associating with it the class-to-file resolution strategy provided by ClassFileSource. It is necessary to do this before any calls to findReloadableClass(ClassLoader, String), the best place is usually the constructor.

Parameters:

cl - The custom class loader being integrated.

cfs - The class-to-file resolution strategy source.

See Also:

ClassResourceSource

reinitializeClassLoader

void reinitializeClassLoader(ClassLoader cl)

Reinitializes the ClassLoader with JRebel.

This should be called if the class path of the given ClassLoader was updated.

Parameters:

cl - The custom class loader being integrated.

unregisterClassLoader

void unregisterClassLoader(ClassLoader cl)

Unregisters the ClassLoader from JRebel. It is recommended to do this in case the corresponding ClassLoader is destroyed (e.g. the web application is undeployed).

Parameters:

cl - The custom class loader being integrated.

registerModularClassLoader

void registerModularClassLoader(ClassLoader cl)

Enable special handling for ClassLoader systems with non-transitive class loading e.g. OSGI, NetBeans. This method does not replace registerClassLoader(ClassLoader, ClassResourceSource).

Parameters:

cl - The custom class loader being integrated.

getRebelURLs

URL[] getRebelURLs(ClassLoader cl)

Returns the additional class path of the given ClassLoader managed by JRebel.

Same as getRebelURLs(cl, false).

Parameters:

cl - The custom class loader being integrated.

Returns:

additional class path of the given ClassLoader or null if nothing found.

getRebelURLs

URL[] getRebelURLs(ClassLoader cl,
                   boolean onlyFullMatch)

Returns the additional class path of the given ClassLoader managed by JRebel.

Parameters:

cl - The custom class loader being integrated.

onlyFullMatch - whether to only return locations with no custom patterns.

Returns:

additional class path of the given ClassLoader or null if nothing found.

getRebelSources

RebelSource[] getRebelSources(ClassLoader cl)

Returns the additional class path of the given ClassLoader managed by JRebel.

Parameters:

cl - The custom class loader being integrated.

Returns:

additional class path of the given ClassLoader or null if nothing found.

getScanHelper

ScanHelper getScanHelper(ClassLoader cl,
                         String name)

Returns helper object to perform class path scanning in the given ClassLoader. NOTE: this api is experimental and may be removed or changed in future versions.

Parameters:

cl - The class loader used to find resources to scan.

name - name of resource to start scanning from.

Returns:

helper for class path scanning or null if not available.

findReloadableClass

Class<?> findReloadableClass(ClassLoader cl,
                             String className)
                      throws ClassNotFoundException

Resolves classes managed by JRebel. These and only these classes will be reloadable. Returns null if class couldn't be resolved and the non-JRebel class loading should be used as fail-over. Throws ClassNotFoundException if class does not exist and the non-JRebel class loading should be skipped.

Parameters:

cl - The custom class loader being integrated.

classname - The public class name.

Returns:

Resolved class or null.

Throws:

ClassNotFoundException - if class does not exist.

See Also:

#defineReloadableClass(ClassLoader, String, byte[])

defineReloadableClass

Class<?> defineReloadableClass(ClassLoader cl,
                               String className,
                               byte[] bytecode,
                               ProtectionDomain protectionDomain)

(Re)defines a class managed by JRebel.

This method may be called for loading as well as reloading the class.

The defined class will only be reloaded if this method is called again. Even if the class was first loaded by findReloadableClass(ClassLoader, String) the resolved class resource will not be checked for updates.

Returns null if this class loader is not registered with JRebel.

Parameters:

cl - The custom class loader being integrated.

className - The public class name.

bytecode - class bytes.

protectionDomain - The ProtectionDomain of the class (may be null).

Returns:

(Re)defined class or null.

Since:

3.0

redefineReloadableClass

boolean redefineReloadableClass(Class<?> klass,
                                byte[] bytecode)

Redefines a class managed by JRebel.

Parameters:

klass - Class managed by JRebel.

bytecode - class bytes.

Returns:

true if the class was managed by JRebel and redefined.

Since:

3.0

redefineClasses

void redefineClasses(ClassDefinition... classDefinitions)

Redefine a set of classes managed by JRebel.

Parameters:

classDefinitions - Array of ClassDefinition objects containing the Class and new class-bytes

isResourceReplaced

boolean isResourceReplaced(ClassLoader cl,
                           String name)

Returns true if the given resource is managed by JRebel.

In that case resources can be resolved using the corresponding methods of the Integration. If any of these methods returns a null it must be returned by the ClassLoader as well.

Parameters:

cl - The custom class loader being integrated.

name - The public resource name.

Returns:

true if the given resource is managed by JRebel.

findResource

URL findResource(ClassLoader cl,
                 String name)

Resolves resources managed by JRebel.

Parameters:

cl - The custom class loader being integrated.

name - The public resource name.

Returns:

Resolved resource URL or null.

findRebelResource

URL findRebelResource(ClassLoader cl,
                      String name)

Resolves resources only managed by JRebel.

Parameters:

cl - The custom class loader being integrated.

name - The public resource name.

Returns:

Resolved resource URL or null.

findResources

Enumeration<URL> findResources(ClassLoader cl,
                               String name)

Resolves resources managed by JRebel.

Parameters:

cl - The custom class loader being integrated.

name - The public resource name.

Returns:

Resolved resource URLs or null.

findRebelResources

Enumeration<URL> findRebelResources(ClassLoader cl,
                                    String name)

Resolves resources only managed by JRebel.

Parameters:

cl - The custom class loader being integrated.

name - The public resource name.

Returns:

Resolved resource URLs or null.

getTransparentResources

Enumeration<URL> getTransparentResources(ClassLoader cl,
                                         String name)

Returns the original resources with given name. This is used to get the original result unaltered by JRebel.

Parameters:

cl - The custom class loader being integrated.

name - The resource name.

Returns:

Resolved resource URLs or null.

getTransparentResource

URL getTransparentResource(ClassLoader cl,
                           String name)

Returns the original resource with given name. This is used to get the original result unaltered by JRebel.

Parameters:

cl - The custom class loader being integrated.

name - The resource name.

Returns:

Resolved resource URL or null.

recordClassResource

void recordClassResource(ClassLoader cl,
                         String className,
                         URL url)

Record location of found class. This method may be used to improve cache hit ration for overhead resource requests in class loaders whose findClass does not call findResource.

Parameters:

cl - The custom class loader being integrated.

name - The public class name.

url - URL of class resource.

Since:

4.6

useSeparateCacheForClassesAndResources

void useSeparateCacheForClassesAndResources(ClassLoader cl)

Cache results for class and resource request separately. Use when the result of resource lookup as returned by findResource may be different from what is recorded with recordClassResource.

Parameters:

cl - The custom class loader being integrated.

makeTransparent

void makeTransparent(String className)

Deprecated.

Allows the given class to see the classes instrumented with JRebel via reflection without hiding any artifacts. Needed e.g. for creating dynamic proxies and so on. This method has been deprecated and may be removed in future versions.

addIntegrationProcessor

void addIntegrationProcessor(ClassLoader cl,
                             String className,
                             ClassBytecodeProcessor processor)

Adds a bytecode processor for the given class in the given classloader. It will be run before that class is loaded and is mainly use to enable integration with a specific framework or classloader. Allows to additionally restrict the bytecode processing to the given classloader.

addIntegrationProcessor

void addIntegrationProcessor(String className,
                             ClassBytecodeProcessor processor)

Adds a bytecode processor for the given class. It will be run before that class is loaded and is mainly use to enable integration with a specific framework or classloader.

addIntegrationProcessor

void addIntegrationProcessor(ClassLoader cl,
                             ClassBytecodeProcessor processor)

Adds a bytecode processor for the given classloader. It will be run before that class is loaded and is mainly use to enable integration with a specific framework or classloader. Allows to additionally restrict the bytecode processing to the given classloader.

addIntegrationProcessor

void addIntegrationProcessor(ClassBytecodeProcessor processor,
                             boolean managedOnly)

Adds a bytecode processor for all classes. It will be run before that class is loaded and is mainly used for integration with preprocessors like AspectJ.

If managedOnly is true the processor will only be run for the classes managed by JRebel. This is useful to enable processing usually done in the class loader findClass() method, e.g. the JBoss AOP.

addIntegrationProcessor

void addIntegrationProcessor(ClassLoader cl,
                             ClassBytecodeProcessor processor,
                             boolean managedOnly)

AAdds a bytecode processor for the given classloader. It will be run before that class is loaded and is mainly used for integration with preprocessors like AspectJ.

If managedOnly is true the processor will only be run for the classes managed by JRebel. This is useful to enable processing usually done in the class loader findClass() method, e.g. the JBoss AOP.

addIntegrationProcessor

void addIntegrationProcessor(String[] classNames,
                             ClassBytecodeProcessor processor)

Adds a bytecode processor for the set of given classes. It will be run before those classes are loaded and is mainly use to enable integration with a specific framework or classloader.

See Also:

addIntegrationProcessor(String, ClassBytecodeProcessor)

addIntegrationProcessor

void addIntegrationProcessor(ClassLoader cl,
                             String[] classNames,
                             ClassBytecodeProcessor processor)

Adds a bytecode processor for the set of given classes in the given classloader. It will be run before those classes are loaded and is mainly use to enable integration with a specific framework or classloader. Allows to additionally restrict the bytecode processing to the given classloader.

See Also:

addIntegrationProcessor(ClassLoader, String, ClassBytecodeProcessor)

removeIntegrationProcessor

void removeIntegrationProcessor(ClassBytecodeProcessor processor)

Remove bytecode processor.

removeIntegrationProcessors

void removeIntegrationProcessors(ClassLoader cl)

Remove bytecode processors that are loaded by the ClassLoader

addBootClassProcessor

void addBootClassProcessor(String className,
                           ClassBytecodeProcessor processor)

Adds a bytecode processor for the given class in boot classloader. It will be run before that class is loaded and is mainly use to enable integration with a specific framework or classloader. This API is only available when JRebel is configured as java agent.

addClassLoaderDestructionListener

void addClassLoaderDestructionListener(ClassLoader cl,
                                       ClassLoaderDestructionListener listener)

Registers a call back invoked when a given class loader is being destroyed.

Parameters:

cl - The custom class loader being integrated.

listener - class loader destruction listener.

removeClassLoaderDestructionListener

void removeClassLoaderDestructionListener(ClassLoaderDestructionListener listener)

Removes a call back invoked when a given class loader is being destroyed.

Parameters:

listener - class loader destruction listener.

isCheckingPluginDependencies

boolean isCheckingPluginDependencies(ClassLoader cl)

Returns true if Plugin.checkDependencies(ClassLoader, ClassResourceSource) is being called for the given class loader.

During the given process no class path entries should be altered.

isFilteringMissingMethods

boolean isFilteringMissingMethods()

Returns true if we are filtering out parent class methods for OSGI, that the class itself can not see. Used to disable class resource finding in a classloader if it can find the class as Resource but can not load that class.

setPartnerPlatform

void setPartnerPlatform(boolean flag)

Indicate that JRebel is running on a partner's platform

Parameters:

flag -

isPartnerPlatform

boolean isPartnerPlatform()

Validates if JRebel is enabled on a partner's platform

Returns:

disablePlugins

void disablePlugins(ClassLoader cl)

Disable running plugins in given class loader.

disableReloading

void disableReloading(ClassLoader cl)

Disable class reloading in given class loader. Resource management will still be enabled.

disableReloadDetection

void disableReloadDetection(ClassLoader cl)

Disable class reload check in given class loader. Resource management will still be enabled.

addAfterMainCallback

void addAfterMainCallback(AfterMainCallback callback)

Registers a callback that will be invoked after the main method is called. Callback will be invoked in the same order as they were added. If a callback is added after the main method has been called it will be invoked immediately.

disableSecurityManager

void disableSecurityManager()

Disables the SecurityManager in the current thread.

enableSecurityManager

void enableSecurityManager()

Re-enables the disabled SecurityManager in the current thread.