[hibernate-dev] [Search] OSGi split packages

[Hardy Ferentschik]

On 26 Jan 2014, at 23:11, Sanne Grinovero <sanne at hibernate.org> wrote:

> On 26 March 2014 20:18, Hardy Ferentschik <hardy at hibernate.org> wrote:
>> 
>> On 26 Jan 2014, at 20:52, Sanne Grinovero <sanne at hibernate.org> wrote:
>> 
>>> The classes in the ORM module are extremely widely used by our primary target:
>>> 
>>> - FullTextQuery
>>> - Search
>>> - FullTextSession
>>> 
>>> and two more lesser ones, but I think the 3 above are probably "THE
>>> API”.
>> 
>> That was my thinking as well.
>> 
>>> To move these out of the way we'd at least need to postpone the
>>> OSGi work for after a Beta to include a deprecated version of these.
>> 
>> ? I don’t get what you are saying here. Deprecate it in an Alpha in order
>> to then move them in a Beta release? That makes no sense what soever to me.
>> My take on this is, that we are dealing with a new major version of Search
>> and that we are still in Alpha phase. If we need to make non backwards
>> compatible changes we should do it now.
> 
> If we need to change public API we have the obvious options:
> 1# just break the API
> 2# deprecate the old one
> 
> I didn't mean that we stricly should do 2#, but we should at least try hard ;-)
> But *if* we go for 2#, we should keep the deprecated classes around
> for at least a Beta release, or the effort (of keeping them) is not
> worth it as I think an Alpha release is not going to inspire enough
> confidence, or have enough visibility, for us to suggest using it as a
> migration milestone.

I just don’t get your migration milestone idea. I doubt seriously that many users 
have the time and resources to gradually upgrade from let’s say a 4.x version to
5.0.0.Alpha1, 5.0.0.Beta1, … 5.0.0.Final. There might be some early adopters 
and contributors who are interested in Search, but in most cases I would expect
people to wait at least until a CR and then do a direct upgrade. 

Also you approach seems to me against my understanding of the different release
steps towards a Final. I would use the Alpha releases to actually make the 
breaking changes and getting more stable once we get to Beta. In your approach things would 
still work in let’s say Beta1, but then get removed for Beta2 or even a CR. For me
that’s contradictive. Personally I also the deprecations as a tool to keep backwards
compatibility between final releases, not between intermediate releases working towards 
a final.

For me the question is, do we see a future of Search in OSGi and do we want to invest 
into making Search fully OSGi enabled or not. If so we should just go ahead and resolve these
split packages. If we don’t see OSGi as so important we should just add the minimum of
metadata information to the artefacts and use the Require-Bundle workaround and be done with it.

> Problem is, that if we keep them you might not be able to finish the
> OSGi issue, as it requires these classes to be removed.

Well, I guess since the alternative classes would exist at the time of deprecation, we would export them
from the bundle, ignoring the deprecated ones.

> Or maybe we can relax this requirement temporarily? I guess the important
> milestone to aim at is to define the final API?

What do you mean with define API. For me the API is defined. We are not making changes to the API as such.

> I guess we shouldn’t necessarily aim at fully resolving HSEARCH-1465 in a single tag,

Not me either. HSEARCH-1465 is the container issue for all OSGi related tasks. HSEARCH-1560 is just one of the 
sub tasks which imo needs to be resolved in one go.


>> Mind you, we are talking just about an import statement change. No API
>> or functional change. And yes, our downstream projects would need to adjust.
> 
> I get that. Still a nice self-documenting deprecated class is so much
> easier to handle than an import statement change.

Except, that deprecations can be ignored. Not that many developers pay careful attention to the build log and
depending on how much logging the build does it might just disappear in the noise. So when will the user actually 
notice the change? When we remove the deprecated class! At some stage the users of Search need to 
adjust their imports. I’d rather let them handle a couple of compilation failures and be done with it.

>>> I think I like Hardy's approach of moving from Engine better; not
>>> least we can provide alternative deprecated constants in the ORM
>>> module for ORM users to use as a migration help (Environment and
>>> ProjectionConstants).
>> 
>> ?
> 
> You could make a copy of Environment and ProjectionConstants in the
> ORM module, and deprecate it to document the new position. Maybe we
> shouldn't invest too much into backwards compatibility, but since this
> is a trivial step we should just do it.

-1

>> I like it. In fact I wish cfg would have been called configuration in the first place.
>> Having both, cfg and configuration seems odd to me. In this case I prefer to just
>> use cfg
> 
> Same here. I almost suggested to rename all of _cfg_ to
> _configuration_ but I didn't realize it contained so much public API,
> so +1 to stick with cfg.

ok

> the tricky part is that today SearchFactoryIntegrator extends
> SearchFactory, but since SearchFactoryIntegrator needs to say in
> Engine, it can't depend on SearchFactory. What would you think of
> breaking this parent-child relation?
> From a user's perspective they wouldn't be able to narrow down their
> SearchFactory to an SearchFactoryIntegrator, but we could provide an
> unwrap backdoor.

I also think that in general an unwrap is better. +1 for this

>  some of
> these changes look like reasonable even out of the OSGi requirements
> scope :-)

Right, I also think that some of these changes make sense one way or another. 


—Hardy