[hibernate-dev] [OGM and others] API, SPI and FPI

Thu May 22 12:01:47 EDT 2014

You misread me. I have to plan to change the meaning of SPI. I just
pointed the few most prominent definitions I have found while
researching the subject. What did strike me though is that SPI is much
less defined and explained than I anticipated.

What I am questioning is whether an API / SPI split is more or less
useful than a API / FPI (as I call it in the email) split for the users
of our libraries.

Emmanuel

On Thu 2014-05-22  9:32, Steve Ebersole wrote:
> Deja vu as we have had this exact discussion before (and actually, our
> discussions pre-date those TAG discussions....)
> 
> You are basing your specific reading of what SPI means based on a single
> wikipedia page that goes out of its way to point out its incompleteness :)
>  And really even then in my opinion you are reading too much into its
> mention of the JDK ServiceLoader.  What the wikiepdia says specifically is:
> 
> *Service Provider Interface* (SPI) is an
> API<http://en.wikipedia.org/wiki/Application_programming_interface>
> intended
> > to be implemented or extended by a third party. It can be used to enable
> > framework extension and replaceable components
> 
> 
> That's actually not much different (if at all) from how I use the term SPI.
>  To me, SPI is simply "the API that is used between internal components to
> accomplish something".  A specific important distinction here is that APIs
> are meant for application code to bind to, SPIs are not.  As I have pointed
> out probably 100 times already, yes there are 2 facets to this.  To me an
> SPI is made up of:
> 1) The SPI contracts that are meant to be extended by users and/or 3rd
> parties.
> 2) The SPI contracts that are not intended for extension.
> 
> Another correlated break down is:
> 1) SPI contracts that do things
> 2) SPI contracts that are inputs/outputs to (1)
> 
> Take for example, the idea of scanning deployments for annotated classes
> (mainly because this one is fresh in my mind).  The main SPI contract here
> is Scanner and ArchiveDescriptorFactory.  These are each intended as
> extension points, they both "do stuff".  All the rest of the "scanning spi"
> is inouts/outputs to these 2.  Why is this an important distinction?  Well,
> generally speaking where we get into trouble in terms of "changing SPIs"
> later is when we change this first group.  When we have to make
> changes to Scanner
> or make changes to ArchiveDescriptorFactory we cause problems downstream
> for folks that implement/extend this stuff.  That's where patterns like
> parameter objects and delegates are sooooooooo beneficial.  As an
> illustration, say we need to pass some new information into the single
> Scanner method (this was the recent case I worked through).  If that means
> adding a new parameter to that Scanner method, well that just screwed every
> implementor of the Scanner interface because now their implementation is no
> longer valid.  If instead, Scanner had made use of parameter objects (it
> now does btw), the parameter object itself would have been changed causing
> no problem of existing Scanner implementations.  The "parameter object" is
> still part of the SPI.  But it falls into this second category.  Changing
> these guys is essentially irrelevant in terms of causing no issues for
> existing SPI implementations.
> 
> 
> And as far as "a tendency to consider the application developer more sacred
> than the framework/integrator when it comes to breaking backward
> compatibility" I would not phrase it like that.  There are  a few parts to
> this in my mind:
> 
> First,  I think you need to step back and look at the bigger picture.  The
> API defines the features that Hibernate is exposing to the application
> (save this thing, find that thing).  Its kind of broad and generally avoids
> defining a feature in relation to an interaction between 2 things.  SPIs in
> many ways are inherently more complicated to design because they need to
> consider both sides of the problem.  Going back to scanning, that SPI needs
> to consider Hibernate's requirements from scanning as well as any
> requirements the implementation needs especially accounting for any quirks
> in the various potential implementations.
> 
> Second, because of the "overlap" or "integration" aspects between teams and
> projects there needs to be coordination and cooperation when
> building/designing an SPI.  To be honest, this part has been lacking even
> within "our team" across projects because people get focused on their work.
>  What happens instead, again from my perspective, is no
> coordination/cooperation
> occurs in the building/designing of these; and then later people get upset
> when the SPI needs to change because it was not well designed to begin
> with.  Another aspects of this is "more eyes"; the more people involved in
> the design of an API (SPI fits in here equally) looking at it, the better
> designed it will be.
> 
> 
> All that said, I don't plan on changing use of the phrase SPI based on (a
> questionable interpretation of) one wikipedia page.
> 
> 
> On Thu, May 22, 2014 at 4:21 AM, Emmanuel Bernard <emmanuel at hibernate.org>wrote:
> 
> > (This discussion is around OGM but it is a very generic subject applicable
> > to all projects.)
> >
> > I made a mistake in naming the spi packages SPI because the definition of
> > SPI is quite narrow and even more narrower in Java than elsewhere.
> >
> > ## Definitions
> >
> > ### SPI
> >
> > In Java and according to Wikipedia, a SPI (Service provider interface) is
> > related to the notion of ServiceLoader
> > http://en.wikipedia.org/wiki/Service_Provider_Interface
> > We certainly do not (or very rarely) have these kinds of services in our
> > SPI packages.
> >
> > Another point of you comes from this StackOverflow article
> > https://stackoverflow.com/questions/2954372/difference-between-spi-and-api
> >
> > - the API is the description of classes/interfaces/methods/... that you
> > call and use to achieve a goal and
> > - the SPI is the description of classes/interfaces/methods/... that you
> > extend and implement to achieve a goal
> >
> > A third point of you is the NetBeans one
> > http://wiki.netbeans.org/DevFaqApiSpi
> >
> > SPI stands for Service Provider Interface. It is a subset of all things
> > that can be API specific to situations where a library is providing classes
> > which are called by the application (or API library), and which typically
> > change the things the application is able to do.
> >
> > I think everyone agrees that an SPI is kind of API.
> >
> > ### IPI or FPI (Integrator / Framework Public Interface)
> >
> > I will use FPI as it tastes better than IPI but I have no preferences over
> > integrators vs frameworks.
> >
> > Now in my mind and for some obscure reasons, SPI really meant FPI. To my
> > credit, I have done that fairly constantly on Hibernate Search and Bean
> > Validation. Hibernate OGM was never properly packaged initially so that’s
> > another story.
> >
> > A FPI is used by a framework integrating or extending the project exposing
> > these FPIs.
> >
> > ## What does really matter?
> >
> > It is useful to differentiate an API used from an API extended (SPI)
> > because the constraints are different:
> >
> > - APIs used can add new methods and should be interfaces rather than
> > classes.
> > - APIs extended (SPIs) should be abstract classes so that a new contract
> > added can be offered by the project without breaking implementors.
> >
> > But from a user point of you, I’m tempted to say "so what?”. It does not
> > change your inclination to make use of that contract.
> >
> > It is useful to differentiate application developer(*) facing APIs from
> > framework/integrator facing APIs (FPIs) to keep the API simple to use and
> > to document. There is also a tendency to consider the application developer
> > more sacred than the framework/integrator when it comes to breaking
> > backward compatibility.
> >
> > (*) I say application developer here but it really the primary user group
> > of your project whereas the integrators are usually less numerous and more
> > controllable.
> >
> > To me the latter (API/FPI) is more generally useful and that is the one I
> > wish to separate in different packages naming conventions.
> > The former it seems to me is very often self-obvious to the user and
> > project maintainers. And from a usage PoV, it does not really matter. Plus
> > there are cases where a contract is both used and extended (JDBC’s
> > Connection contract for example).
> >
> > Can and should we split according to both dimensions? I don’t think so.
> > And if I have to chose, I’d prefer to split according to the API/ FPI
> > dimension which is more generally useful to our customers and makes it
> > clear what is non breakable (API), what is inconvenient to break (FPI),
> > what is free lunch (implementation).
> >
> > ## References
> >
> > There has been some discussions in the past as well
> > https://issues.jboss.org/browse/TAG-47
> >
> > Emmanuel
> > _______________________________________________
> > hibernate-dev mailing list
> > hibernate-dev at lists.jboss.org
> > https://lists.jboss.org/mailman/listinfo/hibernate-dev
> >