Module java.base
Package java.lang.classfilePREVIEW

# 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
`ClassHierarchyResolver` is a preview API of the Java platform.
Programs can only use `ClassHierarchyResolver` when preview features are enabled.
Preview features may be removed in a future release, or upgraded to permanent features of the Java platform.
Provides class hierarchy information for generating correct stack maps during code building.

Since:
  22

- ## Nested Class Summary

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

- ## Method Summary

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

- ## Method Details

  - ### defaultResolver

    static ClassHierarchyResolverPREVIEW defaultResolver()
    Returns the default instance of ClassHierarchyResolverPREVIEW that gets `ClassHierarchyResolver.ClassHierarchyInfo`PREVIEW from system class loader with reflection.
    Returns:
      the default instance of ClassHierarchyResolverPREVIEW that gets `ClassHierarchyResolver.ClassHierarchyInfo`PREVIEW from system class loader with reflection

  - ### getClassInfo

    ClassHierarchyResolver.ClassHierarchyInfoPREVIEW getClassInfo(ClassDesc classDesc)
    Returns the `ClassHierarchyResolver.ClassHierarchyInfo`PREVIEW for a given class name, or null if the name is unknown to the resolver.
    Parameters:
      `classDesc` - descriptor of the class
    Returns:
      the `ClassHierarchyResolver.ClassHierarchyInfo`PREVIEW 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

  - ### orElse

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

  - ### cached

    default ClassHierarchyResolverPREVIEW cached(Supplier<Map<ClassDesc,ClassHierarchyResolver.ClassHierarchyInfoPREVIEW>> cacheFactory)
    Returns a ClassHierarchyResolver that caches class hierarchy information from this resolver. The returned resolver will not update if delegate resolver returns differently. 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 resolver holding an instance of the cache map provided by the `cacheFactory`. It asks the cache map always first and fills the cache map with all resolved and also unresolved class info. The cache map may refuse `null` keys and values.
    Parameters:
      `cacheFactory` - the factory for the cache
    Returns:
      the ClassHierarchyResolver with caching

  - ### cached

    default ClassHierarchyResolverPREVIEW cached()
    Returns a ClassHierarchyResolver that caches class hierarchy information from this resolver. The returned resolver will not update if delegate resolver returns differently. 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:
      the ClassHierarchyResolver

  - ### ofResourceParsing

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

  - ### ofResourceParsing

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

  - ### of

    static ClassHierarchyResolverPREVIEW of(Collection<ClassDesc> interfaces, Map<ClassDesc,ClassDesc> classToSuperClass)
    Returns a ClassHierarchyResolverPREVIEW 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:
      the ClassHierarchyResolverPREVIEW

  - ### ofClassLoading

    static ClassHierarchyResolverPREVIEW ofClassLoading(ClassLoader loader)
    Returns a ClassHierarchyResolver that extracts class hierarchy information via the Reflection API with a ClassLoader.
    Parameters:
      `loader` - the class loader
    Returns:
      the class hierarchy resolver

  - ### ofClassLoading

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