Re: [hibernate-dev] Compatibility Considerations wiki
2014-08-25 18:33 GMT+02:00 Steve Ebersole <steve(a)hibernate.org>:
On Mon, Aug 18, 2014 at 2:14 AM, Gunnar Morling
<gunnar(a)hibernate.org>
wrote:
> Hi Steve,
>
> Thanks for writing up these rules. That's very valuable information for
> users and us as well.
>
> Only two remarks on the following:
>
> > The use of package names for this is unfortunately not granular enough
> oftentimes.
> > Ultimately I would envision a better solution (annotations?)
>
> In which cases is it not granular enough? Can such case not always be
> circumvented by refactoring code into separate classes within separate
> packages?
>
> I'm fearing issues with e.g. distinguishing between public (API/SPI) vs.
> internal parts on a finer level than the package, as that's what OSGi but
> also JBoss Modules rely on. We cannot fully leverage the ability of these
> module systems to "hide" internal parts of a module in that case.
>
> Also I think annotations are easier to "miss" than package names when
> importing classes into an application, thus I'm concerned about accidental
> referencing internal classes.
>
To be honest I don't remember the situations I have run into that brought
me to that conclusion.
Hard to argue against that :) I think what troubles me that the information
about public/private is "one step farther away".
E.g. when examining a client program which imports stuff from a package
with "internal" in its name, this flaw is easily detectable just by looking
at the program. Whereas with an annotation-based approach, you need to look
at the imported types themselves to learn about any un-wanted imports in
the client program.
SPI contracts should be considered stable within a release family,
not
> necessarily across different release families.
>
> A specific example, similar to the API section, would be nice, e.g.: "If
> you implement an application against an integration point from Hibernate
> ORM 4.3.0, the expectation is that it works without changes when updating
> to ORM 4.3.1. It should also continue to work when updating to ORM 4.4.x in
> the very most cases, but that's not guaranteed."
>
Actually the 4.3 -> 4.4 bit here is not really accurate, and illustrates
the main difference between an API and an SPI. Most of the time, yes,
using an SPI method from 4.3 and upgrading to 4.4 will work flawlessly.
But that is in no way by design; it just means that it worked by
happenstance.
Really, it's not by design? I'd expect that we work hard to also keep SPIs
backwards-compatible, that we don't break them easily but only if it's
there is no reasonable way around it.
Which is fine for SPI use from applications, but I think explains
why we
often run into problems with upgrades to ORM in regards to other Hibernate
projects, since the Hibernate projects tend to use a high number of these
SPIs. This would also be good to discuss.