You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@jspwiki.apache.org by Juan Pablo Santos Rodríguez <ju...@gmail.com> on 2020/03/05 14:03:36 UTC
Re: JSPWiki public api proposal + 2.11.0.M7 release
Hi,
I'm finishing another group of commits introducing part of the new public
api. As the initial proposal is taking shape, I've thought an update would
be nice:
* o.a.w.api.core: core API interfaces
** Engine, Context and Session, extracted from WikiEngine, WikiContext and
Session
** Page and Attachment, extracted from WikiPage and Attachment. May be add
DynamicAttachments as well? They don't seem to be widely used, so maybe add
them later on, if needed...
** 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,
WikiPageProvider and WikiAttachmentProvider from both org.apache.wiki and
org.apache.wiki.providers packages
* o.a.w.api.search: QueryItem and SearchResult, promoted from the
o.a.w.search package (as they're needed by the
WikiPageProvider/WikiAttachmentProvider interfaces)
I'm thinking of also including / promoting the
o.a.w.providers.AbstractFileProvider to the o.a.w.api.providers package. I
have to take a look at existing 3rd party
WikiPageProviders and see if it would be useful to include this class on
the public api. If it ends up being a useful class to have on the public
api, that would also mean that
another couple of classes from the o.a.w.search package should be promoted
to the o.a.w.api.search package, namely, SearchComparator and SearchMatcher.
the o.a.w.event package will also be extracted to its own module, and it
will be a dependency of the public API, as some of the public API classes
are expected to react
to events.
Also, the o.a.w.api.engine package is going away, because of two reasons:
- the do not add anything towards 3rd party extensions
(plugins/filters/page providers)
- with all the managers on that package, we would end up with a lot of
classes from everywhere on the public api package, which would do nothing
in there. Having (say)
half the code on that package would totally dillute the purpose of a public
api. It'd simply be half the code on a "public api" package
Finally, WikiEngine, WikiSession and WikiContext have some static methods
to locate / build new instances of those classes. I'm also thinking of
introducing an SPI to
abstract away these methods and be able to get these instances through the
public api. For example, instead of
Engine engine = WikiEngine.getInstance( servletConfig );
we would have:
Engine engine = API.engine().getInstance( servletConfig ); // or whatever
chain of calls from only the o.a.w.api.core package
the engine() method would call the SPI, and return the appropiate
implementation from the classpath, which would call its getInstance(..)
method to return the Engine.
This would have the additional, very nice, benefit of making the core api
interface's implementation pluggable: it would be possible, f.ex., to have
customized
WikiEngine/Wikicontext/WikiSession/etc. implementations without having a
parallel, customized branch. These SPI implementations could be selected
from a
property on jspwiki[-custom].property. Right now this is only an idea and I
still have to see how viable this is, but seems promising.
best regards,
juan pablo
On Mon, Feb 24, 2020 at 11:33 PM Murray Altheim <mu...@altheim.com>
wrote:
> [...]
> > Thoughts? Am I missing something, should the API include more things, or
> > is it too wide,..?
>
> Hi Juan Pablo,
>
> As an author of a lot of plugins I'm guessing I'll have some work to do to
> update my code. Sorry, but I won't be able to look into this and provide
> any
> feedback until this coming weekend though as this week is pretty chocka.
>
> 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
>
>
>
>
Re: JSPWiki public api proposal + 2.11.0.M7 release
Posted by Juan Pablo Santos Rodríguez <ju...@gmail.com>.
Hi Murray,
<snip/>
> > 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. :-)
>
that would've been "next section"
>
> ...............................................................................
> > (2) Filters
> >
> > Not surpringsily, filter execution is handled by the different methods on
>
<snip/>
> > 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.
>
In fact, it'll be in its own maven module, and completely independent from
JSPWiki
code, i.e., you'll be able to import the dependency and use the event
subsystem
on any other project without bringing in any more JSPWiki related code. Its
only
dependencies are commons-lang3 and log4j, IIRC. The public api maven
module will bring the event subsystem as a dependency.
<snip/>
> > 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.
>
haven't thought of that, but moving this code to its own maven module
sounds
like a great idea. I wouldn't mind if the code inside that module ends up
being
messy, because the rest of the code would not.
Also, problems like having two parallel classes on different packages (like
SearchResult or QueryItem mentioned earlier) would also be solved, as
adapter-related code would not interfere with the rest of the codebase, and
the use of duplicated classes would be reduced to calls to the 2.11 pre API
and transforming between those classes and their doppelgangers.
I wouldn't mind then having this module around as long as it useful, as
opposed to
remove it from the main module a minor release after the public api is
released.
<snip/>
> 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.
>
<snip/>
I agree, but it is also highly unusual to have free effort/cost upgrades,
for any
software. If an end user / administrator gets a free effort/cost upgrade
for a
given software, then that cost of upgrading is translated to that said
software.
Also, for a company or an administrator, wanting to update some software,
but not its
related, custom code seems weird to me (not that I don't have seen it). In
the case of
JSPWiki customizations, I understand its different, because that cost of
upgrade is
translated to the plugin/filter/page provider mantainers, and suddenly
having to keep
track of what version of a plugin is compatible with which version(s) of
JSPWiki is a PITA.
Closing up, Jürgen, Murray, thanks for chiming in on this thread, I think
that JSPWiki
will become better because of it.
best regards,
juan pablo
Re: JSPWiki public api proposal + 2.11.0.M7 release
Posted by Murray Altheim <mu...@altheim.com>.
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
Re: JSPWiki public api proposal + 2.11.0.M7 release
Posted by Juan Pablo Santos Rodríguez <ju...@gmail.com>.
Hi,
(another lengthy e-mail, if we're lucky, the last one..)
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"
(1) Plugins
plugins execution is located on DefaultPluginManager and, roughly, looks
like this:
try {
return plugin.execute( context, params ); // plugin is a WikiPlugin,
context is a WikiContext
} catch( final PluginException e ) {
[...]
throw ( PluginException )e.fillInStackTrace();
} catch( final Throwable t ) {
[...]
throw new PluginException( rb.getString( "plugin.error.failed" ), t );
}
If the suggested change for the public plugin api signature (context
becoming Context instead of
WikiContext), a plugin coded against "old" (2.11.0.M6 and below) will raise
an AbstractMethodError
here. However, we can bypass that and achieve plugin execution by changing
the above code to:
try {
try {
return plugin.execute( context, params );
} catch( final AbstractMethodError ame ) {
log.warn( classname + "uses WikiContext instead of Context in its
execute method");
log.warn( "Please contact the plugin's author so there can be a new
release of the plugin " +
"implementing the method signature" );
return ( String )plugin.getClass() // this returns the concrete
type implementing the WikiPlugin interface
.getMethod( "execute", Class.forName(
"org.apache.wiki.WikiContext" ), Map.class )
.invoke( plugin, context, params );
}
} catch( final PluginException e ) {
[...]
throw ( PluginException )e.fillInStackTrace();
} catch( final Throwable t ) {
[...]
throw new PluginException( rb.getString( "plugin.error.failed" ), t );
}
WikiContext#getEngine() method could also be changed so its signature,
instead of returning an
Engine, returns a WikiEngine. That should allow reaching methods from
WikiEngine not present in
Engine, like, f.ex, all the getXYZManager() methods. 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).
Another way to solve this, which would avoid the use of reflection is
turning WikiPlugin into an
adapter. Let's say a new interface org.apache.wiki.api.plugin.Plugin is
created next to WikiPlugin,
which contains the proposed public api change:
public interface Plugin {
String CORE_PLUGINS_RESOURCEBUNDLE = "plugin.PluginResources";
String execute( Context context, Map< String, String > params ) throws
PluginException;
}
then WikiPlugin could become an adapter:
public interface WikiPlugin extends Plugin {
/** {@inheritDoc} */
@Override
default String execute( final Context context, final Map< String,
String > params ) throws PluginException {
Logger.getLogger( WikiPlugin.class ).warn(
this.getClass().getName() + " implements deprecated
org.apache.wiki.api.plugin.WikiPlugin" );
Logger.getLogger( WikiPlugin.class ).warn( "Please contact the
plugin's author so there can be a new release of the plugin " +
"implementing the new
org.apache.wiki.api.plugin.Plugin interface" );
return execute( ( WikiContext )context, params );
}
String execute( WikiContext context, Map< String, String > params )
throws PluginException;
}
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.
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)
Why introduce then the first option? Because that would be the way to go
with
(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.
(3) Page Providers
This one is trickier as WikiPageProvider and WikiAttachmentProvider have
methods like:
Collection< SearchResult > findPages( QueryItem[] query );
with SearchResult and QueryItem being in the search package, with both of
them to land on the
public api, thus changing their package. Happens the same with at least
Acls, Page/WikiPage
Attachment/WikiAttachment.
What I've thought in this case to make them usable with the new API is a
couple of
WikiPage210AdapterProvider / WikiAttachment210AdapterProvider which would
wrap the 3rd party
implementation (that should be located through a property on the
jspwiki[-custom].properties file).
SearchResult / QueryItem classes would not be moved to the API package, but
copied. The API ones
should be used throughout the code, but the original ones (SearchResult /
QueryItem from search
package) would be kept so that the adapter providers can transform back and
forth from the adapter
provider to 3rd party provider. Also, the calls to the 3rd party provider
would be made using the
same reflection technique as before.
(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.
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.
(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.
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?
best regards,
juan pablo
On Sat, Mar 7, 2020 at 11:25 PM Juan Pablo Santos Rodríguez <
juanpablo.santos@gmail.com> wrote:
> Hi Murray,
>
> I'll look into make the current plugins mantain their signature if
> possible. As I wrote else-thread, 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, whether the plugin signature changes or not. What
> I wouldn't want to do is to include back
> code that would make [#1] back into [#2]..
>
>
> best regards,
> juan pablo
>
> [#1]:
> https://jspwiki-wiki.apache.org/attach/JSPWiki3APIDesignProposal/highwheel-master.png
> [#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..)
>
> On Sat, Mar 7, 2020 at 4:21 AM Murray Altheim <mu...@altheim.com>
> wrote:
>
>>
>> > Hi Murray,
>> >
>> > for plugins, most probably there'll be a signature change on WikiPlugin,
>> > from:
>> > String execute( WikiContext context, Map< String, String > params )
>> throws
>> > PluginException;
>> >
>> > to:
>> > String execute( Context context, Map< String, String > params ) throws
>> > PluginException;
>>
>> Hi Juan Pablo,
>>
>> I realise you can't promise anything, but what I'm asking is that there
>> be an adapter-pattern package that maintains **exactly** the same
>> signature as the existing plugins, if at all possible. If we require
>> people
>> to re-code and ecompile plugins then in many cases they simply won't
>> upgrade JSPWiki, as in many cases they won't have time, don't have
>> the developer time or experience or personnel available, etc. as I
>> mentioned previously.
>>
>> If the changes proposed as part of this public API are merely changes
>> of name and package location (effectively facades over the existing
>> code), then an adapter package should be possible. If not, I can't say
>> I'd advocate for making such a change as I believe it would segregate
>> existing users into two camps: those able to re-code and re-install an
>> update, and those who can't due to existing plugins. That seems an
>> overly high price for the existence of a new public API that doesn't
>> add functionality, i.e., if we don't provide a compatible bridging adapter
>> package.
>>
>> 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
>>
>>
>>
>>
Re: JSPWiki public api proposal + 2.11.0.M7 release
Posted by Juan Pablo Santos Rodríguez <ju...@gmail.com>.
Hi Murray,
I'll look into make the current plugins mantain their signature if
possible. As I wrote else-thread, 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, whether the plugin signature changes or not. What I
wouldn't want to do is to include back
code that would make [#1] back into [#2]..
best regards,
juan pablo
[#1]:
https://jspwiki-wiki.apache.org/attach/JSPWiki3APIDesignProposal/highwheel-master.png
[#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..)
On Sat, Mar 7, 2020 at 4:21 AM Murray Altheim <mu...@altheim.com> wrote:
>
> > Hi Murray,
> >
> > for plugins, most probably there'll be a signature change on WikiPlugin,
> > from:
> > String execute( WikiContext context, Map< String, String > params )
> throws
> > PluginException;
> >
> > to:
> > String execute( Context context, Map< String, String > params ) throws
> > PluginException;
>
> Hi Juan Pablo,
>
> I realise you can't promise anything, but what I'm asking is that there
> be an adapter-pattern package that maintains **exactly** the same
> signature as the existing plugins, if at all possible. If we require people
> to re-code and ecompile plugins then in many cases they simply won't
> upgrade JSPWiki, as in many cases they won't have time, don't have
> the developer time or experience or personnel available, etc. as I
> mentioned previously.
>
> If the changes proposed as part of this public API are merely changes
> of name and package location (effectively facades over the existing
> code), then an adapter package should be possible. If not, I can't say
> I'd advocate for making such a change as I believe it would segregate
> existing users into two camps: those able to re-code and re-install an
> update, and those who can't due to existing plugins. That seems an
> overly high price for the existence of a new public API that doesn't
> add functionality, i.e., if we don't provide a compatible bridging adapter
> package.
>
> 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
>
>
>
>
Re: JSPWiki public api proposal + 2.11.0.M7 release
Posted by Murray Altheim <mu...@altheim.com>.
> Hi Murray,
>
> for plugins, most probably there'll be a signature change on WikiPlugin,
> from:
> String execute( WikiContext context, Map< String, String > params ) throws
> PluginException;
>
> to:
> String execute( Context context, Map< String, String > params ) throws
> PluginException;
Hi Juan Pablo,
I realise you can't promise anything, but what I'm asking is that there
be an adapter-pattern package that maintains **exactly** the same
signature as the existing plugins, if at all possible. If we require people
to re-code and ecompile plugins then in many cases they simply won't
upgrade JSPWiki, as in many cases they won't have time, don't have
the developer time or experience or personnel available, etc. as I
mentioned previously.
If the changes proposed as part of this public API are merely changes
of name and package location (effectively facades over the existing
code), then an adapter package should be possible. If not, I can't say
I'd advocate for making such a change as I believe it would segregate
existing users into two camps: those able to re-code and re-install an
update, and those who can't due to existing plugins. That seems an
overly high price for the existence of a new public API that doesn't
add functionality, i.e., if we don't provide a compatible bridging adapter
package.
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
Re: JSPWiki public api proposal + 2.11.0.M7 release
Posted by Juan Pablo Santos Rodríguez <ju...@gmail.com>.
Hi Murray,
for plugins, most probably there'll be a signature change on WikiPlugin,
from:
String execute( WikiContext context, Map< String, String > params ) throws
PluginException;
to:
String execute( Context context, Map< String, String > params ) throws
PluginException;
With Context being a mostly drop-in interface of WikiContext. Likewise,
PageFilter will probably face some
similar changes. I'll look how to ease the transition / make current
plugins / filters compatible but can't promise
anything.
WikiPageProvider will be moved to a new package (a reimport will be
needed), but other than that will also be a
similar case. I'd rather not make this backward compatible as this would
mean having the same interface in two places..
In any case, I suspect the effort will be adapting to changes introduced by
JSPWIKI-120: quite some methods from
WikiEngine were moved to places where they made more sense. The more a
current plugin interacts with JSPWiki, there
are more chances that more things will have to be done to keep the plugin /
filter / page provider up to date.
Finally, just to be clear, the amount of changes that will be needed will
be low: most of the changes involve reimporting classes or
locating methods that were on a class and have been moved to another class,
or using interfaces instead of classes that
most of the time are drop-in replacements. I'll strive to ease or make
current 3rd party extensions backward compatible
as much as possible, but given we're walking towards a major release, now
is the time to do this kind of changes. Don't know
if anything / what else can be done :-?
best regards,
juan pablo
On Thu, Mar 5, 2020 at 8:45 PM Murray Altheim <mu...@altheim.com> wrote:
> Hi Juan Pablo,
>
> One of the things I have considered proposing I'll go ahead and
> propose. I'm as seems typical lately rather overcommitted so I've
> not been able to review what's going on with the new APIs but I
> had the thought that it might be a good idea to actually support,
> at least for some period of time, **two** plugin APIs, the old and
> the new. This would enable existing wikis to continue to use older
> plugins that may have not or may never get updated, whilst still
> moving forward with newer versions of JSPWiki.
>
> The only difference between the old and new plugin APIs may
> simply be its own package signature and the package signatures
> of the respective dependencies (e.g., replacing WikiEngine with
> its API, etc.).
>
> As the author of a lot of plugins, I'd still like to be able to upgrade to
> the newer versions of JSPWiki for production sites, and upgrade my
> plugins as time permits. There are likely a lot of private plugins
> developed for personal or professional sites (that we never hear about)
> whose developers are either too busy or otherwise unavailable for
> updating them, and it'd be a shame to force those sites to either
> abandon what might be essential plugins or never upgrade.
>
> 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
>
>
>
>
Re: JSPWiki public api proposal + 2.11.0.M7 release
Posted by Murray Altheim <mu...@altheim.com>.
Hi Juan Pablo,
One of the things I have considered proposing I'll go ahead and
propose. I'm as seems typical lately rather overcommitted so I've
not been able to review what's going on with the new APIs but I
had the thought that it might be a good idea to actually support,
at least for some period of time, **two** plugin APIs, the old and
the new. This would enable existing wikis to continue to use older
plugins that may have not or may never get updated, whilst still
moving forward with newer versions of JSPWiki.
The only difference between the old and new plugin APIs may
simply be its own package signature and the package signatures
of the respective dependencies (e.g., replacing WikiEngine with
its API, etc.).
As the author of a lot of plugins, I'd still like to be able to upgrade to
the newer versions of JSPWiki for production sites, and upgrade my
plugins as time permits. There are likely a lot of private plugins
developed for personal or professional sites (that we never hear about)
whose developers are either too busy or otherwise unavailable for
updating them, and it'd be a shame to force those sites to either
abandon what might be essential plugins or never upgrade.
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