This interface imposes a total ordering on the objects of each class thatimplements it. This ordering is referred to as the class'snaturalordering, and the class'scompareTo method is referred to asitsnatural comparison method.

Lists (and arrays) of objects that implement this interface can be sortedautomatically byCollections.sort (andArrays.sort). Objects that implement thisinterface can be used as keys in asorted map or aselements in asorted set, without the need tospecify acomparator.

The natural ordering for a classC is said to beconsistentwith equals if and only ife1.compareTo(e2) == 0 hasthe same boolean value ase1.equals(e2) for everye1 ande2 of classC. Note thatnullis not an instance of any class, ande.compareTo(null) shouldthrow aNullPointerException even thoughe.equals(null)returnsfalse.

It is strongly recommended (though not required) that natural orderings beconsistent with equals. This is so because sorted sets (and sorted maps)without explicit comparators behave "strangely" when they are used withelements (or keys) whose natural ordering is inconsistent with equals. Inparticular, such a sorted set (or sorted map) violates the general contractfor set (or map), which is defined in terms of theequalsmethod.

For example, if one adds two keysa andb such that(!a.equals(b) && a.compareTo(b) == 0) to a sortedset that does not use an explicit comparator, the secondaddoperation returns false (and the size of the sorted set does not increase)becausea andb are equivalent from the sorted set'sperspective.

Virtually all Java core classes that implementComparablehave natural orderings that are consistent with equals. Oneexception isBigDecimal, whosenatural ordering equatesBigDecimal objects with equal numerical values and differentrepresentations (such as 4.0 and 4.00). ForBigDecimal.equals() to return true,the representation and numerical value of the twoBigDecimal objects must be the same.

For the mathematically inclined, therelation that definesthe natural ordering on a given class C is:

      {(x, y) such that x.compareTo(y) <= 0}.

Thequotient for this total order is:

      {(x, y) such that x.compareTo(y) == 0}.

It follows immediately from the contract forcompareTo that thequotient is anequivalence relation onC, and that thenatural ordering is atotal order onC. When we say that aclass's natural ordering isconsistent with equals, we mean that thequotient for the natural ordering is the equivalence relation defined bythe class'sequals(Object) method:

    {(x, y) such that x.equals(y)}.

In other words, when a class's natural ordering is consistent withequals, the equivalence classes defined by the equivalence relationof theequals method and the equivalence classes defined bythe quotient of thecompareTo method are the same.

This interface is a member of theJava Collections Framework.