HADOOP-3522. Merge -r 668866:668867 from trunk to branch 0.17.

git-svn-id: https://svn.apache.org/repos/asf/hadoop/core/branches/branch-0.17@668872 13f79535-47bb-0310-9956-ffa450edef68

CHANGES.txt

@@ -28,6 +28,11 @@ Release 0.17.1 - Unreleased
     default, to clear the state of the serializer between objects.
     (tomwhite via omalley)
 
+  IMPROVEMENTS
+
+    HADOOP-3522. Improve documentation on reduce pointing out that
+    input keys and values will be reused. (omalley)
+
 Release 0.17.0 - 2008-05-18
 
   INCOMPATIBLE CHANGES

src/java/org/apache/hadoop/mapred/Reducer.java

@@ -169,7 +169,10 @@ public interface Reducer<K2, V2, K3, V3> extends JobConfigurable, Closeable {
    * <p>The framework calls this method for each 
    * <code>&lt;key, (list of values)></code> pair in the grouped inputs.
    * Output values must be of the same type as input values.  Input keys must 
-   * not be altered.  Typically all values are combined into zero or one value.
+   * not be altered. The framework will <b>reuse</b> the key and value objects
+   * that are passed into the reduce, therefore the application should clone
+   * the objects they want to keep a copy of. In many cases, all values are 
+   * combined into zero or one value.
    * </p>
    *   
    * <p>Output pairs are collected with calls to