Since there seems to be some perception that my comments are overly critical I'll preface this with the note that my entire motivation for writing this is in hope that I'll be able to continue to use JSPWiki 3.0 following the migration. There are a number of factors that effect that, the biggest being time available. [Apologies for the length.]
As Andrew has alluded, I'm not one who appreciates complexity for complexity' sake. I doubt Janne is either and I'm assuming his motivations for this are as he has stated. Reading over his comments above (27/Dec/08 03:26 AM) I think I agree with most of them, particularly that our priority is to produce the WikiEngine. I certainly don't require an API to that, which would only limit my abilities. [And *please* don't create private packages or begin using dashes in package names. Ugh.]
In the case of the JAXP API I can see the rationale for separating the API from the implementations, since the latter are derived from a number of disparate code bases. But in this case we are developing a wiki, which traditionally has been one of the simplest software applications, and we're developing an implementation that is: (a) likely to be the main if only implementation; (b) has no prior API commitments; and (c) is going to break all previous implementations, given it is going to (by design) recommend and/or require that all previous extensions (frameworks, plugins, etc.) use the new implementation since that implementation is guaranteed to change (with at least a package name change). This latter point might seem to suggest the need for an API, but that would also be satisfied by a relatively stable implementation (which has been the status quo). A package name change would maintain that stability more than changes to the fundamental architecture.
I must confess that I don't know why we really need a separate API package. For the past few years I've been able to follow the changes to the implementation as it has gradually gone from version to version. Would such an API be any more stable? Really? I'm probably a good test case on how much access to the innards of the engine will be available via the API. While Janne is rightfully critical of my armchair statements, not having attempted to migrate my Assertion Framework to 3.0, at this point I'd be a fool to do so even if I had the time. It's a bit of a chicken and an egg problem, as I'd much prefer to wait until the 3.0 code has stabilised before doing that, yet I'd be the first to note any deficiencies for extension classes as I hit those limitations, so any API 1.0 would likely need to become an API 1.1 as I found places in the API that needed opening.
While I'd really hate to lock the project into the 2.x code, I'm going to have a tough time convincing management of what is (to an outside observer) going to look like architectural changes with few if any user benefits. I.e., I'd be spending a large amount of time coding to remain with the 3.0 code base with little obvious benefit in the outward application. I'd have to rewrite all of the custom plugins (which includes all the CeryleWikiPlugins plus others not publicly available), the Assertion Framework, and (on the side, unrelated to paid work) all of the integration code used to make JSPWiki work embedded in Ceryle (if that will even be still possible, which remains to be seen since they're fairly tightly integrated). I don't know how much work that'd be but it hardly sounds trivial.
Merely changing the package names is by comparison almost a trivial exercise (accomplished e.g., via a sed script). While not wanting to sound sour about 3.0 you might begin to see that my perspective on this is based on looking ahead at what sounds like a great deal of work (with little in-house support for it), which is why I'm a bit worried. I am enthusiastic as I've said before about Priha since I can likely justify that to my boss and perhaps even use that in other places. But wholesale architectural changes for what is an wiki project seem to me to be overkill, at least for 3.0.
If put to a vote I'd agree with Andrew's recommendation that we simply rename the packages for now. If there's a need for an API for the rendering engine, we make a simple API for that within the package hierarchy. I don't see the need for a separate package for that API. If an API really simplifies things for me, well, then great; I just don't yet see that.
In a nutshell, this is again simply a call for simplicity where possible.
PS. While this may seem tangential to any arguments here, my time on this is until sometime in the coming year very limited, as like many here I've got a busy project schedule. I've basically got to apply to my boss if I'm going to spend a substantial amount of time doing the migration, which means I need to convince him of the need. The Assertion Framework was "unfunded" by a rather useless director who just resigned, so following his happy disappearance I've got to re-apply in the new year to get the project re-funded, and the amount of time required will have a lot to do with the decision, given the organisation has a lot of pressing needs that I'm qualified to satisfy. I don't want to fork the code, or be forced into using a fork, but I can say that looking at our organisation for the next three years we're going to be under a very restrained budget. We're also moving out of the current building during a renovation with all that entails for a . I simply won't have the time to do large changes. I know that none of this is anyone else's concern but I doubt I'm the only one in a similar situation. Maybe I am and I'm therefore ignorable. I don't know.