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