Package 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) 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 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.

      • isRegisteredClassLoader

        boolean isRegisteredClassLoader​(ClassLoader cl)
        Says if this ClassLoader is registerd with JRebel.
        Parameters:
        cl - The custom class loader being integrated.
        Returns:

      • 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,
                               Resource mutableResource,
                               ProtectionDomain protectionDomain,
                               boolean processedByLoader)
        (Re)defines a class managed by JRebel. When the class is reloaded, the Resource provided here is used to get the new bytes. This can be used to re-generate the bytes for a proxy class after a reload. Returns null if this class loader is not registered with JRebel.
        Parameters:
        cl - The custom class loader being integrated.
        className - The public class name.
        resource - bytes for the class.
        protectionDomain - The ProtectionDomain of the class (may be null).
        processedByLoader - Whether given bytes should be processed by class loader in the same way as a normally loaded classes. Set to false when class is supposed to be define similarly to reflectively calling ClassLoader.defineClass that bypasses logic inside defining loader.
        Returns:
        (Re)defined class or null.
        Since:
        18.2.5

      • defineReloadableClass

        Class<?> defineReloadableClass​(ClassLoader cl,
                               String className,
                               byte[] bytecode,
                               ProtectionDomain protectionDomain,
                               boolean processedByLoader)
        (Re)defines a class managed by JRebel.

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

        This method is intended to replace defineClass, e.g. used from the same context as defineClass is currently used. So in normal java ClassLoader the caller of defineClass should already be synchronized and we should not do it inside defineReloadableClass in order to avoid creating extra deadlocks.

        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).
        processedByLoader - Whether given bytes should be processed by class loader in the same way as a normally loaded classes. Set to false when class is supposed to be define similarly to reflectively calling ClassLoader.defineClass that bypasses logic inside defining loader.
        Returns:
        (Re)defined class or null.
        Since:
        7.0.1

      • defineReloadableClass

        Class<?> defineReloadableClass​(ClassLoader cl,
                               String className,
                               byte[] bytecode,
                               ProtectionDomain protectionDomain)
        Same as defineReloadableClass(cl, className, bytecode, protectionDomain, true)
        Since:
        3.0

      • redefineReloadableClass

        boolean redefineReloadableClass​(Class<?> klass,
                                byte[] bytecode,
                                boolean processedByLoader)
        Redefines a class managed by JRebel.
        Parameters:
        klass - Class managed by JRebel.
        bytecode - class bytes.
        processedByLoader - Whether given bytes should be processed by class loader in the same way as a normally loaded classes. Set to false when class is supposed to be define similarly to reflectively calling ClassLoader.defineClass that bypasses logic inside defining loader.
        Returns:
        true if the class was managed by JRebel and redefined.
        Since:
        7.0.1

      • redefineReloadableClass

        boolean redefineReloadableClass​(Class<?> klass,
                                byte[] bytecode)
        Same as redefineReloadableClass(klass, bytecode, true)
        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.

      • 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.

      • 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.

      • addBootClassProcessor

        void addBootClassProcessor​(ClassBytecodeProcessor classBytecodeProcessor)
        Adds a bytecode processor in boot classloader. It is mainly use to enable integration with a specific framework or classloader. This API is only available when JRebel is configured as java agent.

      • reportError

        void reportError​(Throwable e,
                 String version,
                 String jarFile)
        Report CBP failure, implementation must be async.
        Parameters:
        e -
        version -
        jarFile -

      • 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.

      • 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.

      • bindToClassLoader

        void bindToClassLoader​(ClassLoader cl,
                       Object value)
        Add reference from given class loader to given object. This will prevent GC from collecting the input object before class loader is collected.
        Parameters:
        cl - Class loader that will be used to keep object alive.
        value - Object that will be made to live as long as class loader.
        Since:
        2019.2.2

      • addCacheCleaner

        void addCacheCleaner​(CacheCleaner cacheCleaner)
        An integration point to add once per reload caches that should be cleared after reload.
        Since:
        2020.1.2