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 a
Hi Jing,
Thanks for bringing up the discussion. My two cents:
1. All the public methods / classes / interfaces MUST be annotated with one
of the @Experimental / @PublicEvolving / @Public. In practice, all the
methods by default inherit the annotation from the containing class, unless
annotated ot
Thanks Jing for starting this discussion.
For @Becket
> 1. All the public methods / classes / interfaces MUST be annotated with
one of the @Experimental / @PublicEvolving / @Public. In practice, all the
methods by default inherit the annotation from the containing class, unless
annotated otherwise
Hi Shammon,
Thanks for the reply.
Do we really need to have `@Internal` methods in an `@Public` interface or
> class? In general, if a class or interface is marked as `@Public `, it is
> better that their public methods should also be `@Public`, because even if
> marked as `@Internal`, users are
Hi Shammon,
Thanks for asking. @PublicEvolving is actually a very useful design that
developers can offer APIs as publicly accessible but still have changes to
introduce modifications afterwards between minor releases. Compared to it,
all @Public APIs can only be changed between major releases.
Be
Hi Becket,
Thanks for your reply with details.
> 2. I agree it would be too verbose to annotate every internal method /
> class / interface. Currently we already treat the methods / interfaces /
> classes without annotations as effectively @Internal.
>
Does it make sense to clearly define that
>
> Does it make sense to clearly define that APIs without annotation are
> internal APIs and should be used outside of Flink. And deprecate @Internal?
We can do this. Although I think it is OK to keep the @Internal annotation
in case extra clarity is needed sometimes.
Thanks,
Jiangjie (Becket)
We need the @Internal annotation for cases where a user-facing class has
methods entirely meant for internal uses.
It's not great that we have these cases to being with, but fixing that
is another story.
The semantics for non-annotated classes is already documented.
https://nightlies.apache.org
