Page History

...

The equals() method applies only to objects, not primitives. It is unnecessary to override the equals method when checking for logical equality is not useful. For example, enumerated types have a fixed set of distinct values that may be compared using == rather than the equals() method. Note that enumerated types provide an equals() implementation that uses == internally; this default cannot be overridden. More generally, subclasses that both inherit an implementation of equals() from a superclass and also lack a requirement for additional functionality need not override the equals() method.

...

Never violate any of these requirements when overriding the equals() method.

Noncompliant Code Example (Reflexivity)

Mistakes resulting from a violation of the first requirement are infrequent; consequently we omit noncompliant code examples for this case. We provide noncompliant code examples for the second requirement (symmetry) and the third requirement (transitivity). The consistency requirement implies that mutable objects may be unable to satisfy the equals() contract. Consequently, it is good practice to avoid defining equals() implementations that use unreliable data sources such as IP addresses and caches. The most common violation of the final requirement (regarding comparison with null) is equals() methods whose code throws an exception rather than returning false. This can constitute a security vulnerability (in the form of denial of service). The simple solution is to return false rather than to throw the exception.

Noncompliant Code Example (Symmetry)

Noncompliant Code Example (Symmetry)

This noncompliant code example defines a CaseInsensitiveString class that includes a String and overrides the equals() method. The CaseInsensitiveString class knows about ordinary strings but the String class has no knowledge of case-insensitive strings. Consequently, CaseInsensitiveString.equals() method should not attempt to interoperate with objects of the String classThis noncompliant code example defines a CaseInsensitiveString class that includes a String and overrides the equals() method. The CaseInsensitiveString class knows about ordinary strings but the String class has no knowledge of case-insensitive strings. Consequently, CaseInsensitiveString.equals() method should not attempt to interoperate with objects of the String class.

public final class CaseInsensitiveString {
  private String s;

  public CaseInsensitiveString(String s) {
    if (s == null) {
      throw new NullPointerException();
    } 
    this.s = s;
  }

  // This method violates symmetry
  public boolean equals(Object o) {
    if (o instanceof CaseInsensitiveString) {
      return s.equalsIgnoreCase(((CaseInsensitiveString)o).s);
    }

    if (o instanceof String) {
      return s.equalsIgnoreCase((String)o);
    }
    return false;
  }

  public static void main(String[] args) {
    CaseInsensitiveString cis = new CaseInsensitiveString("Java");
    String s = "java";
    System.out.println(cis.equals(s)); // Returns true
    System.out.println(s.equals(cis)); // Returns false
  }
}

...

class XCard {
  private String type;
  private Card card; // Composition
  
  public XCard(int number, String type) {
    card = new Card(number);
    this.type = type;
  }
	  
  public Card viewCard() {
    return card;
  }

  public boolean equals(Object o) {
    if (!(o instanceof XCard)) {
      return false;
    }
      
    XCard cp = (XCard)o;
    return cp.card.equals(card) && cp.type.equals(type);
  }
	  
  public static void main(String[] args) {
    XCard p1 = new XCard(1, "type1");
  }
	  
Card p2 public= staticnew void main(String[] args) {Card(1);
    XCard p1p3 = new XCard(1, "type1type2");
    CardXCard p2p4 = new Card(1);
    XCard p3 = new XCard(1, "type2");
    XCard p4 = new XCard(1, "type1"); XCard(1, "type1");
    System.out.println(p1.equals(p2)); // Prints false
    System.out.println(p2.equals(p3)); // Prints false
    System.out.println(p1.equals(p3)); // Prints false
    System.out.println(p1.equals(p2)); // Prints false
    System.out.println(p2.equals(p3)); // Prints false
    System.out.println(p1.equals(p3)); // Prints false
    System.out.println(p1.equals(p4)); // Prints true
  }
}
p1.equals(p4)); // Prints true
  }
}

Noncompliant Code Example (Consistency)

The consistency requirement implies that mutable objects may be unable to satisfy the equals() contract. Consequently, it is good practice to avoid defining equals() implementations that use unreliable data sources such as IP addresses and caches.

Noncompliant Code Example (Non-null references)

The most common violation of the final requirement (regarding comparison with null) is equals() methods whose code throws an exception rather than returning false. This can constitute a security vulnerability (in the form of denial of service). The simple solution is to return false rather than to throw the exception.

Exceptions

*MET12-EX1EX0:* This guideline may be violated provided that the incompatible types are never compared.  There are classes in the Java platform libraries (and elsewhere) that extend an instantiable class by adding a value component.  For example, {{java.sql.Timestamp}} extends {{java.util.Date}} and adds a nanoseconds field. The {{equals}} implementation for {{Timestamp}} violates symmetry and can cause erratic behavior if {{Timestamp}} and {{Date}} objects are used in the same collection or are otherwise intermixed." \[[Bloch 2008|AA. Bibliography#Bloch 08]\]

...