Yeah, but getting URLs simply, AND having some type-assurance over
the parameters you pass, are diametrically opposed goals. :)
Why would they be?
I have not looked at this in detail yet. A quick skim of it just
now suggests that it is a little sparse so far. What sort of
feedback/interaction are you looking for?
Currently it is really defined only for plugin writers and filter
writers. But it does lay some important groundwork (like WikiContext
and WikiPage being interfaces). Are the methods on them good or
not? What more is needed and what is not?
The point being - we need to define an "SDK" which is independent of
the latest craze. Something on which we can exert strong change
control and test binary compatibility against.
I would like to break our API into two pieces:
1. The stable SDK - that is, the org.apache.jspwiki.api package.
Won't change. You can rely on it. It is well-documented, though
sparse.
2. The "current" API. This is accessed in the old way of just
looking into the source code and trying to figure out WTF is going
on. Allows you to do extensive manipulation of stuff. We won't
guarantee it won't break, but it'll keep roughly the same all the time.
We have #2 currently, but no #1.
The chief motivation is that we have so many wonderful and nice
plugins written by people, and we haven't really cared about them at
all at this point. So while we're purposefully breaking everything,
I want to give them something they can rely on in the future.
The problem with building everything around a single UI library is
that it's brittle. If Stripes breaks compatibility, so shall we,
too. Not by choice, but by necessity. I want to get past that.
That is a feature -- the .action suffix is what causes the
StripesFilter to execute on the inbound side so that it can
populate ActionBeans with correct parameters, run any events that
are needed, check security, etc. However, the URLs are muddled
generally only for things like form POST addresses. Users would see
JSP URLs in their browser location bars. Directly addressing the
JSP would still work.
Unfortunately, they don't. Whenever you post something, and Stripes
returns it back, you *will* see the Action URL. Which means that
users can grab the URL, and send it somewhere and hey, they've got a
wrong/broken URL. The users don't *care* whether it's only after a
POST, it'll just happen randomly.
IMO, it's a bug.
By the way, the .action URLs also make it easy to create service
URLs for things that don't have JSPs. AJAX or JSON calls, for
example, could directly call the ActionBean they correspond to
rather than being threaded through an AJAX servlet. This is, as you
might imagine, incredibly useful. And with the integrated security
annotations I've developed, we will be able to do this in a very
secure way -- enforced and parameter-bound automatically through
the StripesFilter, and -- here is the payoff -- *without writing a
single line of code.*
For AJAX, yes, that's fine - because AJAX URLs can change since we
always send them over via the JS mechanism anyway. They're not
visible to the user anyway - might be to the developer, but not to
the user. But user-visible URLs?
StripesFilter works also for JSPs.
So on balance -- I understand you don't like the .action suffixes.
But they aren't what the user will see most of the time. And, they
make life a lot easier for Dirk and other people who want to build
more "web service" interfaces.
The problem is that users will see them *randomly*. And from what I
have learned, the user's don't understand random.
Could we continue to use WikiContext, with all of its page-centric
methods, as the superinterface for all actionbeans? Sure, but then
we would have to continue referencing read ("faking") the page for
those 'beans that have nothing to do with pages. This is why
calling getPage() for the user prefs wiki context, today, returns
"Main." That is confusing, and from the user's point of view an
error condition. I'd rather we stop using WikiContext this way --
that was what I meant by "overloading."
Fine, I just wouldn't like to call them ActionBeans on the API side,
since they imply Stripes. Besides, if WikiContext is an interface,
you can't use the ActionBeans anyway as the parent I/F. I'd rather
go with
AbstractWikiContext
+--WikiContext
+--GroupWikiContext
or something similar to that effect. The actual implementing classes
can then implement ActionBean.
/Janne
