Hi devs,

While I was joining the flink-avro enhancement and cleanup discussion
driven by Becket[1], I realized that there are some issues with the current
Flink API annotation usage in the source code.

As far as I am concerned, Flink wants to control the access/visibility of
APIs across modules and for downstreams. Since no OSGI is used(it should
not be used because of its complexity, IMHO), Flink decided to use a very
lightweight but manual solution: customized annotation like @Internal,
@Experimental, @PublicEvolving,
etc. This is a Flink only concept on top of JDK annotation and is therefore
orthogonal to @Deprecated or any other annotations offered by JDK. After
this concept has been used, APIs without one of these annotations are in
the kind of gray area which means they have no contract in the context of
this new concept. Without any given metadata they could be considered
as @Internal or @Experimental, because changes are allowed to be applied at
any time. But there is no clear definition and therefore different people
will understand it differently.

There are two options to improve it, as far as I could figure out:

option 1: All APIs must have one of those annotations. We should put some
effort into going through all source code and add missing annotations.
There were discussions[2] and activities going in this direction.
option 2: the community comes to a new consensus that APIs without
annotation equals one of @Internal, @Experimental, or @PublicEvolving. I
personally will choose @Internal, because it is the safest one. And if
@Internal is chosen as the default one, it could also be deprecated,
because no annotation equals @Internal. If it makes sense, I can create a
FLIP and help the community reach this consensus.

Both options have their own pros and cons. I would choose option 2, since
we will not end up with a lot of APIs marked as @Internal.

Looking forward to hearing your thoughts.

Best regards
Jing


[1] https://lists.apache.org/thread/7zsv528swbjxo5zk0bxq33hrkvd77d6f
[2] https://lists.apache.org/thread/zl2rmodsjsdb49tt4hn6wv3gdwo0m31o

Reply via email to