[hibernate-dev] Should we deprecate @Similarity

[Sanne Grinovero]

Discussing about some hibernate-search-engine complexities with Hardy
on IRC, we came to the agreement that the way @Similarity behaves
today was a mistake, so we're proposing to deprecate it in 4.4.

Reasoning follows.

There is a strong requirement in Lucene that all operations on the
same index need to use the same Similarity implementation. We infer
the org.apache.lucene.search.Similarity to be used on a specific index
from either:

- the similarity property from the configuration file, which is
positioned on an index name
- the @Similarity annotation positioned on an indexed entity

The trouble is about all these options needing to be consistent; first
problem is there isn't a precedence rule: if one of them is not
specified, we assume the user is using the other way to configure
things. But also different entities might be sharing the same index,
which leads to needing to verify that at least the user isn't
specifying some contradictory option.

This all gets more confusing when you introduce the notion of
dynamically added new entities (a feature used by Infinispan) and/or
Dynamic Sharding, in which the properties of some indexes might
conflict with the specified @Similarity, but we might notice this only
at runtime rather than at bootstrap. Failing to load a class at this
point is far more annoying to the users than to fail the health-check
at bootstrap time.

So the proposal:
drop the @Similarity annotation and use properties exclusively.
Properties are more suited for this as they are set on a per-index
base, which is what matters in this case.

Downside:
I guess lots of people where using a single index per type, and for
those there was no danger to simply specify a @Similarity. We lose
this straight-forward way of things, but I'd argue that if you're in
the business of specifying a custom Similarity, you're a very advanced
user and wouldn't mind setting a one-liner in your configuration file.

Do we agree?

Sanne