Page History

...

This noncompliant code example violates the third condition (transitivity) in the contract. This requirement states that the objects that compareTo() considers equal (returns by returning 0) must be ordered the same with respect to other objects. For example, a card is may require to be compared against any other card to check whether both belong to the same suit or have the same rank. If neither of these conditions is true, compareTo() is expected to order the cards based on rank alone. This might situation may arise in a game like Uno or Crazy Eights, where you one can only place a card on the pile that shares a suit or rank with the top most 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); // badBad
    }
    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) )
        // checkCheck for integer underflow/overflow
        return c.rank - rank; // orderOrder 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)); // returnsReturns 0
    System.out.println(a.compareTo(c)); // returnsReturns a negative number
    System.out.println(b.compareTo(c)); // returnsReturns a positive number
  }
}

Here, the comparison between (a,c) yields that c is larger. However, the comparison (b,c) yields b as larger. This means b must be larger than a. However, comparing (a,b) results in the value 0 (same) implying that both a and b compare equal.

Compliant Solution

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

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); // goodGood
    }
    return false;
  }

  // thisThis 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)); // returnsReturns 0
    System.out.println(a.compareTo(c)); // returnsReturns a negative number
    System.out.println(b.compareTo(c)); // returnsReturns a negative number
  }
}

As required by the ordering, c is larger than both a and b and the comparison (a,b) produces an equal result. This maintains the compareTo() method's contract.

Risk Assessment

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

...