Class Nexus


  • public class Nexus
    extends java.lang.ref.WeakReference<java.lang.ClassLoader>

    This nexus is a global dispatcher for initializing classes with LoadedTypeInitializers. To do so, this class is to be loaded by the system class loader in an explicit manner. Any instrumented class is then injected a code block into its static type initializer that makes a call to this very same nexus which had the loaded type initializer registered before hand.

    Note: Availability of the Nexus class and its injection into the system class loader can be disabled entirely by setting the PROPERTY system property to false.

    Important: The nexus must never be accessed directly but only by the NexusAccessor which makes sure that the nexus is loaded by the system class loader. Otherwise, a class might not be able to initialize itself if it is loaded by different class loader that does not have the system class loader in its hierarchy.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      private int classLoaderHashCode
      The class loader's hash code upon registration.
      private int identification
      A random value that uniquely identifies a Nexus entry in order to avoid conflicts when applying the self-initialization strategy in multiple transformations.
      private java.lang.String name
      The name of a type for which a loaded type initializer is registered.
      private static java.lang.ref.ReferenceQueue<java.lang.ClassLoader> NO_QUEUE
      An type-safe constant for a non-operational reference queue.
      static java.lang.String PROPERTY
      A system property that allows to disable the use of the Nexus class which is normally injected into the system class loader.
      private static java.util.concurrent.ConcurrentMap<Nexus,​java.lang.Object> TYPE_INITIALIZERS
      A map of keys identifying a loaded type by its name and class loader mapping their potential LoadedTypeInitializer where the class loader of these initializers is however irrelevant.
    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      private Nexus​(java.lang.Class<?> type, int identification)
      Creates a key for identifying a loaded type initializer.
      private Nexus​(java.lang.String name, java.lang.ClassLoader classLoader, java.lang.ref.ReferenceQueue<? super java.lang.ClassLoader> referenceQueue, int identification)
      Creates a key for identifying a loaded type initializer.
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      static void clean​(java.lang.ref.Reference<? super java.lang.ClassLoader> reference)
      Cleans any stale entries from this nexus.
      boolean equals​(java.lang.Object other)  
      int hashCode()  
      static void initialize​(java.lang.Class<?> type, int identification)
      Initializes a loaded type.
      private static java.lang.String nonAnonymous​(java.lang.String typeName)
      Normalizes a type name if it is loaded by an anonymous class loader.
      static void register​(java.lang.String name, java.lang.ClassLoader classLoader, java.lang.ref.ReferenceQueue<? super java.lang.ClassLoader> referenceQueue, int identification, java.lang.Object typeInitializer)
      Registers a new loaded type initializer.
      java.lang.String toString()  
      • Methods inherited from class java.lang.ref.Reference

        clear, clone, enqueue, get, isEnqueued, reachabilityFence
      • Methods inherited from class java.lang.Object

        finalize, getClass, notify, notifyAll, wait, wait, wait
    • Field Detail

      • PROPERTY

        public static final java.lang.String PROPERTY
        A system property that allows to disable the use of the Nexus class which is normally injected into the system class loader.
        See Also:
        Constant Field Values
      • NO_QUEUE

        private static final java.lang.ref.ReferenceQueue<java.lang.ClassLoader> NO_QUEUE
        An type-safe constant for a non-operational reference queue.
      • TYPE_INITIALIZERS

        private static final java.util.concurrent.ConcurrentMap<Nexus,​java.lang.Object> TYPE_INITIALIZERS
        A map of keys identifying a loaded type by its name and class loader mapping their potential LoadedTypeInitializer where the class loader of these initializers is however irrelevant.
      • name

        private final java.lang.String name
        The name of a type for which a loaded type initializer is registered.
      • classLoaderHashCode

        private final int classLoaderHashCode
        The class loader's hash code upon registration.
      • identification

        private final int identification
        A random value that uniquely identifies a Nexus entry in order to avoid conflicts when applying the self-initialization strategy in multiple transformations.
    • Constructor Detail

      • Nexus

        private Nexus​(java.lang.Class<?> type,
                      int identification)
        Creates a key for identifying a loaded type initializer.
        Parameters:
        type - The loaded type for which a key is to be created.
        identification - An identification for the initializer to run.
      • Nexus

        private Nexus​(java.lang.String name,
                      java.lang.ClassLoader classLoader,
                      java.lang.ref.ReferenceQueue<? super java.lang.ClassLoader> referenceQueue,
                      int identification)
        Creates a key for identifying a loaded type initializer.
        Parameters:
        name - The name of a type for which a loaded type initializer is registered.
        classLoader - The class loader for which a loaded type initializer is registered.
        referenceQueue - The reference queue to notify upon the class loader's collection or null if no queue should be notified.
        identification - An identification for the initializer to run.
    • Method Detail

      • nonAnonymous

        private static java.lang.String nonAnonymous​(java.lang.String typeName)
        Normalizes a type name if it is loaded by an anonymous class loader.
        Parameters:
        typeName - The name as returned by Class.getName().
        Returns:
        The non-anonymous name of the given class.
      • initialize

        public static void initialize​(java.lang.Class<?> type,
                                      int identification)
                               throws java.lang.Exception

        Initializes a loaded type. This method must only be invoked via the system class loader.

        Important: This method must never be called directly but only by using a NexusAccessor.InitializationAppender which enforces to access this class for the system class loader to assure a VM global singleton. This avoids a duplication of the class if this nexus is loaded by different class loaders. For this reason, the last parameter must not use a Byte Buddy specific type as those types can be loaded by different class loaders, too. Any access of the instance is done using Java reflection instead.

        Parameters:
        type - The loaded type to initialize.
        identification - An identification for the initializer to run.
        Throws:
        java.lang.Exception - If an exception occurs.
      • register

        public static void register​(java.lang.String name,
                                    java.lang.ClassLoader classLoader,
                                    java.lang.ref.ReferenceQueue<? super java.lang.ClassLoader> referenceQueue,
                                    int identification,
                                    java.lang.Object typeInitializer)

        Registers a new loaded type initializer.

        Important: This method must never be called directly but only by using a NexusAccessor which enforces to access this class for the system class loader to assure a VM global singleton. This avoids a duplication of the class if this nexus is loaded by different class loaders. For this reason, the last parameter must not use a Byte Buddy specific type as those types can be loaded by different class loaders, too. Any access of the instance is done using Java reflection instead.

        Parameters:
        name - The name of the type for the loaded type initializer.
        classLoader - The class loader of the type for the loaded type initializer.
        referenceQueue - The reference queue to notify upon the class loader's collection which will be enqueued a reference which can be handed to clean(Reference) or null if no reference queue should be notified.
        identification - An identification for the initializer to run.
        typeInitializer - The type initializer to register. The initializer must be an instance of LoadedTypeInitializer where it does however not matter which class loader loaded this latter type.
      • clean

        public static void clean​(java.lang.ref.Reference<? super java.lang.ClassLoader> reference)

        Cleans any stale entries from this nexus. Entries are considered stale if their class loader was collected before a class was initialized.

        Important: This method must never be called directly but only by using a NexusAccessor which enforces to access this class for the system class loader to assure a VM global singleton. This avoids a duplication of the class if this nexus is loaded by different class loaders. For this reason, the last parameter must not use a Byte Buddy specific type as those types can be loaded by different class loaders, too. Any access of the instance is done using Java reflection instead.

        Parameters:
        reference - The stale reference to clean.
      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object
      • equals

        public boolean equals​(java.lang.Object other)
        Overrides:
        equals in class java.lang.Object
      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object