MET12-J. Ensure objects that are equated are equatable

Composition may be used to create a new class that both encapsulates an existing class and adds a variable or field, the value of which must be equal for objects of this new class to be equal. When objects of this new class are equated with objects of the encapsulated class, the new class must override the Object.equals() method. Furthermore, this method must follow the general contract for equals() as specified by the Java Language Specification [[JLS 2005]].

An object is characterized both by its identity (location in memory) and by its state (actual data). The == operator compares only the identities of two objects (to check whether the references refer to the same object); the equals method defined in java.lang.Object can be customized by overriding to compare the state as well. When a class defines an equals() method, it implies that the method compares state. When the class lacks a customized equals() method (either locally declared, or inherited from a parent class), it uses the default Object.equals() implementation that is inherited from Object which compares only the references and may produce unexpected results.

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.

The general usage contract for equals() as specified by the Java Language Specification establishes five requirements:

1. It is reflexive: For any reference value x, x.equals(x) must return true.
2. It is symmetric: For any reference values x and y, x.equals(y) must return true if and only if y.equals(x) returns true.
3. It is transitive: For any reference values x, y, and z, if x.equals(y) returns true and y.equals(z) returns true, then x.equals(z) must return true.
4. It is consistent: For any reference values x and y, multiple invocations of x.equals(y) consistently return true or consistently return false, provided no information used in equals comparisons on the object is modified.
5. For any non-null reference value x, x.equals(null) must return false.

Never violate any of these requirements when overriding the equals() method. 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)

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 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
  }
}

By operating on String objects, the CaseInsensitiveString.equals() method violates the second contract requirement (symmetry). Because of the asymmetry, given a String object s and CaseInsensitiveString object cis that differ only in case, cis.equals(s)) returns true while s.equals(cis) returns false.

Compliant Solution

In this compliant solution, the CaseInsensitiveString.equals() method is simplified to operate only on instances of the CaseInsensitiveString class, consequently preserving symmetry.

public final class CaseInsensitiveString {
  private String s;

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

  public boolean equals(Object o) {
    return o instanceof CaseInsensitiveString &&
    ((CaseInsensitiveString)o).s.equalsIgnoreCase(s);
  }

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

Noncompliant Code Example (Transitivity)

This noncompliant code example defines an XCard class that extends the Card class.

public class Card {
  private final int number;

  public Card(int number) {
    this.number = number;
  }

  public boolean equals(Object o) {
    if (!(o instanceof Card)) {
      return false;
    } 
    
    Card c = (Card)o;
    return c.number == number;
  }
}

class XCard extends Card {
  private String type;
  public XCard(int number, String type) {
    super(number);
    this.type = type;
  }

  public boolean equals(Object o) {
    if (!(o instanceof Card)) {
      return false;
    } 

    // Normal Card, do not compare type 
    if (!(o instanceof XCard)) {
      return o.equals(this);
    } 

    // It is an XCard, compare type as well
    XCard xc = (XCard)o;
    return super.equals(o) && xc.type == type;
  }	  
  
  public static void main(String[] args) {
    XCard p1 = new XCard(1, "type1"); 
    Card p2 = new Card(1);
    XCard p3 = new XCard(1, "type2");
    System.out.println(p1.equals(p2)); // Returns true
    System.out.println(p2.equals(p3)); // Returns true
    System.out.println(p1.equals(p3)); // Returns false, violating transitivity
  }
}

In the noncompliant code example, p1 and p2 compare equal and p2 and p3 compare equal but p1 and p3 compare unequal; this violates the transitivity requirement. The problem is that the Card class has no knowledge of the XCard class and consequently cannot determine that p2 and p3 have different values for the field type. Unfortunately, it is impossible to extend an instantiable class (as opposed to an abstract class) by adding a value or field in the subclass while preserving the equals() contract.

Compliant Solution

It is impossible to extend an instantiable class while preserving the equals() contract; use composition rather than inheritance to achieve the desired effect [[Bloch 2008]]. This compliant solution adopts this approach by adding a private card field to the XCard class and providing a public viewCard() method.

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 = new Card(1);
    XCard p3 = new XCard(1, "type2");
    XCard p4 = new 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(p4)); // Prints true
  }
}

Exceptions

MET12-EX1: 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]]

Risk Assessment

Violating the general contract when overriding the equals() method can lead to unexpected results.

Related Vulnerabilities

Search for vulnerabilities resulting from the violation of this rule on the CERT website.

Bibliography

[[API 2006]] method equals()
[[Bloch 2008]] Item 8: Obey the general contract when overriding equals
[[Darwin 2004]] 9.2 Overriding the equals method

MET11-J. Never declare a class method that hides a method declared in a superclass or superinterface      05. Methods (MET)      MET13-J. Classes that define an equals() method must also define a hashCode() method