(apologies in advance because this is going to be a large e-mail) Hi Jürgen,
I agree that retaining backward compatibility should be a top priority. However, I strongly disagree with this sentence: "As I understand this public API would bring no advantage in functionality or user experience, only an aesthetic pleasure to the software engineer's eye" In fact, I think that having a public API is pretty much needed. The public API is meant to ease work on JSPWiki, and to reason about it. At least for me, it is/was becaming hard to keep developing new features because the codebase had become enough complex. One way of measuring this complexity is through package / class cycles, and a tool to measure it is highwheel [#1] If you clone the JSPWiki repo and run: git checkout 2.11.0.M6 mvn clean package org.pitest:highwheel-maven:analyse -DclassFilter=org.apache.wiki.* -DparentOnly=true -DskipTests You'll get a report which highlights: * 480 classes * 55 packages Class cycles * org.apache.wiki.workflow.SimpleDecision and 116 others (containing 380 subcycles) * org.apache.wiki.pages.Page and 1 others * org.apache.wiki.pages.haddock.ReadWikiPage and 1 others Packages cycles * org.apache.wiki.auth.login and 35 others (containing 161 subcycles) OTOH, if you run: git checkout master mvn clean package org.pitest:highwheel-maven:analyse -DclassFilter=org.apache.wiki.* -DparentOnly=true -DskipTests you'll get a report which depicts: * 497 classes * 58 packages Class cycles * org.apache.wiki.ui.GroupCommand and 24 others (containing 33 subcycles) * org.apache.wiki.workflow.WorkflowManager and 5 others (containing 9 subcycles) * org.apache.wiki.pages.Page and 1 others * org.apache.wiki.pages.haddock.ReadWikiPage and 1 others Packages cycles * org.apache.wiki.variables and 33 others (containing 150 subcycles) Generated graphs for the main module are available at [#2], [#3]. On the 2.11.0.M6 you can see that WikiContext, WikiEngine and WikiPage are the main entry/exit points for these cycles, so the way to make JSPWiki less complex forcibly passes by tackling those classes Going back to the numbers, on 2.11.0.M6, the jspwiki-main module goes from a big cycle involving 117 classes, which contains 380 subcycles, to two cycles on current master, involving 25 and 6 classes respectively, with 33 and 9 subcycles. I'd say it is *way* easier to reason about the code on current master than it was on 2.11.0.M6. And that's just by introducing a small fraction of the public API. The two package cycles which disappear are from the event, modules and api packages IIRC, which will allow the public API to exist as an independent module. Those two package cycles implied 16 subcycles less, which means that packages have more meaning now than on 2.11.0.M6, meaning is easier to develop on JSPWiki. I expect those numbers will continue to go down as more of the public API is introduced. Another way this complexity has surfaced is with the lost plugins on transitioning to the org.apache.wiki namespace you've mentioned. In fact, there's a JIRA to track to somehow make them compatible with the current code. I thought it would be an easy thing to do, just drop the old jspwiki jar and use an adapter pattern to use the new signature. But then the plugin signature included WikiContext so there had to be a way to transform the "new" (org.apache.wiki) WikiContext to the "old" back and forth. Ok, I thought, let's then keep the signatures of the old WikiContext and make it an adapter to forward calls to the new one. But then, the old WikiContext also had a method to retrieve the WikiEngine, the "old" one, so that one should be adapted as well. And then the WikiEngine had all sort of getXYZManager methods, etc. so at the end, to be 100% certain that "old" plugins could work on a "new" JSPWiki meant that a big number of "old" classes has to be stubbed (most probably, the equivalent ones to the 117 denoted by the big class cycle on 2.11.0.M6), just in case someone thought of a plugin that used some less common manager of JSPWiki or whatever keeps running. So, not so easy, not so sure it would be worth the effort. Backwards compatibility is a top priority. Having a public API (or making the codebase less complex, to put it another way) is also pressing, and is something that will end up done, now or later on. *If* (I don't know yet) there isn't a plugin signature or any other way to accomodate custom plugin / filters with the newer public api maybe instead of work on 2.11.0.M7 we should be working on 3.0.0.M1 to signal this more strongly? Keep in mind the 6 last releases contain code changes that could result in custom plugins / filters not working anymore. That would also happen on this release, independently from the public API. best regards, juan pablo [#1]: https://github.com/hcoles/highwheel [#2]: https://jspwiki-wiki.apache.org/attach/JSPWiki3APIDesignProposal/highwheel-2.11.0.M6-reduced.png (original image resulted in 36MB, have to scale it to keep the size reasonable, to see the full details is better to execute the maven plugin..) [#3]: https://jspwiki-wiki.apache.org/attach/JSPWiki3APIDesignProposal/highwheel-master.png On Sat, Mar 7, 2020 at 10:21 AM Jürgen Weber <juer...@jwi.de> wrote: > Hi, > > part of the appeal of JSPWiki is for me that I can reach deep into the > wiki engine from plugins. > JSPWiki is for hackers, BigCorps use Confluence. > And as hacker I want control, I need to look into the Wiki core and > use what it offers, or work around its limitations. > So I'd rather prefer no API changes, I'd like the Wiki to stay binary > and API compatible. There are enough plugins out there that didn't > make the move to org.apache.wiki. > As I understand this public API would bring no advantage in > functionality or user experience, only an aesthetic pleasure to the > software engineer's eye. > A big advantage of the old Java and EE eco system is that it mostly > kept compatible. > So should JSPWiki. > > Greetings, > Juergen > > > Am Mo., 24. Feb. 2020 um 22:48 Uhr schrieb Juan Pablo Santos Rodríguez > <juanpablo.san...@gmail.com>: > > > > Hi, > > > > I'm almost done with JSPWIKI-120 (aka big refactor on WikiEngine) and, > > after it, I'd like to retake JSPWIKI-303 > > (JSPWiki public api) before next release. > > > > As of now, I've came up with the following classes/interfaces for the > > public API, that should be enough for most > > of the typical JSPWiki extensions out there. We could add further > > classes/packages later on, but I think it's ok for a first approach: > > > > * o.a.w.api.core: core API interfaces > > ** Engine and Context, extracted from WikiEngine and WikiContext > > ** Page and Attachment, extracted from WikiPage and Attachment > > ** Acl and AclEntry, promoted from the o.a.w.auth.acl package (as they > are > > used by Page, Attachment and Context) > > ** Command, promoted from the o.a.w.ui package (as WikiContext is > > implementing Command) > > ** o.a.w.Release promoted to this package? > > * o.a.w.api.exceptions: JSPWiki custom exceptions > > * o.a.w.api.filters: Filters API (modified to require Context instead of > > WikiContext) > > * o.a.w.api.plugin: Plugins API (modified to require Context instead of > > WikiContext) > > * o.a.w.api.providers: Page providers API, it would contain WikiProvider > > and WikiAttachmentProvider from org.apache.wiki.providers > > > > Some of the classes from which the API is extracted also rely on classes > on > > the o.a.w.event package, so there's a slight > > chance that the o.a.w.event package will become a dependency of the > public > > API. Have to take a better look at it. As of > > now, the o.a.w.event package can be extracted to its own independent > > module, so it shouldn't be a big deal. > > > > As of this quarter release, I think right now it makes sense to skip it: > > current changes related to JSPWIKI-120 have a > > good probability of breaking existing 3rd party plugins/filters (most > > likely if they interact with the WikiEngine), and that is > > likely to happen again when introducing the public API. Also, this > quarter > > work has been mainly around JSPWIKI-120, so > > releasing now wouldn't unlock new features or bugfixes, but rather just > > have a release which may break current 3rd party > > integrations. This was bound to happen sometime, but in order to minimize > > the chances of breaking again the JSPWiki > > API I think it's better to skip this station. > > > > Thoughts? Am I missing something, should the API include more things, or > is > > it too wide,..? > > > > > > best regards, > > juan pablo >
