[hibernate-dev] [Search] OSGi split packages

[Sanne Grinovero]

It's a though choice.

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". 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.
Or we keep them around in the backwards compatible module
"hibernate-search" ?
Doesn't seem like a piece of cake to be able to actually handle this
duplication in our implementation.

On the other option, in Engine we have:
- Environment (containing all the configuration constants)
- ProjectionConstants (more useful constants)
- SearchException
- SearchFactory (another strong case of public API)

Also to remember the changes in Engine also affect the HQL parser
(OGM) and Infinispan Query and its users; we can adapt for it but
ultimately that's our responsibility too, probably best to verify
early on to see the impact. Not really a reason to not do it, but it
has an impact on several other projects which we need to facilitate.

Now so far I've only tackled the "migration problem", but I guess the
goal should be to get to the best outcome in terms of what's more
sensible.

Emmanuel, could you elaborate of what you have in mind as "scalability reasons"?

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).

To reply on the more fine-grained details:

> org.hibernate.search.Environment        ->  org.hibernate.search.cfg.Environment

since it's API, WDYT of a fully fledged mouthfull
"org.hibernate.search.configuration.Environment"

> org.hibernate.search.SearchFactory     ->  org.hibernate.search.spi.SearchFactory

as Emmanuel said, that's an API currently. I'm inclined to think we
should convert it to an SPI, and provide a richer more ORM specific
version in the ORM module?
That way, we could keep the package name. It would break things for
Infinispan Query API but it seems that would happen anyway.

> org.hibernate.search.SearchException ->  org.hibernate.search.exception.SearchException

Maybe making the package plural? We should add variations for specific failures.

> org.hibernate.search.FullTextFilter        ->  org.hibernate.search.filter.FullTextFilter

"filtering" ? "filters" ?
Not too fond of the singular term as it's not very explicit (yes I
know it's an existing one).

> org.hibernate.search.Version                ->  org.hibernate.search.engine.Version

+1

Cheers,
Sanne


On 26 March 2014 12:55, Emmanuel Bernard <emmanuel at hibernate.org> wrote:
> I don't have a full grasp of the consequences, I'll need to think about
> it.
> Here are a few comments in the mean time.
> SearchFactory is not a SPI, it is used by application developers.
> For scalability reasons, I would be tempted to move the orm module
> classes out of the root package. But that is definitely the most
> impactful of the two moves.
>
> Emmanuel
>
> On Tue 2014-03-25 22:11, Hardy Ferentschik wrote:
>> Hi there,
>>
>> As part of my work for making Search OSGi ready [1], I am looking into addressing HSEARCH-1560 [2] which is about
>> split packages which we have between some of our Search bundles (or modules to use Maven lingo).
>>
>> Basically a split package "is caused where two or more bundles export the same package name and version, usually with different contents”. [3]
>> In terms of OSGi, split packages are bad and should be avoided. There exists a work around [3], but afaiu it is frowned upon.
>> While working on an integration test  trying to run Search in Apache Karaf, I was running into this problem and basically needed (for the time being)
>> revert to the mentioned work around.
>>
>> The biggest for getting rid of split packages is org.hibernate.search which is a split packages between the engine and orm bundle. In org.hibernate.search of engine
>> we have:
>> - Environment,
>> - FullTextFilter,
>> - ProjectionConstants,
>> - SearchException,
>> - SearchFactory
>> - Version.
>>
>> org.hibernate.search of orm contains:
>> - FullTextQuery,
>> - FullTextSession,
>> - FullTextSharedSessionBuilder,
>> - MassIndexer
>> - Search.
>>
>> As you can see, these are quite central classes  and moving any of them around will break existing code (even though updating just requires
>> to change import statements). If we are serious with OSGi we should address this. We always said, that Search 5 is the release where we can break
>> API backwards compatibility. So if we want to do this, we should do it now.  On the other hand, it is a big change.
>>
>> I went ahead and tried to refactor org.hibernate.search in engine, applying the following changes:
>>
>> org.hibernate.search.Environment        ->  org.hibernate.search.cfg.Environment
>> org.hibernate.search.SearchFactory     ->  org.hibernate.search.spi.SearchFactory
>> org.hibernate.search.SearchException ->  org.hibernate.search.exception.SearchException
>> org.hibernate.search.FullTextFilter        ->  org.hibernate.search.filter.FullTextFilter
>> org.hibernate.search.Version                ->  org.hibernate.search.engine.Version
>>
>> Some of these changes I actually find quite fitting independently  of the split package problem. FullTextFilter seems to have found its true home now
>> and Version and Environment don’t seem too bad either. The big change is SearchFactory and .SearchException.
>>
>> WDYT? Is this package refactoring something worth doing and if so what do you think about the new locations of the classes? Any better suggestions?
>> Or do you think the orm bundle should be refactored instead?
>>
>> You can see the preliminary result here [4].
>>
>> —Hardy
>>
>> [1] https://hibernate.atlassian.net/browse/HSEARCH-1465
>> [2] https://hibernate.atlassian.net/browse/HSEARCH-1560
>> [3] http://wiki.osgi.org/wiki/Split_Packages
>> [4] https://github.com/hferentschik/hibernate-search/compare/HSEARCH-1560
>> _______________________________________________
>> hibernate-dev mailing list
>> hibernate-dev at lists.jboss.org
>> https://lists.jboss.org/mailman/listinfo/hibernate-dev
> _______________________________________________
> hibernate-dev mailing list
> hibernate-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/hibernate-dev