Package org.atmosphere.nativeimage

Interface NativeImageMetadataProvider

All Known Implementing Classes:
CoreNativeImageMetadataProvider, PoolNativeImageMetadataProvider
public interface NativeImageMetadataProvider
Lets a module declare what it needs at runtime that a native image cannot infer — the classes it constructs by name, and the resources it reads.

Ahead-of-time compilation keeps only what it can prove reachable. A class named in a configuration string and loaded with IOUtils.loadClass is reachable from nothing, so it is dropped, and the first hint of trouble is a ClassNotFoundException at runtime — often swallowed, as it was for broadcaster caches, where the result was every annotated endpoint silently failing to register.

Modules implement this and register it in META-INF/services/org.atmosphere.nativeimage.NativeImageMetadataProvider. The framework merges every provider it finds (NativeImageMetadata), which matters because atmosphere-ai, atmosphere-mcp, atmosphere-agent and others all load classes by name and none of them can be described from atmosphere-runtime. A module that adds a reflective lookup declares it next to the code that does the lookup, rather than in a central list nobody remembers to update.

Consumers are the Spring Boot hints registrar, the Quarkus build step, and the generated GraalVM metadata embedded in each jar. The last of those means a plain servlet deployment with no integration module still gets everything — see META-INF/native-image in atmosphere-runtime.

Implementations must be side-effect free and cheap to construct: they are instantiated during image build and during startup, before the framework exists.

  • Method Summary

    Modifier and Type
    Method
    Description
    default boolean
    isAvailable()
    Whether this provider applies to the current classpath.
    String
    name()
    Identifier for logs and the generated metadata's provenance comment.
    default int
    priority()
    Ordering hint; higher runs first.
    default Collection<String>
    reflectiveTypes()
    Fully-qualified names of types that are constructed, inspected or invoked reflectively — typically anything selected by an init-param or read from a ServiceLoader file.
    default Collection<String>
    resourcePatterns()
    Resource patterns that must survive into the image — ServiceLoader files above all, since a missing one turns a discovered implementation into a silently absent one.
    default String
    typeReachedCondition()
    A type whose reachability gates every reflective type this provider declares, emitted as GraalVM's "condition": {"typeReached": ...}.

  • Method Details

    • name

      String name()
      Identifier for logs and the generated metadata's provenance comment.

    • reflectiveTypes

      default Collection<String> reflectiveTypes()
      Fully-qualified names of types that are constructed, inspected or invoked reflectively — typically anything selected by an init-param or read from a ServiceLoader file.

      Names rather than Class literals: a provider must be able to declare a type from an optional dependency without forcing that dependency to be present, which is the same reason the framework's own AtmosphereReflectiveTypes is a list of strings.

      Returns:
      type names, never null

    • resourcePatterns

      default Collection<String> resourcePatterns()
      Resource patterns that must survive into the image — ServiceLoader files above all, since a missing one turns a discovered implementation into a silently absent one.
      Returns:
      patterns understood by GraalVM's resource configuration, never null

    • isAvailable

      default boolean isAvailable()
      Whether this provider applies to the current classpath. A provider covering an optional dependency returns false when that dependency is absent, so its types are not registered into an image that cannot contain them.
      Returns:
      true to include this provider's metadata

    • typeReachedCondition

      default String typeReachedCondition()
      A type whose reachability gates every reflective type this provider declares, emitted as GraalVM's "condition": {"typeReached": ...}.

      isAvailable() is evaluated where the metadata is collected — for the file shipped inside atmosphere-runtime, that is the framework's own build, where optional dependencies are present. A provider covering an optional dependency therefore also names a type from that dependency here, so an application image without it skips the registration instead of asking GraalVM to link a type whose supertype is missing.

      Returns:
      a fully-qualified type name, or null for unconditional

    • priority

      default int priority()
      Ordering hint; higher runs first. Only affects the order metadata is emitted, never whether it is emitted — registration is a union, so no provider can suppress another's types.
      Returns:
      the priority, default 0