Page History

Choosing to implement the Comparable interface represents a commitment that the implementation of the compareTo() method adheres to the general contract for that method regarding how the method is to be called. Library classes such as TreeSet and TreeMap accept Comparable objects and use the associated compareTo() methods to sort the objects. However, a class that implements the compareTo() method in an unexpected way can cause undesirable results.

The general contract for compareTo() from Java SE 8 API [API 2014] states that

Note: I merely modified the equivalent rule for equals to make this rule.
It also seems like I'm sort of just copying from the Java standard,
but I can't think of any reason why if we have an equals rule
we should not have a compareTo rule, since it is so often used with equals.
This rule could be extended to deal with Comparator as well; since they go together.

The general usage contract for compareTo() has been put forth verbatim from the Java specification:

1. The implementor must ensure sgn(x.compareTo

...

1. (y)) == -sgn(y.compareTo

...

1. (x)) for all x and y. (This implies that x.compareTo

...

1. (y) must throw an exception

...

1. if y.compareTo

...

1. (x) throws an exception.)
2. The implementor must also ensure that the relation is transitive: (x.compareTo

...

1. (y) > 0 && y.compareTo(z)

...

1. > 0) implies x.compareTo(z)

...

1. > 0.
2. Finally, the implementor must ensure that x.compareTo

...

1. (y) == 0 implies that sgn(x.compareTo(z)) == sgn(y.compareTo(z))

...

1. for all z.
2. It is strongly recommended, but not strictly required, that (x.compareTo(y) == 0) == x.equals(y). Generally speaking, any class that implements the Comparable interface and violates this condition should clearly indicate this fact. The recommended language is Note: this class has a natural ordering that is inconsistent with equals.

In the foregoing description, the notation sgn(expression) designates the mathematical signum function, which is defined to return either -1, 0, or 1 depending on whether the value of the expression is negative, zero or positive.

Implementations must never violate any of the first three conditions when implementing the compareTo() method. Implementations should conform to the fourth condition whenever possibleDo not violate any of five conditions while overriding the compareTo method.

Noncompliant Code Example (Rock-Paper-Scissors)

This noncompliant code example violates the third condition in the contract.
Consider a Card that considers itself equal to any card of the same suit; otherwise it orders based on rank.program implements the classic game of rock-paper-scissors, using the compareTo() operator to determine the winner of a game:

public final class CardGameEntry implements Comparable{
  private String suit;
  private int rank;
 {
  public Card(String s, int r) {
    if (s == null)enum Roshambo {ROCK, PAPER, SCISSORS}
  private    throw new NullPointerException();
    suit = s;
    rank = r;
  }Roshambo value;

  public boolean equalsGameEntry(ObjectRoshambo ovalue) {
    if (o instanceof Card){
      Card c=(Card)o;
      return suit.equals(c.suit) || (rank == c.rank);
    }
    return falsethis.value = value;
  }

  //this method violates its contract
  public int compareTo(Object othat) {
    if (o!(that instanceof Card){
      Card c=(Card)o;
      if(suit.equals(c.suitGameEntry)) return 0;{
      return c.rank - rank;
    }
    throw new ClassCastException();
  }

  public static void main(String[] args) { }
    CardGameEntry at = new Card("Clubs", 2)(GameEntry) that;
    Cardreturn b(value == new Card("Clubs", 10);t.value) ? 0
    Card c = new: Card("Hearts", 7);
    System.out.println(a.compareTo(b)); //returns 0
    System.out.println(a.compareTo(c)); //returns a negative number
    System.out.println(b.compareTo(c)); //returns a positive number
  }
}

Compliant Solution

Do not try to inter-operate with String from the equals method. The new equals method is highlighted in this compliant solution.

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 nowvalue == Roshambo.ROCK && t.value == Roshambo.PAPER) ? -1
      : (value == Roshambo.PAPER && t.value == Roshambo.SCISSORS) ? -1
      : (value == Roshambo.SCISSORS && t.value == Roshambo.ROCK) ? -1
      : 1;
  }
}

Noncompliant Code Example

However, this game violates the required transitivity property because rock beats scissors, scissors beats paper, but rock does not beat paper.

Compliant Solution (Rock-Paper-Scissors)

This compliant solution implements the same game without using the Comparable interface:This noncompliant example violates transitivity though it follows the symmetry condition. This is because the first two statements print true while the third prints false. A practical implementation issue is intermingling of java.sql.Timestamp and java.util.Date classes. There is a disclaimer about the erratic behavior in the documentation for the Timestamp class.

public class CardGameEntry {
  private final int number;

  public Card(int number)enum Roshambo {
ROCK,    this.number = number;
  PAPER, SCISSORS}

  publicprivate 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;Roshambo value;

  public XCardGameEntry(int number, String typeRoshambo value) {
    super(number);
    this.typevalue = typevalue;
  }

  public booleanint equalsbeats(Object othat) {
    if (!(othat instanceof CardGameEntry))
    return false; {
    //normal Card, dothrow not compare type
    if (!(o instanceof XCard))
      return o.equals(thisnew ClassCastException();
    //It is an XCard, compare type as well}
    XCardGameEntry xct = (XCardGameEntry)o that;
    return super.equals(o) && xc.type(value == type;
  }
t.value) ? 0
  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
  }
}

Compliant Solution

"There is simply no way to extend an instantiable class and add an aspect while preserving the equals contract." This implies that composition must be preferred over inheritance in this case. This is done by giving the {{XCard}} class a private {{card}} field and providing a a public {{viewCard}} method. \[[Bloch 08|AA. Java References#Bloch 08]\]

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;
  private Card card;

  public XCard(int number, String type) {
    super(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");
    System.out.println(p1.equals(p2)); //returns false
    System.out.println(p2.equals(p3)); //returns false
    System.out.println(p1.equals(p3)); //returns false : (value == Roshambo.ROCK && t.value == Roshambo.PAPER) ? -1
      : (value == Roshambo.PAPER && t.value == Roshambo.SCISSORS) ? -1
      : (value == Roshambo.SCISSORS && t.value == Roshambo.ROCK) ? -1
      : 1;
  }
}

TODO: Add condition for hashcode

Risk Assessment

Violating the general contract when overriding implementing the equalscompareTo() method can lead to cause unexpected results, possibly leading to invalid comparisons and information disclosure.

Automated Detection

TODO

Related Vulnerabilities

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

References

\[[API 06|AA. Java References#API 06]\] [method equals()|http://java.sun.com/j2se/1.4.2/docs/api/java/lang/Object.html#equals(java.lang.Object)]
\[[Bloch 08|AA. Java References#Bloch 08]\] Item 8: Obey the general contract when overriding equals
\[[Darwin 04|AA. Java References#Darwin 04]\] 9.2 Overriding the equals method

is infeasible in the general case.

Related Guidelines

Bibliography

...

Image Added Image Added Image AddedMET03-J. For methods that return an array or collection prefer returning an empty array or collection over a null value      09. Methods (MET)      MET31-J. Ensure that hashCode() is overridden when equals() is overridden