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 > >> > >> > >> > > > >> > > >> > > >
