Juan Pablo wrote: > (another lengthy e-mail, if we're lucky, the last one..)
I'll preface my remarks with one that tries to encapsulate my position: that is, I don't *think* I'm asking to do anything more than a reasonable person who has a substantial investment in JSPWiki customisation would ask: as someone in that boat I might be considered a representative sampling of such a person. I've written a lot of plugins, a few filters, and about a half dozen WikiPageProviders. But I also understand the issues and limitations due to upgrades, version numbers, time available, etc. > took a look at how could we achieve backward compatibility for (1)plugins, > (2)filters and (3)page providers, while developing the public API. After > that I'd like two make two brief comments about (4)next steps and (5)having > JSPWiki installations' "islands" Juan Pablo, again thank you for taking so much time and effort trying to find a way through this, it's very much appreciated. ............................................................................... > (1) Plugins > > plugins execution is located on DefaultPluginManager and, roughly, looks > like this: > [...] However, note that there are some methods in > WikiEngine that are not longer there, they've been moved to places were > they made sense. These methods were used mainly for JSPWiki internal > operations, so they're unlikely used in custom plugins. It's not impossible, > though, but this kind of change should be expected on a minor release > (the ones changing the middle number, i.e., 2.10.6 to 2.11.0). I think it's entirely reasonable that if someone's plugin is digging into what might be considered the "internal" methods of the WikiEngine (or really, anywhere else that might have been, in the absence of a real public API, an "internal" method, even if such concepts aren't fixed), they should have known this was a risky endeavour. > Another way to solve this, which would avoid the use of reflection is > turning WikiPlugin into an adapter. > [...] > WikiPlugin, although being in the api.plugin package would NOT be part of > the public api, i.e., it would remain on the jspwiki-main module, whereas > the public api would be in a new jspwiki-api maven module. I'm more > inclined to this, mostly because all interfaces/classes on the public api > are not prefixed with "Wiki" except for WikiPlugin, and then all the public > api would be uniformly named. Yes, agreed. I'm perfectly happy with the public API remaining as clean and "new" as possible, and the existing Wiki* classes being relegated (even as unchanged) into a territory of "beyond here be dragons". I think that we can agree that those whose modus operandi would be "not touching anything" won't be fussed to know their existing package signatures are now deprecated or otherwise discouraged. They probably won't notice because they don't have time to notice: they just upgrade until something busts, then back out of the upgrade to get things to work again. > That would please all people like me who are somewhere in-between software > engineers and people with obsessive-compulsive disorder :-) Jokes aside, the > important thing is that current plugins would still run with the new API. > (And WikiPlugin would eventually be deleted from the source code) This could work indefinitely, as it does no harm. > Why introduce then the first option? Because that would be the way to go > with [...] I'm guessing you had to take a typing break here. :-) ............................................................................... > (2) Filters > > Not surpringsily, filter execution is handled by the different methods on > DefaultFilterManager. By catching different AbstractMethodError on those > methods we can make "old" filters work alongside the new API. Yes, this one should be relatively straightforward. ............................................................................... > (3) Page Providers > > This one is trickier as WikiPageProvider and WikiAttachmentProvider have > methods like: [...] I'll just summarise my response to page providers by saying that having written a few I knew going in that I'd be entirely responsible for upkeep, as due to their nature and their requirement to dig into the internals of the WikiEngine there was/is an inherent risk involved, i.e., that I or someone would have to continue to maintain and upgrade the code. So I consider this quite different from WikiPlugin. Perhaps *after* availability of a public API it'd be cleaner/safer to develop page providers. This would certainly be one benefit. > (4) Next steps > > Hopefully, no more kilometric e-mails. On the short term, I'm planning to > extract the event package to its own jspwiki-event maven module, and > create a jspwiki-api > maven module. This module would contain the full > public API, although right now only part of it would be used (Engine, > Session and maybe a few more classes), so it can be discussed and reasoned > around with a more clear focus. Having been I seem to remember the one who wrote the original event handler it's remarkable how many times I've reused that code for other projects, so having it pushed over into a public API is a good thing. > After that, re-introduce API compatibility with plugins (easy) and filters > (a bit more of work but hopefully doable too without spending too much > time on it). It would be really, *really* nice if someone volunteered for > the page providers: keeping the existing extensions is gone to take some > time that I was planning to spend on other tasks, so any help with that > would mean more time spent on the public api. I can only apologise that I'm not available to do any coding in the foreseeable future. It seems I'm now perpetually overcommitted, which I guess is a good thing. > (5) JSPWiki installations' islands > > We don't want to have them, and we strive to avoid them as much as > possible. Said that, I think they're bound to happen someday. Keeping the > backward compatibility is an ongoing burden. It is not that we shouldn't > have it as a top priority, but that doesn't mean is the absolute driver. Agreed. And it's admittedly a shame that the nature of JSPWiki is that there's likely a lot of people who are using it, and upgrading regularly, but we don't have any metrics on how many people have done customisations, or on the nature and depth of those customisations. We can only surmise, and I can only advocate on the likelihood of the needs of that community, not on anything beyond my own personal experience. > JSPWiki API hasn't changed in ~7 years. A minor release after introducing > the public API (that is on 2.12.0 or 3.1.0, whatever we see fit) I plan / > like to remove the backward compatibility introduced above, as it also > means more complexity on the code base. That would be a breaking change > in the API in about 8-9 years, which I don't find completely unreasonable. > > thoughts? I think this is entirely reasonable, if that change were to occur in a year or two. I would suggest that after things settle we all look at the additional complexity required by the adapter/facade classes that permit the plugins to continue to work and consider that rather than kill that off after some period of time, that rather than that consider moving that code off to its own sub-project so that people could install that jar file to continue to use the older plugins. Iff that's a reasonable proposition. I think we all have the experience that developers operate at a much faster speed than end users. I'm always struck by how many installations are still using old hardware and software. A few years ago I came upon a critical, enterprise system (which I can't name) that was working *entirely* on two Windows 2000 servers (physical boxes!) in the basement of the building. I managed to talk management to have me lead a project to get that onto Linux blade servers and properly requisitioned, and that effort took a couple of years. But *typically* management don't see infrastructure as so high a priority as new features. And support systems like wikis are pretty much at the bottom of that priority list. They just want them to keep ticking over. Cheers, Murray ........................................................................... Murray Altheim <murray18 at altheim dot com> = = === http://www.altheim.com/murray/ === === = = === In the evening The rice leaves in the garden Rustle in the autumn wind That blows through my reed hut. -- Minamoto no Tsunenobu
