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

[Emmanuel Bernard]

After reading this thread, `family` or `private` feel better than `friend`

BTW, can’t you isolate those classes in a dedicated package still marked `impl` but have it exposed to OSGi?
After all all this "shared but not shared because we decided to cut our software in many pieces“ is a bit of an implementation detail from a user PoV.

> On 08 Dec 2014, at 02:14, Sanne Grinovero <sanne at hibernate.org> wrote:
> 
> 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".
> _______________________________________________
> hibernate-dev mailing list
> hibernate-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/hibernate-dev