HADOOP-3944. Improve documentation for public TupleWritable class in join package. Contributed by Chris Douglas.

git-svn-id: https://svn.apache.org/repos/asf/hadoop/core/trunk@689032 13f79535-47bb-0310-9956-ffa450edef68

CHANGES.txt

@@ -215,6 +215,9 @@ Trunk (unreleased changes)
     HADOOP-3742. Remove HDFS from public java doc and add javadoc-dev for
     generative javadoc for developers. (Sanjay Radia via omalley)
 
+    HADOOP-3944. Improve documentation for public TupleWritable class in 
+    join package. (Chris Douglas via enis)
+
   OPTIMIZATIONS
 
     HADOOP-3556. Removed lock contention in MD5Hash by changing the 

src/mapred/org/apache/hadoop/mapred/join/TupleWritable.java

@@ -30,6 +30,15 @@ import org.apache.hadoop.io.WritableUtils;
 
 /**
  * Writable type storing multiple {@link org.apache.hadoop.io.Writable}s.
+ *
+ * This is *not* a general-purpose tuple type. In almost all cases, users are
+ * encouraged to implement their own serializable types, which can perform
+ * better validation and provide more efficient encodings than this class is
+ * capable. TupleWritable relies on the join framework for type safety and
+ * assumes its instances will rarely be persisted, assumptions not only
+ * incompatible with, but contrary to the general case.
+ *
+ * @see org.apache.hadoop.io.Writable
  */
 public class TupleWritable implements Writable, Iterable<Writable> {
 
@@ -77,7 +86,7 @@ public class TupleWritable implements Writable, Iterable<Writable> {
   public boolean equals(Object other) {
     if (other instanceof TupleWritable) {
       TupleWritable that = (TupleWritable)other;
-      if (this.size() != that.size() || this.mask() != that.mask()) {
+      if (this.size() != that.size() || this.written != that.written) {
         return false;
       }
       for (int i = 0; i < values.length; ++i) {
@@ -215,12 +224,4 @@ public class TupleWritable implements Writable, Iterable<Writable> {
     written = 0L;
   }
 
-  /**
-   * Return a bitmap recording which of the writables that have been
-   * written to.
-   */
-  long mask() {
-    return written;
-  }
-
 }