groovy.transform
[Java] Annotation Type EqualsAndHashCode

java.lang.Object
  groovy.transform.EqualsAndHashCode

@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.TYPE})
@GroovyASTTransformationClass("org.codehaus.groovy.transform.EqualsAndHashCodeASTTransformation")
public @interface EqualsAndHashCode

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
 }
 

 @Canonical class IntPair { int x, y }
 def p1 = new IntPair(1, 2)

 // overriden 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 Point2D {
     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))
 

Authors:

Paul King

See Also:

HashCodeHelper

Since:

1.8.0

cache

public boolean cache

Whether to cache hashCode calculations. You should only set this to true if you know the object is immutable (or technically mutable but never changed). @default false

callSuper

public boolean callSuper

Whether to include super in equals and hashCode calculations. @default false

excludes

public String[] excludes

List of field and/or property names to exclude from the equals and hashCode calculations. Must not be used if 'includes' is used. For convenience, a String with comma separated names can be used in addition to an array (using Groovy's literal list notation) of String values. @default {}

includeFields

public boolean includeFields

Include fields as well as properties in equals and hashCode calculations. @default false

includes

public String[] includes

List of field and/or property names to include within the equals and hashCode calculations. Must not be used if 'excludes' is used. For convenience, a String with comma separated names can be used in addition to an array (using Groovy's literal list notation) of String values. @default {}

useCanEqual

public boolean useCanEqual

Generate a canEqual method to be used by equals. @default true

Copyright © 2003-2013 The Codehaus. All rights reserved.