introduce the notion of equivalence

[Ladicek]

Resolves #158

[Ladicek]

FYI @mkouba @FroMage, this should be pretty useful for anyone developing an annotation overlay on top of Jandex.

I'm not merging this yet, because I'd like to hear from you, and also because I really should add a few more tests :-)

[mkouba]

Perf experts always say that Objects.hash() is evil when used in hot paths because it allocates one more unnecessary array ;-). In fact, it also sometimes helps to compute the hashcode in the constructor and save it in a field.

It depends on whether we expect the equivalence keys in hash maps and in hot paths.

[Ladicek]

I'm ignoring this for now. If that ever becomes problematic, it's straightforward to improve.

[FroMage]

Looks useful, yes. But not really an annotation override ;)

[FroMage]

Is it intentional that this is targeted at the smallrye branch and not main?

[Ladicek]

Not an overlay per se, but having built an annotation overlay on top of Jandex myself, I find this a rather important building block.

I didn't consider putting this into 2.4 (would probably become 2.5?), I always thought of this as 3.0 material, but there's probably nothing preventing inclusion into 2.x.