svn commit: r1074241 - in /hadoop/common/trunk: CHANGES.txt src/java/org/apache/hadoop/io/WritableComparable.java

[todd]

Author: todd
Date: Thu Feb 24 18:05:46 2011
New Revision: 1074241

URL: http://svn.apache.org/viewvc?rev=1074241&view=rev
Log:
HADOOP-7151. Document need for stable hashCode() in WritableComparable. 
Contributed by Dmitriy V. Ryaboy.

Modified:
    hadoop/common/trunk/CHANGES.txt
    hadoop/common/trunk/src/java/org/apache/hadoop/io/WritableComparable.java

Modified: hadoop/common/trunk/CHANGES.txt
URL: 
http://svn.apache.org/viewvc/hadoop/common/trunk/CHANGES.txt?rev=1074241&r1=1074240&r2=1074241&view=diff
==============================================================================
--- hadoop/common/trunk/CHANGES.txt (original)
+++ hadoop/common/trunk/CHANGES.txt Thu Feb 24 18:05:46 2011
@@ -57,6 +57,9 @@ Trunk (unreleased changes)
     HADOOP-6376. Add a comment header to conf/slaves that specifies the file
     format. (Kay Kay via todd)
 
+    HADOOP-7151. Document need for stable hashCode() in WritableComparable.
+    (Dmitriy V. Ryaboy via todd)
+
   OPTIMIZATIONS
 
   BUG FIXES

Modified: 
hadoop/common/trunk/src/java/org/apache/hadoop/io/WritableComparable.java
URL: 
http://svn.apache.org/viewvc/hadoop/common/trunk/src/java/org/apache/hadoop/io/WritableComparable.java?rev=1074241&r1=1074240&r2=1074241&view=diff
==============================================================================
--- hadoop/common/trunk/src/java/org/apache/hadoop/io/WritableComparable.java 
(original)
+++ hadoop/common/trunk/src/java/org/apache/hadoop/io/WritableComparable.java 
Thu Feb 24 18:05:46 2011
@@ -28,12 +28,16 @@ import org.apache.hadoop.classification.
  * via <code>Comparator</code>s. Any type which is to be used as a 
  * <code>key</code> in the Hadoop Map-Reduce framework should implement this
  * interface.</p>
+ *
+ * <p>Note that <code>hashCode()</code> is frequently used in Hadoop to 
partition
+ * keys. It's important that your implementation of hashCode() returns the 
same 
+ * result across different instances of the JVM. Note also that the default 
+ * <code>hashCode()</code> implementation in <code>Object</code> does 
<b>not</b>
+ * satisfy this property.</p>
  *  
  * <p>Example:</p>
  * <p><blockquote><pre>
- *     public class MyWritableComparable implements
- *         WritableComparable&lt;MyWritableComparable&gt; {
- *
+ *     public class MyWritableComparable implements WritableComparable {
  *       // Some data
  *       private int counter;
  *       private long timestamp;
@@ -48,10 +52,18 @@ import org.apache.hadoop.classification.
  *         timestamp = in.readLong();
  *       }
  *       
- *       public int compareTo(MyWritableComparable other) {
- *         int thisValue = this.counter;
- *         int thatValue = other.counter;
- *         return (thisValue &lt; thatValue ? -1 : (thisValue == thatValue ? 0 
: 1));
+ *       public int compareTo(MyWritableComparable w) {
+ *         int thisValue = this.value;
+ *         int thatValue = ((IntWritable)o).value;
+ *         return (thisValue &lt; thatValue ? -1 : (thisValue==thatValue ? 0 : 
1));
+ *       }
+ *
+ *       public int hashCode() {
+ *         final int prime = 31;
+ *         int result = 1;
+ *         result = prime * result + counter;
+ *         result = prime * result + (int) (timestamp ^ (timestamp 
&gt;&gt;&gt; 32));
+ *         return result
  *       }
  *     }
  * </pre></blockquote></p>