Complete the Third-Party API in Native Image

[christianwimmer]

TL;DR

Users of native image currently rely on internals of the image generator, for a variety of reasons. We need to expand the API so that it covers the use cases of all current users. Eventually, the internals of the image generator will no longer be published on Maven.

Goals

Expand the API so that the following parts are covered by proper API:

• JNI / Resource / Proxy / Serialization registration: These are currently not exposed as public API, but really for no good reason. The API will be a small facade for the already existing classes.
• Provide API to query annotations without initializing all annotation classes: The getAnnotation method of Class, Method, and Field triggers initialization of all annotation classes of that member. The image generator already has a mechanism to load a single annotation without initializing the remaining annotation classes (see Native Image Committer Community Meeting 2022-06-30 #4687 for some details). This will be exposed as proper API.
• Add API options that replace the current -H: options for frequently used options.

Move the following parts to the API project, so that for pragmatic reasons users can rely on it, but mark it clearly that these parts are not considered stable API:

• AutomaticFeature: While the Feature interface is API, the annotation AutomaticFeature is not in the API. That is intentional: if a feature is necessary, then it should be added via the --features=... option in a native-image.properties file.
• Substitution system annotations (Substitute, Alias, TargetClass, ...): The substitution system is powerful, but it is easy to make hard-to-detect mistakes. Until all important libraries have necessary code changes moved upstream and released, there is no good way to avoid substitutions. Therefore, move the annotations into the API module, but explicitly document them as not being supported API.

Non-Goals

Add new registration mechanism or new functionality to the image generator. Everything added to the API is already present in the image generator in the form of non-API classes.

[zakkak]

Related issue: #4862

[fniephaus]

This has shipped with the 22.3 release. 🎉

[Suvankarmnvr]

@zakkak