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.+5 (and you owe me another beer that I didn't gave up this time!)
What do you think ?
Cool. I'll give a look at Xalan's build to see how it's done.
And I didn't tried to make you give up, but tried to convince you that API stability and ease of coding are somewhat antagonist concerns ! Now, counting the number of beers that I owe you, I think I'll have to buy a keg ;-)
Sylvain
-- Sylvain Wallez Anyware Technologies http://www.apache.org/~sylvain http://www.anyware-tech.com { XML, Java, Cocoon, OpenSource }*{ Training, Consulting, Projects } Orixo, the opensource XML business alliance - http://www.orixo.com
