Puh, I need some beer... Sylvain Wallez wrote: > Take another example : CocoonComponentManager.getCurrentEnvironment(). > We need this method to have the "public" access modifier because we need > this information to implement SitemapSource and other pipeline > machinery. But we all agree that using it for "normal" components is a > hack that should be prohibited. Exactly.
> > Now imagine the following story : an innocent Cocoon user downloads > Cocoon 2.1, digs the javadoc and finds this method. "Cool", he says, > "this public method gives me access to the Environment that provides so > much interesting data. I'll use it there, and there, and there". Now we, > Cocoon devs, decide to refactor the internal pipeline machinery for some > reason, and finally no more need this method. At we consider its use as > an internal hack, we remove it. Now our innocent users sees the new > Cocoon 2.1.1 release which is told to be faster. "Cool", he says, "let's > drop the new jars in my WEB-INF/lib". And bing bang, NoSuchMethodError > all over the place because the method he used has disappeared. > > As, you can see, there's a big difference between the "public" access > modifier required by the Java syntactic rules, and the public API that > is safe for "innocent users" to use. And that's why I'm proposing : a > restricted official public API. People using it will know that it will > never change. And if it has to (e.g. Composable --> Serviceable), then > new classes will be created. And people using syntactically public but > not officially public members and methods will be warned that doing so > may lead their code to be broken in the future. Yes, I totally agree. But again :) my point was that it doesn't play a role if you say an instance variable is public or private or protected. If someone needs it it will be used anyway, and if I declare it as public it doesn't mean that it can safely be used. So, yes we agree here! > Our users need API stability, and not all public items of our huge code > base can be considered as "stable API". That's the whole point. And > going through this process of tagging our code base with "@usage" can > force us to better design the extensions points of our components. > > What do you think ? > +5 (and you owe me another beer that I didn't gave up this time!) Carsten
