Page History

Choosing to implement the Comparable interface represents a commitment that the implementation of the compareTo() method adheres to the general usage 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.unmigrated-wiki-markup

The general usage contract for {{compareTo()}} from Java SE 6 8 API \ [[API 2006|AA. Bibliography#API 06] (numbering added) states API 2014] states that

1. The implementor must ensure sgn(x.compareTo(y)) == -sgn(y.compareTo(x)) for all x and y. (This implies that x.compareTo(y) must throw an exception if y.compareTo(x) throws an exception.)
2. The implementor must also ensure that the relation is transitive: (x.compareTo(y) > 0 && y.compareTo(z) > 0) implies x.compareTo(z) > 0.
3. Finally, the implementor must ensure that x.compareTo(y) == 0 implies that sgn(x.compareTo(z)) == sgn(y.compareTo(z)) for all z.
4. 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.

...

This program implements the classic game of rock-paper-scissors, using the compareTo() operator to determine the winner of a game.:

class GameEntry implements Comparable {
  public enum Roshambo {ROCK, PAPER, SCISSORS}
  private Roshambo value;

  public GameEntry(Roshambo value) {
    this.value = value;
  }

  public int compareTo(Object that) {
    if (!(that instanceof RoshamboGameEntry)) {
      throw new ClassCastException();
    }
    GameEntry t = (GameEntry) that;
    return (value == t.value) ? 0
      : (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;
  }
}

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

Compliant Solution (Rock-Paper-Scissors)

This compliant solution implements the same game without using the Comparable interface.:

class GameEntry {
  public enum Roshambo {ROCK, PAPER, SCISSORS}
  private Roshambo value;

  public GameEntry(Roshambo value) {
    this.value = value;
  }

  public int beats(Object that) {
    if (!(that instanceof RoshamboGameEntry)) {
      throw new ClassCastException();
    }
    GameEntry t = (GameEntry) that;
    return (value == t.value) ? 0
      : (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;
  }
}

...

Violating the general contract when implementing the compareTo() method can result in cause unexpected results, possibly leading to invalid comparisons and information disclosure.

Automated Detection

Automated detections of violations of this rule is infeasible in the general case.

Related Guidelines

Bibliography

Bibliography

...

Image Added Image Added MET09-J. Classes that define an equals() method must also define a hashCode() method      05. Methods (MET)      Image Modified