Page History

One way to order objects of a class relative to one another is to 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. Library classes such as TreeSet and TreeMap accept Comparable objects and use their the associated compareTo() methods to sort themthe 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 x and y. (This implies that x.compareTo(y) must throw an exception iff 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) ==0 implies that sgn(x.compareTo(z)) == sgn(y.compareTo(z)), for all z.

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.

Do not Never violate any of the first three conditions when implementing the compareTo() method. Implementing Implementations should conform to the fourth condition is strongly recommended but is not necessarywhenever possible.

Noncompliant Code Example

This noncompliant code example violates the third condition (transitivity) in the contract. This requirement states that the objects that compareTo() considers equal (by returning 0) must be ordered the same with respect identically when compared to other objects. For example, it may be necessary to compare a card may require to be compared against with any other card to check whether both belong to the same suit or have the same rank. If When neither of these conditions is true, compareTo() is expected to order the cards based on rank alone. This situation may arise in a game like Uno or Crazy Eights, where one can only place a card on the pile that only when it shares a suit or rank with the top most topmost card on the pile.

public final class Card implements Comparable {
  private String suit;
  private int rank;

  public Card(String s, int r) {
    if (s == null) {
      throw new NullPointerException();
    }
    suit = s;
    rank = r;
  }

  public boolean equals(Object o) {
    if (o instanceof Card) {
      Card c = (Card)o;
      return suit.equals(c.suit) || (rank == c.rank); // Bad
    }
    return false;
  }

  // This method violates its contract
  public int compareTo(Object o) {
    if (o instanceof Card) {
      Card c = (Card)o;
      if(suit.equals(c.suit) ) 
        return 0;
      if((c.rank >= rank + Integer.MIN_VALUE) && 
          (c.rank <= rank + Integer.MAX_VALUE) )
        // Check for integer overflow
        return c.rank - rank; // Order based on rank
    }
    throw new ClassCastException();
  }

  public static void main(String[] args) {
    Card a = new Card("Clubs", 2);
    Card b = new Card("Clubs", 10);
    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
  }
}

Here, the comparison between (a,c) yields that comparing a with c} indicates that {{c is larger. However, the comparison (b,c) yields b as larger. This means , and comparing b with c indicates that b is larger. Consequently, b must be larger than a. However, comparing (a,b) results in the value 0 implying that both with b reports that a and b compare are equal. Therefore, the compareTo() implementation violates the general contract.

Compliant Solution

This compliant solution ensures both that the compareTo() contract is satisfied , and also that the corresponding equals() method is consistent with the compareTo() method.

public final class Card implements Comparable{
  private String suit;
  private int rank;

  public Card(String s, int r) {
    if (s == null) {
      throw new NullPointerException();
    }
    suit = s;
    rank = r;
  }

  public boolean equals(Object o) {
    if (o instanceof Card) {
      Card c=(Card)o;
      return suit.equals(c.suit) && (rank == c.rank); // Good
    }
    return false;
  }

  // This method fulfills its contract
  public int compareTo(Object o) {
    if (o instanceof Card) {
      Card c=(Card)o;
      if(suit.equals(c.suit) &&
          (c.rank >= rank + Integer.MIN_VALUE) &&
          (c.rank <= rank + Integer.MAX_VALUE) ) 
        return c.rank - rank;
      return suit.compareTo(c.suit);
    }
    throw new ClassCastException();
  }

  public static void main(String[] args) {
    Card a = new Card("Clubs", 2);
    Card b = new Card("Clubs", 10);
    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 negative number
  }
}

...