I have a slightly different take on this. I've been trying to embed Flume within the Log4j 2 client and have found that things that look like they are extendable actually aren't and that Flume configuration is actually pretty brittle (the properties don't seem to be isolated to one place but percolate through several), such that if you want to create a configuration using XML, JSON or anything else you are forced to convert that into the property syntax. I've also noticed that the Sources, Sinks and Channels are all defined in enums - another brittle construct that puts third party add-ons at a disadvantage from stuff packaged with Flume.
I tackled a lot of these issues in Log4j 2 and came up with different solutions for them. I used annotations, but not specifically to mark things as public or private but to identify "plugins". For example, Sources, Sinks and Channels could all be annotated and be made available by a short name specified on the annotation which would get rid of the need for the enums. Of course, these also identify components that can be used as models for developers and users to emulate to add their own components. While addition annotations as guidance to programmers is OK, you can accomplish the same thing just by writing good Javadoc. I'm more a fan of using annotations for things that are a bit more useful. Ralph On Aug 14, 2012, at 2:38 AM, Mike Percy wrote: > It seems we have reached a point in some of the Flume components where we > want to add features but that means adding new interfaces to maintain > backwards compatibility. While this is natural, the more we do it, and the > more we cast from interface to interface, the less readable and consistent > the codebase becomes. Also, we have exposed much of our code as public > class + public method, even when APIs may not be intended as stable > extension points, for testing or other reasons. A few years ago, Hadoop > faced this problem and ended up implementing annotations to document APIs > as @Stable/@Evolving, @Public/@Limited/@Private. See < > https://issues.apache.org/jira/browse/HADOOP-5073> for the history on that. > > I would like to propose the adoption of a similar mechanism in Flume, in > order to give us more wiggle room in the future for evolutionary > development. Thoughts? > > Right now, I feel we would get most of the bang for the buck simply by > adding two annotations: @Public and @Internal, which to me means "you can > subclass or instantiate this directly", or "you can't directly use this if > you expect future compatibility". > > Regards, > Mike
