Package: org.codehaus.groovy.reflection

## [Java] Class ClassInfo

- org.codehaus.groovy.reflection.ClassInfo

- All Implemented Interfaces and Traits:
    Finalizable

      public class ClassInfo
      extends Object
      implements Finalizable

  Handle for all information we want to keep about the class

  This class handles caching internally and it's advisable to not store references directly to objects of this class. The static factory method ClassInfo.getClassInfo should be used to retrieve an instance from the cache. Internally the `Class` associated with a `ClassInfo` instance is kept as WeakReference, so it not safe to reference and instance without the Class being either strongly or softly reachable.

- - ### Nested Class Summary

    Nested classes
    Modifiers | Name | Description
    --- | --- | ---
    `interface` | `ClassInfo.ClassInfoAction` | Functional interface for performing actions on `ClassInfo` instances.

  - ### Field Summary

    Fields
    Modifiers | Name | Description
    --- | --- | ---
    `int` | `hash` |

  - ### Methods Summary

    Methods
    Type Params | Return Type | Name and description
    --- | --- | ---
    `` | `public static void` | `clearModifiedExpandos()` Clears all modified `ExpandoMetaClass` instances for all classes.
    `` | `public void` | `finalizeReference()`
    `` | `public static int` | `fullSize()` Returns the total size including soft-referenced (potentially garbage-collectable) entries.
    `` | `public static Collection<ClassInfo>` | `getAllClassInfo()` Returns all cached class information across the runtime.
    `` | `public ClassLoaderForClassArtifacts` | `getArtifactClassLoader()` Returns the class loader for loading class artifacts (e.g., compiled bytecode).
    `` | `public CachedClass` | `getCachedClass()` Returns the cached class representation for this class.
    `` | `public static ClassInfo` | `getClassInfo(Class cls)` Retrieves the `ClassInfo` for the given class.
    `` | `public final MetaClass` | `getMetaClass()` Returns the `MetaClass` for the `Class` associated with this `ClassInfo`.
    `` | `public MetaClass` | `getMetaClass(Object obj)` Returns the metaclass for an object.
    `` | `public MetaClass` | `getMetaClassForClass()` Returns the most appropriate metaclass for this class.
    `` | `public ExpandoMetaClass` | `getModifiedExpando()` Returns the modified `ExpandoMetaClass` for this class, if one exists.
    `` | `public MetaClass` | `getPerInstanceMetaClass(Object obj)` Returns the per-instance metaclass for the given object, if one has been set.
    `` | `public MetaClass` | `getStrongMetaClass()` Returns the strong (immutable) metaclass for this class, if one has been set.
    `` | `public final Class<?>` | `getTheClass()` Returns the `Class` associated with this `ClassInfo`.
    `` | `public int` | `getVersion()` Returns the version number of this class information.
    `` | `public MetaClass` | `getWeakMetaClass()` Returns the weak (mutable) metaclass for this class, if one has been set.
    `` | `public boolean` | `hasPerInstanceMetaClasses()` Returns whether this class has any per-instance metaclasses associated with its objects.
    `` | `public void` | `incVersion()` Increments the version number and invalidates call sites.
    `` | `public void` | `lock()` Acquires a lock for this class information.
    `` | `public static void` | `onAllClassInfo(ClassInfo.ClassInfoAction action)` Executes the given action on all cached class information.
    `` | `public static void` | `remove(Class<?> cls)` Removes a `ClassInfo` from the cache.
    `` | `public void` | `setPerInstanceMetaClass(Object obj, MetaClass metaClass)` Sets the per-instance metaclass for the given object.
    `` | `public void` | `setStrongMetaClass(MetaClass answer)` Sets the strong (immutable) metaclass for this class.
    `` | `public void` | `setWeakMetaClass(MetaClass answer)` Sets the weak (mutable) metaclass for this class.
    `` | `public static int` | `size()` Returns the number of cached class information entries.
    `` | `public void` | `unlock()` Releases the lock for this class information.

  - ### Inherited Methods Summary

    Inherited Methods
    Methods inherited from class | Name
    --- | ---
    `class Object` | `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### public final int hash

  - ### Method Detail

    - #### public static void clearModifiedExpandos()

      Clears all modified `ExpandoMetaClass` instances for all classes. Removes strong references to metaclasses and disassociates them from their class information.

    - #### public void finalizeReference()

    - #### public static int fullSize()

      Returns the total size including soft-referenced (potentially garbage-collectable) entries.

      Returns:
        the full count of class information entries

    - #### public static Collection<ClassInfo> getAllClassInfo()

      Returns all cached class information across the runtime.

      Returns:
        a collection of all cached class info objects

    - #### public ClassLoaderForClassArtifacts getArtifactClassLoader()

      Returns the class loader for loading class artifacts (e.g., compiled bytecode). Lazily initializes on first access.

      Returns:
        the artifact class loader

    - #### public CachedClass getCachedClass()

      Returns the cached class representation for this class. Lazily initializes on first access.

      Returns:
        the cached class

    - #### public static ClassInfo getClassInfo(Class cls)

      Retrieves the `ClassInfo` for the given class. Lazily creates one if not already cached.

      Parameters:
        `cls` - the class to get information for
      Returns:
        the class information, or `null` if `cls` is `null`

    - #### public final MetaClass getMetaClass()

      Returns the `MetaClass` for the `Class` associated with this `ClassInfo`. If no `MetaClass` exists one will be created.

      It is not safe to call this method without a `Class` associated with this `ClassInfo`. It is advisable to always retrieve a ClassInfo instance from the cache by using the static factory method ClassInfo.getClassInfo to ensure the referenced Class is strongly reachable.

      Returns:
        a `MetaClass` instance

    - #### public MetaClass getMetaClass(Object obj)

      Returns the metaclass for an object. If the object has a per-instance metaclass, returns that; otherwise returns this class's metaclass.

      Parameters:
        `obj` - the object to get the metaclass for
      Returns:
        the metaclass for the object

    - #### public MetaClass getMetaClassForClass()

      Returns the most appropriate metaclass for this class. Prefers strong metaclass if available, then weak metaclass if valid, otherwise the default.

      Returns:
        the metaclass for this class

    - #### public ExpandoMetaClass getModifiedExpando()

      Returns the modified `ExpandoMetaClass` for this class, if one exists.

      Returns:
        the modified expando metaclass, or `null` if not modified or not an ExpandoMetaClass

    - #### public MetaClass getPerInstanceMetaClass(Object obj)

      Returns the per-instance metaclass for the given object, if one has been set.

      Parameters:
        `obj` - the object to get the per-instance metaclass for
      Returns:
        the per-instance metaclass, or `null` if not set

    - #### public MetaClass getStrongMetaClass()

      Returns the strong (immutable) metaclass for this class, if one has been set. A strong reference keeps the metaclass in memory regardless of garbage collection.

      Returns:
        the strong metaclass, or `null` if not set

    - #### public final Class<?> getTheClass()

      Returns the `Class` associated with this `ClassInfo`.

      This method can return `null` if the `Class` is no longer reachable through any strong or soft references. A non-null return value indicates that this `ClassInfo` is valid.

      Returns:
        the `Class` associated with this `ClassInfo`, else `null`

    - #### public int getVersion()

      Returns the version number of this class information. The version increments when the metaclass is modified (e.g., methods/properties added).

      Returns:
        the current version

    - #### public MetaClass getWeakMetaClass()

      Returns the weak (mutable) metaclass for this class, if one has been set. A weak reference allows garbage collection of the metaclass when no longer needed.

      Returns:
        the weak metaclass, or `null` if not set or if it has been garbage collected

    - #### public boolean hasPerInstanceMetaClasses()

      Returns whether this class has any per-instance metaclasses associated with its objects.

      Returns:
        `true` if one or more per-instance metaclasses have been set; `false` otherwise

    - #### public void incVersion()

      Increments the version number and invalidates call sites. Called when metaclass modifications occur (e.g., adding methods to an `ExpandoMetaClass`).

    - #### public void lock()

      Acquires a lock for this class information. Used to synchronize modifications to metaclass and per-instance metaclass maps.

    - #### public static void onAllClassInfo(ClassInfo.ClassInfoAction action)

      Executes the given action on all cached class information. Allows processing of all classes currently tracked by the runtime.

      Parameters:
        `action` - the action to execute on each ClassInfo

    - #### public static void remove(Class<?> cls)

      Removes a `ClassInfo` from the cache. This is useful in cases where the Class is parsed from a script, such as when using GroovyClassLoader#parseClass, and is executed for its result but the Class is not retained or cached. Removing the `ClassInfo` associated with the Class will make the Class and its ClassLoader eligible for garbage collection sooner that it would otherwise.

      Parameters:
        `cls` - the Class associated with the ClassInfo to remove from cache

    - #### public void setPerInstanceMetaClass(Object obj, MetaClass metaClass)

      Sets the per-instance metaclass for the given object. Per-instance metaclasses override the class-level metaclass for that specific object.

      Parameters:
        `obj` - the object to associate with a metaclass
        `metaClass` - the metaclass to set, or `null` to remove the association

    - #### public void setStrongMetaClass(MetaClass answer)

      Sets the strong (immutable) metaclass for this class. Increments the version number and manages ExpandoMetaClass registry.

      Parameters:
        `answer` - the metaclass to set, or `null` to clear

    - #### public void setWeakMetaClass(MetaClass answer)

      Sets the weak (mutable) metaclass for this class. Clears the strong metaclass and increments the version number.

      Parameters:
        `answer` - the metaclass to set, or `null` to clear

    - #### public static int size()

      Returns the number of cached class information entries.

      Returns:
        the count of cached ClassInfo instances

    - #### public void unlock()

      Releases the lock for this class information.