incubator-jspwiki-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Janne Jalkanen <Janne.Jalka...@ecyrd.com>
Subject Re: svn commit: r773455 - in /incubator/jspwiki/trunk: ./ src/java/org/apache/wiki/ src/java/org/apache/wiki/api/ src/java/org/apache/wiki/content/ src/java/org/apache/wiki/parser/ src/java/org/apache/wiki/plugin/ src/java/org/apache/wiki/search/ src
Date Tue, 12 May 2009 07:07:31 GMT
>
> 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

Mime
View raw message