(changing subject as there may be more e-mails following to reflect current conversation, which spun off this quarters board report)
Hi Dirk, finally went with first option, context.getEngine().getManager( RenderApi.class ).textToHtml(..) The Api suffix instead of the Manager one was just to differentiate public vs non-public api interfaces (most of these are suffixed with Manager). It was the first one I thought of, so most probably there are better alternatives. If you feel another name would be most appropriate, please rename as you see fit :-) Haven't used that class throughout the code because I felt further discussion on this might be needed Initially went with engine().render().. but noticed that it would mean introducing a package cycle between o.a.w.api.core and o.a.w.api.engine packages and, having being cutting them off for the last two months, didn't seem right to introduce a new one. I liked the engine().render().textToHtml(..) semantic because it was very expressive so I thought of a couple of ways to have it: - move the Engine to the o.a.w.api.engine package. That would mean the core package would consist of Wiki related classes (Page, Attachment, Context), and the engine would have "application/static" related stuff. Is not necessarily bad, but seems a lit overkill.. - have on the engine package something like APIs.from( engine ).render() .textToHtml(..) but I don't feel it provides something useful other than being a wrapper in top of existing code / classes As said, I've pushed changes so that first option is available and will begin to deploy an snapshot in a minute, but if you feel it could be improved, please go for it, I'm not sure if I'll be able to get in front of IntelliJ this Eastern, so the sooner we get this out the better :-) best regards, juan pablo On Wed, Apr 8, 2020 at 10:21 PM Dirk Frederickx <dirk.frederi...@gmail.com> wrote: > Juan, > > Sounds logical to keep the RenderManagerApi (? why the "Api" name?) stuff > separated from the Engine interface. > > I'd prefer the > > "context.getEngine().render().textToHtml(...) " > > syntax or perhaps more consistent > > "context.getEngine().getRenderManagerApi().textToHtml(...)" > > > dirk > > On Wed, Apr 8, 2020 at 9:56 PM Juan Pablo Santos Rodríguez < > juanpablo.san...@gmail.com> wrote: > > > Hi, > > > > one last line; just to clarify, I'm not opposed to have the textToHtml > > method on the public api, my concerns were more > > inline with not seeing the Engine as being the place for it.. As for how > to > > call it, > > context.getEngine().getManager( RenderingApi.class ).textToHtml(..) > > > > would be an option, but > > context.getEngine().render().textToHtml(..) > > > > (which under the hood would behave like the first case) would be ok too > and > > perhaps is a bit more expressive.. WDYT? > > > > > > br, > > juan pablo > > > > On Wed, Apr 8, 2020 at 9:26 PM Juan Pablo Santos Rodríguez < > > juanpablo.san...@gmail.com> wrote: > > > > > Hi Dirk, > > > > > > would something like context.getEngine().getManager( RenderingApi.class > > > ).textToHtml( Context, String ) work for you? > > > > > > RenderingApi would sit on the o.a.w.api.engine package, and thus being > > > part of the public API. It would, initially, consist > > > of only the .textToHtml(..) method. We can add more methods (or new > *Api > > > interfaces) later, as needed. > > > > > > RenderingManager would then extend RenderingApi, simply inheriting that > > > method. The engine.getManager(..) behaviour > > > would have to change a little bit to accomodate this, but that would > be a > > > minimal change. That way the Engine and the > > > rendering responsibilities would remain separated on different classes. > > > > > > Does that approach sound reasonable? > > > > > > > > > best regards, > > > juan pablo > > > > > > > > > On Wed, Apr 8, 2020 at 8:18 PM Dirk Frederickx < > > dirk.frederi...@gmail.com> > > > wrote: > > > > > >> Sorry, part of the mail was incomplete.Corrected & resend: > > >> > > >> > > >> > Juan, > > >> > > > >> > Thx for the (long) reply. > > >> > It is indeed key to carefully select what will/will-not be added to > > the > > >> > public api. > > >> > > > >> > Having textToHtml() on the public api make a lot of sense IMO. It > > will > > >> > facilitate plugin authors (existing, new) in quickly building new > > >> plugins > > >> > just be using the public api's (without needing much in-depth > > >> > understanding of the internals of JSPWiki) > > >> > > > >> > textToHtml() is a pretty stable and "static" function as it converts > > one > > >> > string into another; without dependency on other interfaces in the > > >> public > > >> > api. > > >> > > > >> > As "the public "Engine" interface focuses more on the "static" side > of > > >> the > > >> > application" , it could be a good place also to host some other > > >> supporting > > >> > functions. > > >> > But it would probably give a broader role to "Engine" than its > initial > > >> > purpose. > > >> > (maybe we should try to list other "static" functions we'd like to > > bring > > >> > into the public api, to see whether this makes sense) > > >> > > > >> > I'm not sure whether promoting the RenderingManager to be part of > the > > >> > public api is a good idea. > > >> > > > >> It seems to me that this is much more an internal implementation of > > >> > JSPWiki, and not a good candidate for the public api. > > >> > > > >> > (BTW - Note that when pulling in the RenderingManager, it is also > > >> needed > > >> > to pull in other dependencies (WikiEventListener). Adding additional > > >> > complexities fo Plugin writers.) > > >> > > > >> > > > >> > my .02 cent, > > >> > > > >> > dirk > > >> > > > >> > > > >> > On Tue, Apr 7, 2020 at 9:47 PM Juan Pablo Santos Rodríguez < > > >> > juanpablo.san...@gmail.com> wrote: > > >> > > > >> >> Hi Dirk, > > >> >> > > >> >> I've to say I've got mixed feelings about adding the method to the > > >> Engine > > >> >> (but not to add it somewhere else on the public API). > > >> >> On one hand, if it helps with backwards compatibility I wouldn't > mind > > >> >> putting that shortcut on the Engine, or maybe only on > > >> >> the WikiEngine. However once in the API, it would mean that, to > > remove > > >> it, > > >> >> we should release a major version, so instead of > > >> >> moving it away we'd perpetuate it in the public API in a place not > so > > >> well > > >> >> suited for it (in this case, for this method, let me > > >> >> ellaborate in a bit).. > > >> >> > > >> >> On the other hand, having to explicit > > >> .getManager(RenderingManager.class) > > >> >> on wherever (plugin, filter, etc.) explicits > > >> >> a dependency between the "wherever" and the rendering manager > which I > > >> >> think > > >> >> is ok, as it clearly depicts expectations > > >> >> on what is needed by the "wherever", be it on the public API or > not. > > >> >> > > >> >> What would be the reason of having that method on the public API > > >> instead > > >> >> of > > >> >> having to go through the getManager(..) method? > > >> >> The only thing coming to mind is that being on the public API would > > >> mean > > >> >> plugins, filters, etc, using it would have the certainty > > >> >> of still keep working through every minor release. If that's the > > >> >> reasoning, > > >> >> I'd better promote the RenderingManager interface (or > > >> >> maybe only parts of it) to the public API. The Engine as is right > now > > >> is > > >> >> more focused on the "static" side of the application: providing > > >> >> dependencies, configuration properties, the associated servlet > > context, > > >> >> etc. > > >> >> > > >> >> In this case, textToHtml seems nearer to me to rendering > procedures, > > so > > >> >> having that method on a new interface on the o.a.w.api.engine > > >> >> package, and then have the RenderingManager extend from it would be > > ok > > >> for > > >> >> me. And the same with other operations on other > > >> >> managers /operations that are common enough. The public API by no > > >> means is > > >> >> closed, we can add as many classes / interfaces as > > >> >> we deem necessary, its only that we must have extra care, as once a > > new > > >> >> class / method / etc. in there is released, if it ends up being > > >> >> ina bad place or a bad decission, it is going to be very difficult > to > > >> get > > >> >> rid of it (i.e. a major release). > > >> >> > > >> >> Said that and re-reading the public API document + the versioning > > >> >> proposal, > > >> >> I'd like to emphasize that having to code > > >> >> against non-public APIs doesn't mean an extension (or whatever) > will > > >> >> probably stop working on next minor. The policy for breaking > > >> >> changes should be the same as we've doing: only if there isn't a > > >> sensible > > >> >> workaround; f.ex, prefer overloading a method instead of changing > > >> >> its signature. And removing a class / method on the scope of a > minor > > >> >> release should be done like some releases after announcing, > > >> >> perhaps announcing and waiting a couple of years or something like > > >> that? > > >> >> We've always tried to be as nice as possible for custom > > >> >> extensions, having the public API shouldn't mean we are going to > stop > > >> >> being > > >> >> nice.. > > >> >> > > >> >> This isn't expressed on the public API or versioning proposal > pages, > > >> but > > >> >> should be, somehow. @everybody, how could this be phrased? > > >> >> > > >> >> (apologies on the large e-mail, been a tough day at work with too > > much > > >> >> overthinking; hope I haven't digressed too much / have been > > >> >> able to express myself clear..) > > >> >> > > >> >> > > >> >> best regards, > > >> >> juan pablo > > >> >> > > >> >> > > >> >> On Mon, Apr 6, 2020 at 10:54 PM Dirk Frederickx < > > >> >> dirk.frederi...@gmail.com> > > >> >> wrote: > > >> >> > > >> >> > Juan, > > >> >> > > > >> >> > When converting one of the plugins to the latest api; I noticed > > >> that . > > >> >> > textToHTML is not available on the public api. > > >> >> > I needed to do something like: > > >> >> > > > >> >> > > > >> > m_context.getEngine().getManager(RenderingManager.class).textToHTML(... > > >> >> > > > >> >> > iso > > >> >> > > > >> >> > m_context.getEngine().textToHTML(... > > >> >> > > > >> >> > As the textToHtml is IMO a common function used by plugin > > writers; I > > >> >> would > > >> >> > be useful to have that available in the public api. > > >> >> > > > >> >> > WDYT? > > >> >> > > > >> >> > dirk > > >> >> > > > >> >> > On Mon, Apr 6, 2020 at 10:47 PM Dirk Frederickx < > > >> >> dirk.frederi...@gmail.com > > >> >> > > > > >> >> > wrote: > > >> >> > > > >> >> > > Juan, > > >> >> > > > > >> >> > > Excellent work done on the api & documentation ! > > >> >> > > And tx for the report too. > > >> >> > > > > >> >> > > > > >> >> > > dirk > > >> >> > > > > >> >> > > On Sun, Apr 5, 2020 at 9:10 PM Juan Pablo Santos Rodríguez < > > >> >> > > juanpablo.san...@gmail.com> wrote: > > >> >> > > > > >> >> > >> Hi, > > >> >> > >> > > >> >> > >> below is the draft for next board report, I intend to send no > > more > > >> >> later > > >> >> > >> than next Wednesday. As usual, any edits, comments, etc. are > > more > > >> >> than > > >> >> > >> welcome. > > >> >> > >> > > >> >> > >> > > >> >> > >> best regards, > > >> >> > >> juan pablo > > >> >> > >> > > >> >> > >> > > >> >> > >> > > >> >> > >> > > >> >> > > > >> >> > > >> > > > ============================================================================= > > >> >> > >> > > >> >> > >> ## Description: > > >> >> > >> The mission of JSPWiki is the creation and maintenance of > > software > > >> >> > related > > >> >> > >> to > > >> >> > >> Leading open source WikiWiki engine, feature-rich and built > > around > > >> >> > >> standard > > >> >> > >> JEE components (Java, servlets, JSP). > > >> >> > >> > > >> >> > >> ## Issues: > > >> >> > >> There are no issues requiring board attention. > > >> >> > >> > > >> >> > >> ## Membership Data: > > >> >> > >> Apache JSPWiki was founded 2013-07-17 (7 years ago) > > >> >> > >> There are currently 16 committers and 11 PMC members in this > > >> project. > > >> >> > >> The Committer-to-PMC ratio is roughly 4:3. > > >> >> > >> > > >> >> > >> Community changes, past quarter: > > >> >> > >> - No new PMC members. Last addition was Dave Koelmeyer on > > >> 2016-04-06. > > >> >> > >> - No new committers. Last addition was Dave Koelmeyer on > > >> 2016-04-06. > > >> >> > >> > > >> >> > >> ## Project Activity: > > >> >> > >> This quarter's project activity has revolved mostly around the > > >> >> following > > >> >> > >> items > > >> >> > >> * The refactor of WikiEngine, one of the core classes of > JSPWiki > > >> >> > >> (JSPWIKI-120) > > >> >> > >> * The development of a public API for JSPWiki's custom > > extensions > > >> >> > >> (JSPWIKI-303) > > >> >> > >> * Other bugfixes and improvements > > >> >> > >> > > >> >> > >> Because of two first, we missed our release train stop this > > >> quarter, > > >> >> as > > >> >> > in > > >> >> > >> the > > >> >> > >> moment of releasing the master branch, it wasn't backwards > > >> compatible > > >> >> > with > > >> >> > >> current 3rd party extensions. We should be able to release > next > > >> >> quarter, > > >> >> > >> though. > > >> >> > >> > > >> >> > >> The development of the public API also allowed us to add the > > >> >> possibility > > >> >> > >> of > > >> >> > >> including custom managers on the Wiki Engine (JSPWIKI-806) and > > the > > >> >> > ability > > >> >> > >> of > > >> >> > >> swapping core JSPWiki classes (WikiContext, WikiEngine, > > WikiPage, > > >> >> etc.) > > >> >> > >> with > > >> >> > >> custom ones through an SPI, bringing up JSPWiki pluggability > > >> another > > >> >> > step > > >> >> > >> up. > > >> >> > >> > > >> >> > >> ## Community Health: > > >> >> > >> There is enough oversight, with questions getting answered on > > MLs. > > >> >> The > > >> >> > >> public > > >> >> > >> API sparkled a conversation on how / when to break backwards > > >> >> > >> compatibility, > > >> >> > >> which ended up on specifying /clarifying our versioning > proposal > > >> >> [#1]. > > >> >> > >> > > >> >> > >> We received one security report this quarter, but ended up > > >> rejecting > > >> >> it. > > >> >> > >> > > >> >> > >> One pull request merged into master, with 3 people committing > > into > > >> >> > master. > > >> >> > >> > > >> >> > >> In order to foster / attract contributors, we also had an > > >> overhaul of > > >> >> > >> documentation related to different ways of extending / > > customizing > > >> >> > >> JSPWiki: > > >> >> > >> - How to write plugins [#2] > > >> >> > >> - How to write filters [#3] > > >> >> > >> - How to write page providers [#4] > > >> >> > >> - Starting point for developing custom extensions [#5] > > >> >> > >> - JSPWiki's public API [#6] > > >> >> > >> - Adding / improving translations [#7], [#8] > > >> >> > >> > > >> >> > >> [#1] > > >> >> https://jspwiki-wiki.apache.org/Wiki.jsp?page=VersioningProposal > > >> >> > >> [#2 < > > >> >> > > > https://jspwiki-wiki.apache.org/Wiki.jsp?page=VersioningProposal[#2 > > >> >] > > >> >> > >> > https://jspwiki-wiki.apache.org/Wiki.jsp?page=HowToWriteAPlugin > > >> >> > >> [#3 < > > >> >> https://jspwiki-wiki.apache.org/Wiki.jsp?page=HowToWriteAPlugin[#3 > > >> >> > >] > > >> >> > >> > https://jspwiki-wiki.apache.org/Wiki.jsp?page=HowToWriteAFilter > > >> >> > >> [#4 < > > >> >> https://jspwiki-wiki.apache.org/Wiki.jsp?page=HowToWriteAFilter[#4 > > >> >> > >] > > >> >> > >> > > >> >> > > https://jspwiki-wiki.apache.org/Wiki.jsp?page=HowToWriteAPageProvider > > >> >> > >> [#5 > > >> >> > >> < > > >> >> > > > >> >> > > >> > > https://jspwiki-wiki.apache.org/Wiki.jsp?page=HowToWriteAPageProvider[#5 > > > > >> >> > >> ] > > >> >> > >> > > >> >> > >> > > >> >> > > > >> >> > > >> > > > https://jspwiki-wiki.apache.org/Wiki.jsp?page=StartingPointForCustomExtensions > > >> >> > >> [#6 > > >> >> > >> < > > >> >> > > > >> >> > > >> > > > https://jspwiki-wiki.apache.org/Wiki.jsp?page=StartingPointForCustomExtensions[#6 > > >> >> > >] > > >> >> > >> > https://jspwiki-wiki.apache.org/Wiki.jsp?page=JSPWikiPublicAPI > > >> >> > >> [#7 < > > >> >> https://jspwiki-wiki.apache.org/Wiki.jsp?page=JSPWikiPublicAPI[#7 > > >> >> > >] > > >> >> > >> https://jspwiki-wiki.apache.org/Wiki.jsp?page=HowToI18n > > >> >> > >> [#8] https://jspwiki.apache.org/development/i18n.html > > >> >> > >> > > >> >> > > > > >> >> > > > >> >> > > >> > > > >> > > > > > >
