Class annotation used to assist in creating appropriate equals() and hashCode() methods.

It allows you to write classes in this shortened form:

 import groovy.transform.EqualsAndHashCode
 @EqualsAndHashCode
 class Person {
     String first, last
     int age
 }
 def p1 = new Person(first:'John', last:'Smith', age:21)
 def p2 = new Person(first:'John', last:'Smith', age:21)
 assert p1 == p2
 def map = [:]
 map[p1] = 45
 assert map[p2] == 45
 

The hashCode() method is calculated using Groovy's HashCodeHelper class which implements an algorithm similar to the one outlined in the book Effective Java.

The equals() method compares the values of the individual properties (and optionally fields) of the class. It can also optionally call equals on the super class. Two different equals method implementations are supported both of which support the equals contract outlined in the javadoc for java.lang.Object

To illustrate the 'canEqual' implementation style (see http://www.artima.com/lejava/articles/equality.html for further details), consider this class:

 @EqualsAndHashCode
 class IntPair {
     int x, y
 }
 

 public boolean equals(java.lang.Object other)
     if (other == null) return false
     if (this.is(other)) return true
     if (!(other instanceof IntPair)) return false
     if (!other.canEqual(this)) return false
     if (x != other.x) return false
     if (y != other.y) return false
     return true
 }

 public boolean canEqual(java.lang.Object other) {
     return other instanceof IntPair
 }
 

 import groovy.transform.*
 @Canonical class IntPair { int x, y }
 def p1 = new IntPair(1, 2)

 // overridden getter but deemed an IntPair as far as domain is concerned
 def p2 = new IntPair(1, 1) { int getY() { 2 } }

 // additional helper method added through inheritance but
 // deemed an IntPair as far as our domain is concerned
 @InheritConstructors class IntPairWithSum extends IntPair {
     def sum() { x + y }
 }

 def p3 = new IntPairWithSum(1, 2)

 assert p1 == p2 && p2 == p1
 assert p1 == p3 && p3 == p1
 assert p3 == p2 && p2 == p3
 

 @EqualsAndHashCode
 @TupleConstructor(includeSuperProperties=true)
 class IntTriple extends IntPair { int z }
 def t1 = new IntTriple(1, 2, 3)
 assert p1 != t1 && p2 != t1 && t1 != p3
 

 @EqualsAndHashCode(useCanEqual=false)
 class IntPair {
     int x, y
 }
 

 public boolean equals(java.lang.Object other)
     if (other == null) return false
     if (this.is(other)) return true
     if (IntPair != other.getClass()) return false
     if (x != other.x) return false
     if (y != other.y) return false
     return true
 }
 

Note that if you explicitly set useCanEqual=false for child nodes in a class hierarchy but have it true for parent nodes and you also have callSuper=true in the child, then your generated equals methods will not strictly follow the equals contract.

Note that when used in the recommended fashion, the two implementations supported adhere to the equals contract. You can provide your own equivalence relationships if you need, e.g. for comparing instances of the IntPair and IntTriple classes discussed earlier, you could provide the following method in IntPair:

 boolean hasEqualXY(other) { other.x == getX() && other.y == getY() }
 

 assert p1.hasEqualXY(t1) && t1.hasEqualXY(p1)
 assert p2.hasEqualXY(t1) && t1.hasEqualXY(p2)
 assert p3.hasEqualXY(t1) && t1.hasEqualXY(p3)
 

 import groovy.transform.*
 @EqualsAndHashCode(excludes="z")
 @TupleConstructor
 public class Point2D {
     int x, y, z
 }

 assert  new Point2D(1, 1, 1).equals(new Point2D(1, 1, 2))
 assert !new Point2D(1, 1, 1).equals(new Point2D(2, 1, 1))

 @EqualsAndHashCode(excludes=["y", "z"])
 @TupleConstructor
 public class Point1D {
     int x, y, z
 }

 assert  new Point1D(1, 1, 1).equals(new Point1D(1, 1, 2))
 assert  new Point1D(1, 1, 1).equals(new Point1D(1, 2, 1))
 assert !new Point1D(1, 1, 1).equals(new Point1D(2, 1, 1))
 

More examples:

 import groovy.transform.EqualsAndHashCode

 @EqualsAndHashCode(includeFields=true)
 class User {
     String name
     boolean active
     List likes
     private int age = 37
 }

 def user = new User(name: 'mrhaki', active: false, likes: ['Groovy', 'Java'])
 def mrhaki = new User(name: 'mrhaki', likes: ['Groovy', 'Java'])
 def hubert = new User(name: 'Hubert Klein Ikkink', likes: ['Groovy', 'Java'])

 assert user == mrhaki
 assert mrhaki != hubert

 Set users = new HashSet()
 users.add user
 users.add mrhaki
 users.add hubert
 assert users.size() == 2
 

See Also:

HashCodeHelper

Since:

1.8.0