Add the notion of equivalence

[Ladislav Thon]

Jandex classes often don't have equals at all, or have equals that isn't necessarily useful. That makes perfect sense e.g. in case of annotation overlaying, where you would have e.g. two ClassInfo objects for the same class, each having a different set of annotations. These ClassInfo objects should not be considered equal, but they should be considered equivalent.

I can see several ways how equivalence could be introduced to Jandex. I'm currently thinking it should be completely separate from the AnnotationTarget hierarchy. Something like this:

public class EquivalenceKey {
    public static EquivalenceKey of(ClassInfo) { ... }
    public static EquivalenceKey of(MethodInfo) { ... }
    public static EquivalenceKey of(MethodParameterInfo) { ... }
    public static EquivalenceKey of(FieldInfo) { ... }

    // guaranteed to have `equals` and `hashCode` (and `toString`)
    // everything else would be private
}

[Ladislav Thon]

I've already implemented this, but it needs more thinking (and also adding tests and documentation, the usual). In my current implementation, equivalence is established like this:

• for classes: based on the name
• for methods: based on the name of the declaring class, the name of the method, and the list of parameter types
• for method parameters: based on the method equivalence key and the parameter index
• for fields: based on the name of the declaring class and the name of the field

I'm pretty confident it's fine for classes and fields (and method parameters, because they delegate to method equivalence). For methods, return type most likely needs to be considered too (as I said, more thinking).

[Ladislav Thon]

Done in #173.