I don't feel qualified enough to interfere with the design discussions, but I do want stress the importance of a good set of working JUnit tests, and that it should be the first thing to fix, saving us a lot of time in the next steps (designing/coding/testing). So, for that part, many credits to Andrew, I really sometimes wonder if you ever sleep :-)
Another thing, I don't have a clear view on the general use of JSPWiki, is the majority just installing it in their AppServer and using it as is, or is there a serious crowd out there embedding JSPWiki in something else and really using the API's we have had some many discussions on. So I can't really judge on the importance on having this clear and high quality public (Java-level) API. Maybe it would be good to describe some use cases ? regards, Harry 2009/5/12 Janne Jalkanen <[email protected]> > >> With respect to event-firing, it cannot be a matter of taste. From a >> JCR node lifecycle standpoint, we need certain events to fire at >> particular times. In JSPWiki, this always happens from inside manager >> classes, and so ContentManager is clearly the right place to fire node >> events. How could it not be? For page saves, here are the options we >> have: >> > > I don't, frankly, give a crap who fires events and where. It's all internal > code. > > But I *do* care about presenting a simple interface to developers (as > opposed to committers). APIs should be our "first class citizens" and we > should have a clear, concise API instead of hundreds of classes and > thousands of methods which are all lumped together with the instructions > "just read the javadocs, and oh, we've documented the ones which you're not > supposed to use, except that we mostly haven't." > > Committers and contributors are expected to know the internal structure and > know which should be logically placed where. Developers aren't. And forcing > them to wade through hundreds of pages of Javadoc documentation, no matter > how good, is akin to learning a new language. And that is not good. > > Because of the way Java works, we are forced to make some methods public in > some classes, even though most of the time those should not be public, but > somehow limited to "classes of org.apache.wiki only". The fact that a > method is public does not mean that it should be callable by a developer. > You can say that those methods should be documented, but I am saying that > *most* of the methods that we have are like that. > > I do appreciate the desire to abstract interactions with >> ContentManager away from plugin developers. From the standpoint of >> "making it easy for developers to do common things easily," it does >> simplify things to have WikiPage.save(). So I take your point on this, >> and to that end we should remove the @deprecated annotation from >> WikiPage.save(). >> > > Look, I quite spent some time trying to figure out what would be a nice and > common API towards developers. My *new* code for 3.0 gets @deprecated for no > reason and replaced without any discussion whatsoever. My suggestion for an > API package and a simplified developer offering is a "non-starter" and > that's pretty much the extent of the discussion. > > So is it any wonder I get a bit brusque about it? > > We need to talk more about what we're doing and where we're planning to > take this thing. Getting unit tests to run is admirable (and thank you for > it), but it is not enough. No unit tests and source control are substitutes > for developer discussion. > > I, for one, want to see our developer offering simplified, and I've > provided the api package as a suggestion on how that should be handled. I do > believe that it would be good to split our offering to a "jspwiki-api.jar" > and "jspwiki.jar", so that we can exert stronger change control to the > classes and interfaces in jspwiki-api.jar, which gives a) committers freedom > to change internal code more radically, if needed, and b) give the third > parties and developers something that they can grasp easily, build their > stuff on top of, and rely on so that they don't have to rewrite all plugins > moving from 3.0 to 3.1. > > /Janne >
