Marking public APIs with @Public annotation #3419

In order to better communicate - in terms of semver - which our APIs are considered public we should introduce @Public annotation, and mark appropriate classes / methods etc. Note this is source level compatibility, not binary.

Note that there are libraries that provide such annotations like:

1. org.apiguardian:apiguardian-api:

@API(status = Status.STABLE)
@API(status = Status.EXPERIMENTAL)
@API(status = Status.INTERNAL)
@API(status = Status.MAINTAINED)
@API(status = Status.DEPRECATED)

2. audience-annotations in yetus

For reference, Flink's own @Public/@PublicEvolving/@Experimental/@Internal in org.apache.flink.annotation are the same idea, but they're internal to Flink (and shaded), so not meant to be pulled in as a standalone dependency.

Notes

• we have already @Experimental annotation.
• this could be done an an inverse way, so marking internal API, butin our case would be probably harder to do (or more code)