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
