KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > hammurapi > inspectors > metrics > statistics > IntComparator


1
2 /*
3 Copyright © 1999 CERN - European Organization for Nuclear Research.
4 Permission to use, copy, modify, distribute and sell this software and its documentation for any purpose
5 is hereby granted without fee, provided that the above copyright notice appear in all copies and
6 that both that copyright notice and this permission notice appear in supporting documentation.
7 CERN makes no representations about the suitability of this software for any purpose.
8 It is provided "as is" without expressed or implied warranty.
9 */
10
11 package org.hammurapi.inspectors.metrics.statistics;
12
13 /**
14  * A comparison function which imposes a <i>total ordering</i> on some
15  * collection of elements. Comparators can be passed to a sort method (such as
16  * <tt>cern.colt.Sorting.quickSort</tt>) to allow precise control over the sort order.<p>
17  *
18  * Note: It is generally a good idea for comparators to implement
19  * <tt>java.io.Serializable</tt>, as they may be used as ordering methods in
20  * serializable data structures. In
21  * order for the data structure to serialize successfully, the comparator (if
22  * provided) must implement <tt>Serializable</tt>.<p>
23  *
24  * @author wolfgang.hoschek@cern.ch
25  * @version 0.1 01/09/99
26  * @see java.util.Comparator
27  * @see cern.colt.Sorting
28  */
29 public interface IntComparator {
30 /**
31  * Compares its two arguments for order. Returns a negative integer,
32  * zero, or a positive integer as the first argument is less than, equal
33  * to, or greater than the second.<p>
34  *
35  * The implementor must ensure that <tt>sgn(compare(x, y)) ==
36  * -sgn(compare(y, x))</tt> for all <tt>x</tt> and <tt>y</tt>. (This
37  * implies that <tt>compare(x, y)</tt> must throw an exception if and only
38  * if <tt>compare(y, x)</tt> throws an exception.)<p>
39  *
40  * The implementor must also ensure that the relation is transitive:
41  * <tt>((compare(x, y)&gt;0) &amp;&amp; (compare(y, z)&gt;0))</tt> implies
42  * <tt>compare(x, z)&gt;0</tt>.<p>
43  *
44  * Finally, the implementer must ensure that <tt>compare(x, y)==0</tt>
45  * implies that <tt>sgn(compare(x, z))==sgn(compare(y, z))</tt> for all
46  * <tt>z</tt>.<p>
47  *
48  *
49  * @return a negative integer, zero, or a positive integer as the
50  * first argument is less than, equal to, or greater than the
51  * second.
52  */
53 int compare(int o1, int o2);
54 /**
55  *
56  * Indicates whether some other object is &quot;equal to&quot; this
57  * Comparator. This method must obey the general contract of
58  * <tt>Object.equals(Object)</tt>. Additionally, this method can return
59  * <tt>true</tt> <i>only</i> if the specified Object is also a comparator
60  * and it imposes the same ordering as this comparator. Thus,
61  * <code>comp1.equals(comp2)</code> implies that <tt>sgn(comp1.compare(o1,
62  * o2))==sgn(comp2.compare(o1, o2))</tt> for every element
63  * <tt>o1</tt> and <tt>o2</tt>.<p>
64  *
65  * Note that it is <i>always</i> safe <i>not</i> to override
66  * <tt>Object.equals(Object)</tt>. However, overriding this method may,
67  * in some cases, improve performance by allowing programs to determine
68  * that two distinct Comparators impose the same order.
69  *
70  * @param obj the reference object with which to compare.
71  * @return <code>true</code> only if the specified object is also
72  * a comparator and it imposes the same ordering as this
73  * comparator.
74  * @see java.lang.Object#equals(java.lang.Object)
75  * @see java.lang.Object#hashCode()
76  */
77 boolean equals(Object JavaDoc obj);
78 }
79
Popular Tags