[hibernate-dev] Redefining the API/SPI/implementation split

[Sanne Grinovero]

Thanks all,
so I went for the "friend" package name, adding a brief notice in the javadocs.

https://github.com/Sanne/hibernate-search/blob/HSEARCH-1739/engine/src/main/java/org/hibernate/search/engine/friend/package-info.java

Sanne

On 6 December 2014 at 16:02, Steve Ebersole <steve at hibernate.org> wrote:
>> Sometimes it's just convenience; we have an "util.JNDIHelper" which is
>> needed in several modules (Massindexer statistics, JMS lookups, etc..)
>> and I don't think we should expose it as an API nor that another
>> project like Infinispan Query should ever use it.
>
>
> It's funny you bring up JNDIHelper specifically.  ORM used to have a
> JNDIHelper class as well and I went through this same exercise.  In ORM
> JNDIHelper is now the JndiService (I treat "well known acronyms" as words
> for the purpose of camel casing).  But the important point is that it is a
> service, available from the service registry.  To me, access to the service
> registries and their services overall, is an SPI concern.  If some 3rd party
> integration wants to use Hibernate's JndiService as part of its integration
> (and some cache integrations do), I am more than ok with that.
>
>
>>
>> > Isn't it our definition of a SPI?
>>
>> No. I just realised our definition of SPI isn't adequate as there are
>> two different kinds of integration points.
>
>
> In my opinion we have many more "levels" of SPI then just 2.  We have even
> discussed how to handle some of the differences a few times in f2f or irc.
>
> An SPI describes a contract meant for integration.  But there are many parts
> to that.  You mentioned caching, so the main contract there is the
> RegionFactory.  So obviously an integrator is implementing that.  The
> RegionFactory is returning Region instances.  those 2 contracts need to
> remain stable.  Since the integrations implement those contracts, any
> changes of any kind to the contracts require changes to the implementation
> (aside from certain cases involving supplied base implementations).  Most of
> the methods on RegionFactory to build a Region accept a CacheDataDescription
> argument.  CacheDataDescription is a "parameter object".  Changes to
> CacheDataDescription do not generally require changes to the implementation.
> I like to think of it in terms of a component and the data passed between
> Hibernate and that component.  So even though RegionFactorty, Region and
> CacheDataDescription are all "spi contracts", they fulfill very different
> roles in the concept of an SPI.  Some need to be more stable than others.
>
> I also think a lot in terms of "audience" when it comes to contracts.  I
> might write a class intending it for use by a number of different roles:
>
> Another Hibernate class
>
> In the same module
> In another module
> In another Hibernate project, although I prefer to think of this more in
> line with an "Integration"
>
> Integration
>
> As the contract for an integration
> As the communication related to that integration
>
> Application - SessionFactory, Session, etc
>
> Just wanted to clarify...
>
> Personally, I like the phrase "friend" or "family" when describing the type
> of thing you are discussing.  Not sure either of those work great as a
> package name though to denote the idea of "stay away".