[infinispan-dev] Deprecating the @ProvidedId annotation w/o a replacement in place

[Sanne Grinovero]

I'm deprecating the `org.hibernate.search.annotations.ProvidedId`
annotation in Hibernate Search.

This was originally introduced when Infinispan Query was first
designed as a way to mark the Infinispan value object as "something
which doesn't contain the id", since in the key/value store world the
key can usually not be extracted from the value (which is a difference
from the Hibernate ORM world).

In early days, this meant that all indexed objects in Infinispan had
to be marked with this, but we quickly fixed this oddness by simply
assuming that - when using Hibernate Search to index Infinispan
objects - we might as well consider them all annotated with
@ProvidedId implicitly.

So the main reason for this annotation to exist is long gone, but its
role evolved beyond that.


This annotation was also enabling a couple more features:
 A] allow the user to pick the index field name used to store the IDs
 B] allow to bind a custom FieldBridge to the key type

# A: customizing the field name from "providedId"

I don't think this is actually very useful. It is complex to handle
when different types might want to override this, and the rules at
which this is valid across inherited types.
I'm proposing we take this "mapping flexibility" away with no replacement.

# B: custom FieldBridge for indexing of Infinispan keys

Infinispan already has the notion of Transformers, which is similar
but not quite the same. The differences are confusing, and neither of
them actually makes it very clear how to e.g. search by some attribute
of the key type.
Clearly there's need for a better approach to deal with keys, and
@ProvidedId doesn't fit well in such plans.

For now I plan to mark @ProvidedId as deprecated; although I won't
remove it yet until we have an alternative in place to better deal
with keys.

However, I'm unable to properly document what its replacement should
be until we fleshed out the alternative.

I'd like to proceed with the deprecation even without having the
replacement already as I suspect what we had so far for indexing keys
was not good enough anyway. Deprecating it is rather urgent as it
turns out it's all quite confusing when this annotation should be
used.

Thanks,
Sanne