incubator-jspwiki-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Harry Metske <harry.met...@gmail.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 16:37:08 GMT
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 <Janne.Jalkanen@ecyrd.com>

>
>> 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
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message