flink-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Robert Metzger <rmetz...@apache.org>
Subject [ANNOUNCE] Please annotate public interfaces!
Date Fri, 05 Feb 2016 14:07:27 GMT
Hi,

tl;dr: we now have @Public, @Internal, @Experimental annotations. Check
your stuff before the release!

Fabian and I spend some time the last weeks to annotate all classes we
consider to be userfacing and stable with the "*@Public*" annotation. I
just pushed those changes to master.

There is also an annotation "*@Internal*" for marking interfaces users
should not use because they are internal to the system (for example
"DataStream.getId()").

The annotation "*@Experimental*" marks unstable methods within stable
classes (for example SingleOutputStreamOperator.uid()).
Also note that we should also annotate @Deprecated methods with
@Experimental so that they are not part of the stable interface (this works
only before the 1.0 release). I checked that all current @Deprecated
annotations are excluded.


*I would like to ask everyone to spend some time before the 1.0 release to
go through some core classes and see if there is anything we forgot.*
*We will not be able to touch methods and classes which are public after
the 1.0 release.*

Some areas where I feel we should check closely are the following:
- InputFormats
- State-related classes
- Windowing related classes
- DataStream API (global() / forward(); output to files; ... ).

Fabian and I also realized that there are some downsides to this annotation
approach.
a) By not annotating all classes, its easy to forget some classes. And its
not obvious to users that "no annotation" means "not public".

b) For example the "SourceFunction.SourceContext" interface is @Public
because users use the methods of the interface.
However, the underlying implementations are internal to Flink (users will
most likely not implement their own SourceContexts). Adding a new method to
the SourceContext interface will break its compatibilty (because users
would need to implement the new method), however, for API users it does not
matter when we are adding new methods.
We decided to make the interface @Public, but we added a comment explaining
the issue.
If we want to add a method after the 1.0 release, we can define an exclude
in the maven plugin which enforces the interface stability.


For making the whole annotation analysis business a bit easier, I'm
currently working on a little tool to output a list of public classes and
methods. I'll post that on the mailing list at a later point.

Regards,
Robert

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message