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
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 implementor must ensure
sgn(x.compareTo(y)) == -sgn(y.compareTo(x))for all
y. (This implies that
x.compareTo(y)must throw an exception if
y.compareTo(x)throws an exception.)
- The implementor must also ensure that the relation is transitive:
(x.compareTo(y) > 0 && y.compareTo(z) > 0)implies
x.compareTo(z) > 0.
- Finally, the implementor must ensure that
x.compareTo(y) == 0implies that
sgn(x.compareTo(z)) == sgn(y.compareTo(z))for all
- 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 possible.
Noncompliant Code Example (Rock-Paper-Scissors)
This program implements the classic game of rock-paper-scissors, using the
compareTo() operator to determine the winner of a game:
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
Violating the general contract when implementing the
compareTo() method can cause unexpected results, possibly leading to invalid comparisons and information disclosure.
Automated detections of violations of this rule is infeasible in the general case.
CWE-573, Improper Following of Specification by Caller