On Mon, Feb 11, 2013 at 5:15 PM, Sergiu Dumitriu <ser...@xwiki.org> wrote:
> On 02/08/2013 01:36 PM, Denis Gervalle wrote: > > On Fri, Feb 8, 2013 at 7:15 PM, Vincent Massol <vinc...@massol.net> > wrote: > > > >> > >> On Feb 8, 2013, at 7:09 PM, Denis Gervalle <d...@softec.lu> wrote: > >> > >>> On Fri, Feb 8, 2013 at 3:58 PM, Vincent Massol <vinc...@massol.net> > >> wrote: > >>> > >>>> > >>>> On Feb 8, 2013, at 3:42 PM, Denis Gervalle <d...@softec.lu> wrote: > >>>> > >>>>> By the way, if we agree on @unstable, I also think having another > >>>>> annotation for marking stable API that are not considered to be > stable > >>>> SPI. > >>>>> Why not something like @onlyAPI or @unstableSPI on an interface ? > >>>> > >>>> I think first we need to define what is an SPI and what is an API > first. > >>>> ATM I don't think I understand clearly the difference in the context > of > >>>> XWiki. Is it clear for you? > >>>> > >>> > >>> I do not really understand your question. The general definition is > >> rather > >>> clear: "Service Provider Interface (SPI) is an API intended to be > >>> implemented or extended by a third party". > >> > >> All our component interfaces are meant to be implemented by 3rd parties > to > >> override default behaviors. Are they SPI? > >> > > > > If you consider them stable enough, these could be. The distinction is > > clearly based of what we think of it. Let me take an example: > > interface DataMigrationManager (do not mixup with DataMigration which is > an > > SPI for sure). Currently, I consider this one as an API, but I do not > > imagine any serious usage of it as an SPI for a third party. Marking it > API > > only, would clearly state this point of view. It means that adding a new > > method to this interface is not considered a breakage. Anyone which would > > implement it, knows it could have his code broken later. > > > > How about when Hibernate isn't used? The current implementation is > marked with the "hibernate" hint, so it suggests that it is valid only > in a Hibernate environment. It is a SPI, but one that can't easily be > implemented, since it requires a new storage engine, a new query > manager, plus rewriting all the $xwiki.search* instances, and so on. > Surely, but the key here, is that an SPI is an interface that is intended to be implemented *by a third party*. In that sens, IMO it is currently not. This is want I would like to make clear for third parties. If it was, it would means that my recent breakage in that interface would have cause a far more important complexity increase. This is why IMO, we should not intend to have every API supported as SPI. > > >>> What I would like to be > >>> annotated is API that we do not consider stable SPI at the moment. It > is > >>> less restrictive than @unstable, but more than not saying anything. > >>> Is that answering your question ? > >> > >> That seems complex. Why not use @unstable on "SPI" classes/methods? > >> > > > > Because the status is about the interface as a whole. It is particularly > > about adding new methods (or signatures of existing methods), while > > existing methods are stable. > > I do not want to add something new, but to state clearly what we think of > > our interfaces. This is already the case, while we do not really state > it. > > Considering anything an SPI is not an option IMO, since it will create > more > > complexity over time, for a very low benefit, since the chances of a > third > > party to implement an interface like the DataMigrationManager is near > zero. > > And if any, this third party will surely agree to apply some minor > changes > > to its implementation when needed. > > > > All that said, I wonder if it wouldn't be better to annotate SPI > interface > > in place of non-SPI one, with a @SPI annotation. Which will favor API > only > > and limit complexity. A user really interested in implementing a not > > annotated interface could easily open an issue explaining his use case, > so > > we may open the interface as an SPI. > > > > > > > -- > Sergiu Dumitriu > http://purl.org/net/sergiu > _______________________________________________ > devs mailing list > devs@xwiki.org > http://lists.xwiki.org/mailman/listinfo/devs > -- Denis Gervalle SOFTEC sa - CEO eGuilde sarl - CTO _______________________________________________ devs mailing list devs@xwiki.org http://lists.xwiki.org/mailman/listinfo/devs
