ClassHierarchyResolver (Java SE 26 & JDK 26)
Description: declaration: module: java.base, package: java.lang.classfile, interface: ClassHierarchyResolver
Keywords: java.lang.classfile.ClassHierarchyResolver interface

# Interface ClassHierarchyResolver

Functional Interface:
  This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.

@FunctionalInterface public interface ClassHierarchyResolver
Provides class hierarchy information for stack maps generation and verification. A class hierarchy resolver must be able to process all classes and interfaces encountered during these workloads.

See Java Virtual Machine Specification:
  4.10.1.2 Verification Type System
Since:
  24
See Also:
  - `ClassFile.ClassHierarchyResolverOption`
  - `StackMapTableAttribute`

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Interface
  Description
  `static interface`
  `ClassHierarchyResolver.ClassHierarchyInfo`
  Information about a resolved class.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `default ClassHierarchyResolver`
  `cached()`
  Returns a `ClassHierarchyResolver` that caches class hierarchy information from this resolver.
  `default ClassHierarchyResolver`
  `cached(Supplier<Map<ClassDesc, ClassHierarchyResolver.ClassHierarchyInfo>> cacheFactory)`
  Returns a `ClassHierarchyResolver` that caches class hierarchy information from this resolver.
  `static ClassHierarchyResolver`
  `defaultResolver()`
  Returns the default instance of `ClassHierarchyResolver` that gets `ClassHierarchyResolver.ClassHierarchyInfo` from system class loader with reflection.
  `ClassHierarchyResolver.ClassHierarchyInfo`
  `getClassInfo(ClassDesc classDesc)`
  Returns the `ClassHierarchyInfo` for a given class name, or `null` if the name is unknown to the resolver.
  `static ClassHierarchyResolver`
  `of(Collection<ClassDesc> interfaces, Map<ClassDesc, ClassDesc> classToSuperClass)`
  Returns a `ClassHierarchyResolver` that extracts class hierarchy information from collections of class hierarchy metadata.
  `static ClassHierarchyResolver`
  `ofClassLoading(ClassLoader loader)`
  Returns a `ClassHierarchyResolver` that extracts class hierarchy information via classes loaded by a class loader with reflection.
  `static ClassHierarchyResolver`
  `ofClassLoading(MethodHandles.Lookup lookup)`
  Returns a `ClassHierarchyResolver` that extracts class hierarchy information via classes accessible to a `MethodHandles.Lookup` with reflection.
  `static ClassHierarchyResolver`
  `ofResourceParsing(ClassLoader loader)`
  Returns a `ClassHierarchyResolver` that extracts class hierarchy information from `class` files located by a class loader.
  `static ClassHierarchyResolver`
  `ofResourceParsing(Function<ClassDesc, InputStream> classStreamResolver)`
  Returns a `ClassHierarchyResolver` that extracts class hierarchy information from `class` files returned by a mapping function.
  `default ClassHierarchyResolver`
  `orElse(ClassHierarchyResolver other)`
  Chains this `ClassHierarchyResolver` with another to be consulted if this resolver does not know about the specified class.

- ## Method Details

  - ### defaultResolver

    static ClassHierarchyResolver defaultResolver()
    Returns the default instance of `ClassHierarchyResolver` that gets `ClassHierarchyResolver.ClassHierarchyInfo` from system class loader with reflection. This default instance cannot load classes from other class loaders, such as the caller's class loader; it also loads the system classes if they are not yet loaded, which makes it unsuitable for instrumentation.
    Returns:
      the default instance of `ClassHierarchyResolver` that gets `ClassHierarchyResolver.ClassHierarchyInfo` from system class loader with reflection

  - ### getClassInfo

    ClassHierarchyResolver.ClassHierarchyInfo getClassInfo(ClassDesc classDesc)
    Returns the `ClassHierarchyInfo` for a given class name, or `null` if the name is unknown to the resolver.

    This method is called by the Class-File API to obtain the hierarchy information of a class or interface; users should not call this method. The symbolic descriptor passed by the Class-File API always represents a class or interface.

    Parameters:
      `classDesc` - descriptor of the class
    Returns:
      the `ClassHierarchyInfo` for a given class name, or `null` if the name is unknown to the resolver
    Throws:
      `IllegalArgumentException` - if a class shouldn't be queried for hierarchy, such as when it is inaccessible

  - ### orElse

    default ClassHierarchyResolver orElse(ClassHierarchyResolver other)
    Chains this `ClassHierarchyResolver` with another to be consulted if this resolver does not know about the specified class.
    Implementation Requirements:
      The default implementation returns resolver implemented to query `other` resolver in case this resolver returns `null`.
    Parameters:
      `other` - the other resolver
    Returns:
      the chained resolver

  - ### cached

    default ClassHierarchyResolver cached(Supplier<Map<ClassDesc, ClassHierarchyResolver.ClassHierarchyInfo>> cacheFactory)
    Returns a `ClassHierarchyResolver` that caches class hierarchy information from this resolver. The returned resolver will not update if the query results from this resolver changed over time. The thread safety of the returned resolver depends on the thread safety of the map returned by the `cacheFactory`.
    Implementation Requirements:
      The default implementation returns a resolver holding an instance of the cache map provided by the `cacheFactory`. It looks up in the cache map, or if a class name has not yet been queried, queries this resolver and caches the result, including a `null` that indicates unknown class names. The cache map may refuse `null` keys and values.
    Parameters:
      `cacheFactory` - the factory for the cache
    Returns:
      a `ClassHierarchyResolver` that caches class hierarchy information from this resolver

  - ### cached

    default ClassHierarchyResolver cached()
    Returns a `ClassHierarchyResolver` that caches class hierarchy information from this resolver. The returned resolver will not update if the query results from this resolver changed over time. The returned resolver is not thread-safe.

        MethodHandles.Lookup lookup = ...;
        ClassHierarchyResolver resolver = ClassHierarchyResolver.ofClassLoading(lookup).cached();

    Implementation Requirements:
      The default implementation calls `cached(Supplier)` with `HashMap` supplier as `cacheFactory`.
    Returns:
      a `ClassHierarchyResolver` that caches class hierarchy information from this resolver

  - ### ofResourceParsing

    static ClassHierarchyResolver ofResourceParsing(Function<ClassDesc, InputStream> classStreamResolver)
    Returns a `ClassHierarchyResolver` that extracts class hierarchy information from `class` files returned by a mapping function. The mapping function should return `null` if it cannot provide a `class` file for a class name. Any `IOException` from the provided input stream is rethrown as an `UncheckedIOException` in `getClassInfo(ClassDesc)`.
    Parameters:
      `classStreamResolver` - maps class descriptors to `class` file input streams
    Returns:
      a `ClassHierarchyResolver` that extracts class hierarchy information from `class` files returned by a mapping function

  - ### ofResourceParsing

    static ClassHierarchyResolver ofResourceParsing(ClassLoader loader)
    Returns a `ClassHierarchyResolver` that extracts class hierarchy information from `class` files located by a class loader.
    Parameters:
      `loader` - the class loader, to find class files
    Returns:
      a `ClassHierarchyResolver` that extracts class hierarchy information from `class` files located by a class loader

  - ### of

    static ClassHierarchyResolver of(Collection<ClassDesc> interfaces, Map<ClassDesc, ClassDesc> classToSuperClass)
    Returns a `ClassHierarchyResolver` that extracts class hierarchy information from collections of class hierarchy metadata.
    Parameters:
      `interfaces` - a collection of classes known to be interfaces
      `classToSuperClass` - a map from classes to their super classes
    Returns:
      a `ClassHierarchyResolver` that extracts class hierarchy information from collections of class hierarchy metadata

  - ### ofClassLoading

    static ClassHierarchyResolver ofClassLoading(ClassLoader loader)
    Returns a `ClassHierarchyResolver` that extracts class hierarchy information via classes loaded by a class loader with reflection.
    Parameters:
      `loader` - the class loader
    Returns:
      a `ClassHierarchyResolver` that extracts class hierarchy information via classes loaded by a class loader with reflection

  - ### ofClassLoading

    static ClassHierarchyResolver ofClassLoading(MethodHandles.Lookup lookup)
    Returns a `ClassHierarchyResolver` that extracts class hierarchy information via classes accessible to a `MethodHandles.Lookup` with reflection. If the class resolved is inaccessible to the given lookup, `getClassInfo(ClassDesc)` throws `IllegalArgumentException` instead of returning `null`.
    Parameters:
      `lookup` - the lookup, must be able to access classes to resolve
    Returns:
      a `ClassHierarchyResolver` that extracts class hierarchy information via classes accessible to a `MethodHandles.Lookup` with reflection