[Equivalence] Add factory methods for multiple and/or nested fields

[NathanJAdams]

Use Case
My use case is for the Equivalence class and is to enable checking against multiple nested fields. It isn't yet supported I'd like to add support for it. There's an added benefit too - it would reduce and simplify the amount of client code needed to create Equivalence objects.

Issues

1. There is an Equivalence.onResultOf() method but it only takes one Function, if you only need to test one field that's fine, but if you want to test multiple fields then you have to create your own Functions that delegate to each in turn.
2. The onResultOf() method can be chained, but it creates an extra object for each Function tested. It should be possible to create only one object for multiple Functions.
3. The code needed to create the chain is quite verbose and could be reduced and simplified with the right method declarations.

Solution
Add factory methods to create Equivalence objects that take multiple Functions or multiple Equivalences. This will solve all 3 issues above and would be invoked something like eg.

ofFields(Class1::getField1, Class1::getField2);
or
ofSubFields(Class1::getField1, ofFields(Field1::getSubField1, Field1::getSubField2));

Any thoughts on this would be much appreciated

[nick-someone]

I think some more example code would be helpful, but one aspect to keep in mind is that onResultOf is really just a transformational adapter to allow an equivalence on Y to be used as an equivalence on X when there exists a Function<X, Y>.

In your examples (and your use case), you seem to be making an assumption that the Equivalence<Y> is valid for all of the fields. Consider an example equivalence like:

Equivalence<Integer> SAME_ODDNESS = new Equivalence<Integer>(){ 
   protected boolean doEquivalent(Integer a, Integer b) {
     return a % 2 == b % 2;
  }
  ...
}

Equivalence<DomainObject> FOO_PROP_HAS_SAME_ODDNESS =
    SAME_ODDNESS.onResultOf(DomainObject::getFoo);

Here, I don't see how ofFields and ofSubFields would work here. Would it be the case that you test all of getField1, getField2, etc. against the equivalence, and the original equivalence would have to be applicable to all of them? What happens with null references, etc.

[NathanJAdams]

Ah ok apologies for the slight miscommunication, the methods of(Sub)Field(s) would all be static factory methods and ofField would be similar to what onResultOf does already but with the invoking object being the last parameter instead. So with the example you mentioned it would look something like:

Equivalence<DomainObject> FOO_PROP_HAS_SAME_ODDNESS = Equivalence.ofField(DomainObject::getFoo, SAME_ODDNESS);

The singular versions would have overloads that allow an Equivalence to be injected for that field type and would be needed for any transformations as you say.
The plural versions would delegate to Objects::equals to compare fields (works with nulls) but would allow multiple fields to be combined at once into a single Equivalence object.

[nick-someone]

The plural versions would delegate to Objects::equals to compare fields (works with nulls) but would allow multiple fields to be combined at once into a single Equivalence object.

I think there's still some assumption about equals() as the primary mechanism of equivalence that just doesn't apply to Equivalences in general.

It sounds like you're looking to create something like:

Equivalence<DomainObject> equivalentByCompoundObjectEqualOfFields = new Equivalence<DomainObject>() {
   protected boolean doEquivalent(DomainObject a, DomainObject b) {
    if (Objects.equals(a.field1, b.field1) && (field 2, field 3, etc))
  }
};

with a number of different factory methods, something like:

Equivalence<DomainObject> equalByInterestingSubfields =  
  Equivalence.equals().onResultOf(DomainObject::getField1)
    .andAlsoBy(Equivalence.equals().onResultOf(DomainObject::getField2))
    .andAlsoBy(SAME_ODDNESS.onResultOf(DomainObject::getIntField));

Is this (not-yet-existing API) close to what you're looking for?

One other alternative to this compound equivalence chain is to create an "equivalence value object", representing the fields, then using Equivalence.equals().onResultOf(domainObject -> EquivalenceObject.fromDomainObject(domainObject)).

EquivalenceObject could be an AutoValue that contains field1, field2, etc. and copies it from DomainObject.

[Maaartinus]

Just to throw in some ideas:

Equivalence<DomainObject> equivalentByCompoundObjectEqualOfFields = Equivalence.
.compareUsing(Equivalence.equals(), DomainObject::getField1, DomainObject::getField2)

and

Equivalence<DomainObject> equalByInterestingSubfields = Equivalence.
.compare(DomainObject::getField2)
.compareUsing(SAME_ODDNESS, DomainObject::getIntField, DomainObject::getIntField2)

In compareUsing, the parameters are a delegate Equivalence, followed by any number of field extracting methods. compare is just a shortcut defaulting the first argument to Equivalence.equals(). I did't try to invent good names.

One other alternative to this compound equivalence chain is to create an "equivalence value object" ...

I'm afraid, this couldn't do things like

Equivalence
.compareUsing(Equivalence.equals(), DomainObject::getField1)
.compareUsing(Equivalence.identity(), DomainObject::getField2)
.compareUsing(Equivalence.arrayEquals(), DomainObject::getSomeByteArray)

[NathanJAdams]

Lots of great ideas thank you both. I'll put a first draft PR together and see what you think

[nick-someone]

https://github.com/google/guava/wiki/HowToContribute#new-features

I think there's still lots more discussion to be had about these new features (shape of methods, features, details, etc.) before proceeding to implementation.

If you want to put a PR together, note that it would primarily be a platform for more discussion about the actual methods/details.

[lowasser]

If you want to pursue something like this, I think you might want to look really hard at how the new Comparator factory methods in Java 8 work -- honestly, I think the strategy they took there works really well.

I wouldn't worry in the slightest about object allocation, in all honesty, at least up-front. Equivalences should usually be stored in static constants.

[Maaartinus]

Sure, J8 Comparator is really nice and feels very natural. To me Equivalence::onResultOf feels backwards, as it uses the this equivalence to compare the extracted fields... I find it rather hard to read, especially with chaining like above.

I guess, Equivalence could much more often than Comparator use multiple fields (without any delegate equivalence), so

.comparing(keyExtractor1, keyExtractor2, keyExtractor3)

could be an useful shortcut for

.comparing(keyExtractor1).thenComparing(keyExtractor2).thenComparing(keyExtractor3)

Also comparingInt and comparingLong (with their then-variants) are surely useful (unlike comparingDouble). As the order of comparisons is basically irrelevant here, I could imagine things like

.comparingInt(intExtractor1, intExtractor2, intExtractor3)
.thenComparingLong(longExtractor4)
.thenComparing(objectExtractor5, objectExtractor6)

They may be even more efficient than comparing fields in source code order as the primitive comparison is way faster. This expression is nicely compact, but probably more error-prone.

For objects, some

.comparingVia(delegateEquivalence, keyExtractor1, keyExtractor2, ...)

might be useful enough to justify reversing the parameter order from comparing(keyExtractor, keyComparator).

For composing arbitrary equivalences

.thenComparing(anotherEquivalenceOnTheSameType1)

would be nice (possibly also varargs).

Nulls and reverse order don't apply, so that's all I can think of.

[NathanJAdams]

Comparator chaining
I totally agree the Comparator chaining is very nice and natural to use. Having looked at their implementations, they use a combination of a similarly named static factory method with a joining method to create the resultant Comparator.
We could follow a similar pattern here and have a generic combining method and similarly named instance methods that delegate to their static factory method counterparts.
Perhaps the chaining methods could be named something like
andAlso<factory method name>()

Generic and Specifically typed methods
Comparator has both generic and specifically typed methods eg. comparing(), comparingInt() and comparingLong()
Obviously we'll have the generic methods but what about specifically typed ones eg. primitives, String, arrays, primitive arrays, multi-dimensional arrays etc.?
Are the use cases for these widespread enough to be useful adding specific methods for some of them?

Current progress
There's 5 factory methods so far - here's how they'd be called:

ofDelegate()
takes a BiFunction<? super T, ? super T> that doEquivalent() delegates to
and a ToIntFunction<? super T> that doHash() delegates to
Equivalence<Integer> e1 = ofDelegate((a, b) -> (a % 2) == (b % 2), i -> i % 2);

ofFunction()
helper method for ofDelegate() that takes a Function<? super T, ?>
doEquivalent() delegates the transformed inputs to Objects::equals
doHash() delegates the transformed input to Objects::hashCode
Equivalence<Integer> e2 = ofFunction(i -> i % 2);

ofFunctions()
uses a single Equivalence<F> against a varargs array of Function<? super T, ? extends F>
inputs are transformed by each Function in turn before being passed to the Equivalence
Equivalence<Class1> e3 = ofFunctions(Equivalence.identity(), Class1::getString, Class1::getField2);

join()
combines a varargs array of Equivalence<? super T> together
doEquivalent() checks all the Equivalences
doHash() combines all the hash codes together
Equivalence<String> e4 = join(Equivalence.equals(), Equivalence.identity());

ofNested()
takes a Function<? super T, ? extends F> followed by a varargs array of Equivalence<? super F>
passes the inputs through the Function then passes the transformed input to all the Equivalences
allows arbitrarily deep nesting
Equivalence<Class1> e5 = ofNested(Class1::getField2,
    ofNested(Class2::getField3,
        ofFunctions(Equivalence.identity(), Class3::getString),
        ofNested(Class3::getString2,
            ofFunction(String::length))));

As always any thoughts, comments or suggestions are much appreciated

[NathanJAdams]

One more thought, equals and identity semantics are probably the most used equivalences. So we could have helper methods for ofDelegate() and ofFunctions() that inject Equivalence.equals() and Equivalence.identity() respectively.
The ofFunction() method is a helper for ofDelegate() which uses equals semantics, it could be renamed to ofDelegateEquals() and we could have a ofDelegateIdentity() method.
Likewise with ofFunctions()<Equals | Identity>()

Anyway the initial PR is coming soon.