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 2012/12/12 01:17:01 UTC
org.apache.wiki.api?
Hello again,
I was going through 3.0 JIRA issues, and I've came across with JSPWIKI-303
[#1], defining an API for JSPWiki under [com.ecyrd|org.apache].wiki.api,
not only as a mean of providing access to JSPWiki internals, but as a mean
of breaking cycles between classes and packages (red squares at [#2]).
Basically this would mean better testability and modularity, and easier
manteinance.
My intention is to do this gradually, trying to mantain binary
compatibility whenever possible, targeting for 2.10.x scope (but hey, if it
happens to be done for 2.9.x, so be it). This most probably means marking
some methods with @Deprecated with the intention of deleting them in 2.10.x.
As of candidates for wiki.api package, I'd look both in [#3] and
WikiEngine#initialize(Properties), lines 523-587, making the appropiate
changes so ClassUtils returns always interfaces. As I've had to take a look
at the plugins recently, I was about to begin with PluginManager +
WikiPlugin.
thoughts?
[#1] https://issues.apache.org/jira/browse/JSPWIKI-303
[#2]
https://analysis.apache.org/plugins/resource/110730?page=org.sonar.plugins.design.ui.page.DesignPage
[#3] http://www.jspwiki.org/wiki/JSPWiki3APIDesignProposal
Re: org.apache.wiki.api?
Posted by Juan Pablo Santos Rodríguez <ju...@gmail.com>.
Hi,
I didn't want to start a branch because my intention was to push the API
into trunk gradually. Also, as the API is being checked in, the build is
still backwards compatible so it's possible to develop plugins, filters,
etc. totally ignoring the API.
In 2.10 we should get rid off the @Deprecated API-related classes/methods,
but until then, the API should be transparent, i.e.: I left some tests and
plugins in $svn/tests against org.apache.wiki.plugins.WikiPlugin instead of
org.apache.wiki.api.WikiPlugin, just to ensure that the @Deprecated
classes/methods are still functional.
Also, the UPGRADING document gives a quick overview of the API and
associated changes.
With all that in mind, I think that's safe enough to push the API in trunk.
WDYT
Regarding why the API, and on what is based, my intention is to modularize
the source, that meaning no more red squares at [#1], so we're able to talk
about several individual modules like jspwiki-api, jspwiki-plugins,
jspwiki-ctags. As a consequence of that, the API emerges by itself, which
made me look at the 3.0 API, JSPWIKI-303 and
http://www.jspwiki.org/wiki/JSPWiki3APIDesignProposal
br,
juan pablo
p.d.: as a side note, I was planning on targetting at filters for the nexts
commits regarding the API..
[#1]:
https://analysis.apache.org/drilldown/measures/110730?metric=package_cycles
On Sun, Dec 16, 2012 at 11:56 AM, Florian Holeczek <fl...@holeczek.de>wrote:
> Oops... Just saw that my answer came too late.
>
>
> Am 16.12.2012 12:53, schrieb Florian Holeczek:
>
> True... I'm thinking of the API to be a very good thing, but I haven't
>> got enough time to follow this at the moment. Having the possibility of
>> looking at the progress on a separate branch would surely lower the hurdles.
>>
>> @Juan Pablo: Did you base your work on Janne's previous work, or is it
>> something completely new?
>>
>> Regards
>> Florian
>>
>>
>> Am 14.12.2012 20:31, schrieb Siegfried Goeschl:
>>
>>> Hi Juan Pablo,
>>>
>>> maybe a SVN feature branch would be a good idea ...
>>>
>>> Cheers,
>>>
>>> Siegfried Goeschl
>>>
>>
Re: org.apache.wiki.api?
Posted by Florian Holeczek <fl...@holeczek.de>.
Oops... Just saw that my answer came too late.
Am 16.12.2012 12:53, schrieb Florian Holeczek:
> True... I'm thinking of the API to be a very good thing, but I haven't got enough time to follow this at the moment. Having the possibility of looking at the progress on a separate branch would surely lower the hurdles.
>
> @Juan Pablo: Did you base your work on Janne's previous work, or is it something completely new?
>
> Regards
> Florian
>
>
> Am 14.12.2012 20:31, schrieb Siegfried Goeschl:
>> Hi Juan Pablo,
>>
>> maybe a SVN feature branch would be a good idea ...
>>
>> Cheers,
>>
>> Siegfried Goeschl
Re: org.apache.wiki.api?
Posted by Florian Holeczek <fl...@holeczek.de>.
True... I'm thinking of the API to be a very good thing, but I haven't got enough time to follow this at the moment. Having the possibility of looking at the progress on a separate branch would surely lower the hurdles.
@Juan Pablo: Did you base your work on Janne's previous work, or is it something completely new?
Regards
Florian
Am 14.12.2012 20:31, schrieb Siegfried Goeschl:
> Hi Juan Pablo,
>
> maybe a SVN feature branch would be a good idea ...
>
> Cheers,
>
> Siegfried Goeschl
Re: org.apache.wiki.api?
Posted by Siegfried Goeschl <sg...@gmx.at>.
Hi Juan Pablo,
maybe a SVN feature branch would be a good idea ...
Cheers,
Siegfried Goeschl
On 14.12.12 00:42, Juan Pablo Santos Rodríguez wrote:
> Hi,
>
> I'm almost done with the plugin API, however, in order to keep the build
> running and still being being backwards compatibility, it's going to be
> quite a somewhat big commit, ~50 files touched, so just to be sure:
>
> Classes affected:
> @Deprecated methods/classes
> -> all classes / methods anotated with @Deprecated because of the API
> changes will be removed
> in 2.10 timeframe
> * the plugin api is still depending on WikiContext and PluginContent,
> but this should change shortly
> (I'd rather release the files now that I've an stabilized build and
> continue later on)
>
> api
> -> new package org.apache.wiki.api, which should compile without depending
> on other packages
>
> exceptions
> -> new package org.apache.wiki.api.exceptions with copies of the original
> Exceptions declared by
> the API methods
> -> to retain backwards compatibility, "old" exceptions will inherit new
> ones, also the former ones
> are marked as @Deprecated
> * e.g.: org.apache.wiki.plugin.PluginException will inherit
> org.apache.wiki.api.exceptions.PluginException which (ultimately)
> inherits WikiException
> * note that, until the API is completed, regarding exceptions there
> will be an somewhat
> awkward jump: org.apache.wiki.api.exceptions.*Exception ->
> org.apache.wiki.WikiException ->
> org.apache.wiki.api.exceptions.WikiException. It allows us to
> achieve compatibility with
> 2.9 derived source (regarding exceptions).
>
> org.apache.wiki.plugin.PluginManager
> -> new interface org.apache.wiki.api.PluginManager
> -> moved to org.apache.wiki.plugin.DefaultPluginManager
> -> @Deprecated public static boolean isPluginLink( String link )
> * equivalent method on org.apache.wiki.parser.JSPWikiMarkupParser
> -> WikiEngine.getPluginManager now has the following signature, in order
> to retain backward
> compatibility: public < T extends PluginManager > T getPluginManager()
> * In 2.10 this should change to public PluginManager
> getPluginManager()
>
> org.apache.wiki.plugin.InitializablePlugin
> -> new interface org.apache.wiki.api.InitializablePlugin
> -> all core wikiplugins and wikiforms implementing the "old" interface now
> implement the new one
> -> org.apache.wiki.plugin.InitializablePlugin marked with @Deprecated +
> extends
> org.apache.wiki.api.InitializablePlugin
>
> org.apache.wiki.plugin.ParserStagePlugin
> -> new interface org.apache.wiki.api.ParserStagePlugin
> -> all core wikiplugins and wikiforms implementing the "old" interface now
> implement the new one
> -> org.apache.wiki.plugin.ParserStagePlugin marked with @Deprecated +
> extends
> org.apache.wiki.api.ParserStagePlugin
>
> org.apache.wiki.plugin.WikiPlugin
> -> new interface org.apache.wiki.api.WikiPlugin
> -> all wikiplugins and wikiforms implement the new interface
> -> org.apache.wiki.plugin.WikiPlugin marked with @Deprecated + extends
> org.apache.wiki.api.WikiPlugin
>
> Any ideas/comment/objections will be welcomed, but I'd like to do the
> commit tomorrow evening.. O:-)
>
>
> br,
> juan pablo
>
>
> On Wed, Dec 12, 2012 at 1:17 AM, Juan Pablo Santos Rodríguez <
> juanpablo.santos@gmail.com> wrote:
>
>> Hello again,
>>
>> I was going through 3.0 JIRA issues, and I've came across with JSPWIKI-303
>> [#1], defining an API for JSPWiki under [com.ecyrd|org.apache].wiki.api,
>> not only as a mean of providing access to JSPWiki internals, but as a mean
>> of breaking cycles between classes and packages (red squares at [#2]).
>> Basically this would mean better testability and modularity, and easier
>> manteinance.
>>
>> My intention is to do this gradually, trying to mantain binary
>> compatibility whenever possible, targeting for 2.10.x scope (but hey, if it
>> happens to be done for 2.9.x, so be it). This most probably means marking
>> some methods with @Deprecated with the intention of deleting them in 2.10.x.
>>
>> As of candidates for wiki.api package, I'd look both in [#3] and
>> WikiEngine#initialize(Properties), lines 523-587, making the appropiate
>> changes so ClassUtils returns always interfaces. As I've had to take a look
>> at the plugins recently, I was about to begin with PluginManager +
>> WikiPlugin.
>>
>> thoughts?
>>
>>
>> [#1] https://issues.apache.org/jira/browse/JSPWIKI-303
>> [#2]
>> https://analysis.apache.org/plugins/resource/110730?page=org.sonar.plugins.design.ui.page.DesignPage
>> [#3] http://www.jspwiki.org/wiki/JSPWiki3APIDesignProposal
>>
>
Re: org.apache.wiki.api?
Posted by Juan Pablo Santos Rodríguez <ju...@gmail.com>.
Hi,
I'm almost done with the plugin API, however, in order to keep the build
running and still being being backwards compatibility, it's going to be
quite a somewhat big commit, ~50 files touched, so just to be sure:
Classes affected:
@Deprecated methods/classes
-> all classes / methods anotated with @Deprecated because of the API
changes will be removed
in 2.10 timeframe
* the plugin api is still depending on WikiContext and PluginContent,
but this should change shortly
(I'd rather release the files now that I've an stabilized build and
continue later on)
api
-> new package org.apache.wiki.api, which should compile without depending
on other packages
exceptions
-> new package org.apache.wiki.api.exceptions with copies of the original
Exceptions declared by
the API methods
-> to retain backwards compatibility, "old" exceptions will inherit new
ones, also the former ones
are marked as @Deprecated
* e.g.: org.apache.wiki.plugin.PluginException will inherit
org.apache.wiki.api.exceptions.PluginException which (ultimately)
inherits WikiException
* note that, until the API is completed, regarding exceptions there
will be an somewhat
awkward jump: org.apache.wiki.api.exceptions.*Exception ->
org.apache.wiki.WikiException ->
org.apache.wiki.api.exceptions.WikiException. It allows us to
achieve compatibility with
2.9 derived source (regarding exceptions).
org.apache.wiki.plugin.PluginManager
-> new interface org.apache.wiki.api.PluginManager
-> moved to org.apache.wiki.plugin.DefaultPluginManager
-> @Deprecated public static boolean isPluginLink( String link )
* equivalent method on org.apache.wiki.parser.JSPWikiMarkupParser
-> WikiEngine.getPluginManager now has the following signature, in order
to retain backward
compatibility: public < T extends PluginManager > T getPluginManager()
* In 2.10 this should change to public PluginManager
getPluginManager()
org.apache.wiki.plugin.InitializablePlugin
-> new interface org.apache.wiki.api.InitializablePlugin
-> all core wikiplugins and wikiforms implementing the "old" interface now
implement the new one
-> org.apache.wiki.plugin.InitializablePlugin marked with @Deprecated +
extends
org.apache.wiki.api.InitializablePlugin
org.apache.wiki.plugin.ParserStagePlugin
-> new interface org.apache.wiki.api.ParserStagePlugin
-> all core wikiplugins and wikiforms implementing the "old" interface now
implement the new one
-> org.apache.wiki.plugin.ParserStagePlugin marked with @Deprecated +
extends
org.apache.wiki.api.ParserStagePlugin
org.apache.wiki.plugin.WikiPlugin
-> new interface org.apache.wiki.api.WikiPlugin
-> all wikiplugins and wikiforms implement the new interface
-> org.apache.wiki.plugin.WikiPlugin marked with @Deprecated + extends
org.apache.wiki.api.WikiPlugin
Any ideas/comment/objections will be welcomed, but I'd like to do the
commit tomorrow evening.. O:-)
br,
juan pablo
On Wed, Dec 12, 2012 at 1:17 AM, Juan Pablo Santos Rodríguez <
juanpablo.santos@gmail.com> wrote:
> Hello again,
>
> I was going through 3.0 JIRA issues, and I've came across with JSPWIKI-303
> [#1], defining an API for JSPWiki under [com.ecyrd|org.apache].wiki.api,
> not only as a mean of providing access to JSPWiki internals, but as a mean
> of breaking cycles between classes and packages (red squares at [#2]).
> Basically this would mean better testability and modularity, and easier
> manteinance.
>
> My intention is to do this gradually, trying to mantain binary
> compatibility whenever possible, targeting for 2.10.x scope (but hey, if it
> happens to be done for 2.9.x, so be it). This most probably means marking
> some methods with @Deprecated with the intention of deleting them in 2.10.x.
>
> As of candidates for wiki.api package, I'd look both in [#3] and
> WikiEngine#initialize(Properties), lines 523-587, making the appropiate
> changes so ClassUtils returns always interfaces. As I've had to take a look
> at the plugins recently, I was about to begin with PluginManager +
> WikiPlugin.
>
> thoughts?
>
>
> [#1] https://issues.apache.org/jira/browse/JSPWIKI-303
> [#2]
> https://analysis.apache.org/plugins/resource/110730?page=org.sonar.plugins.design.ui.page.DesignPage
> [#3] http://www.jspwiki.org/wiki/JSPWiki3APIDesignProposal
>