From 8aa0c73294dbf6a8aa77a29839b50e8a6368f34c Mon Sep 17 00:00:00 2001
From: Akira Ajisaka <aajisaka@apache.org>
Date: Thu, 26 Feb 2015 15:05:17 -0800
Subject: [PATCH] MAPREDUCE-5612. Add javadoc for TaskCompletionEvent.Status.
 Contributed by Chris Palmer.

(cherry picked from commit bfbf076b7dcb71b59d85b05d0a6da88195ea9902)
---
 hadoop-mapreduce-project/CHANGES.txt          |  3 ++
 .../hadoop/mapred/TaskCompletionEvent.java    | 32 ++++++++++++++++++-
 .../hadoop/mapreduce/TaskCompletionEvent.java | 32 ++++++++++++++++++-
 3 files changed, 65 insertions(+), 2 deletions(-)

diff --git a/hadoop-mapreduce-project/CHANGES.txt b/hadoop-mapreduce-project/CHANGES.txt
index 14018b6184e..c51bd23e004 100644
--- a/hadoop-mapreduce-project/CHANGES.txt
+++ b/hadoop-mapreduce-project/CHANGES.txt
@@ -66,6 +66,9 @@ Release 2.7.0 - UNRELEASED
     MAPREDUCE-6264. Remove httpclient dependency from hadoop-mapreduce-client.
     (Brahma Reddy Battula via aajisaka)
 
+    MAPREDUCE-5612. Add javadoc for TaskCompletionEvent.Status.
+    (Chris Palmer via aajisaka)
+
   OPTIMIZATIONS
 
     MAPREDUCE-6169. MergeQueue should release reference to the current item 
diff --git a/hadoop-mapreduce-project/hadoop-mapreduce-client/hadoop-mapreduce-client-core/src/main/java/org/apache/hadoop/mapred/TaskCompletionEvent.java b/hadoop-mapreduce-project/hadoop-mapreduce-client/hadoop-mapreduce-client-core/src/main/java/org/apache/hadoop/mapred/TaskCompletionEvent.java
index dc4d82e116c..2bb55a2b694 100644
--- a/hadoop-mapreduce-project/hadoop-mapreduce-client/hadoop-mapreduce-client-core/src/main/java/org/apache/hadoop/mapred/TaskCompletionEvent.java
+++ b/hadoop-mapreduce-project/hadoop-mapreduce-client/hadoop-mapreduce-client-core/src/main/java/org/apache/hadoop/mapred/TaskCompletionEvent.java
@@ -32,7 +32,37 @@ public class TaskCompletionEvent
     extends org.apache.hadoop.mapreduce.TaskCompletionEvent {
   @InterfaceAudience.Public
   @InterfaceStability.Stable
-  static public enum Status {FAILED, KILLED, SUCCEEDED, OBSOLETE, TIPFAILED};
+  /**
+   *  Task Completion Statuses
+   */
+  static public enum Status {
+    /**
+     * Task Event Attempt failed but there are attempts remaining.
+     */
+    FAILED,
+    /**
+     * Task Event was killed.
+     */
+    KILLED,
+    /**
+     * Task Event was successful.
+     */
+    SUCCEEDED,
+    /**
+     * Used to Override a previously successful event status.
+     * Example:  Map attempt runs and a SUCCEEDED event is sent. Later a task
+     * is retroactively failed due to excessive fetch failure during shuffle
+     * phase. When the retroactive attempt failure occurs, an OBSOLETE event is
+     * sent for the map attempt indicating the prior event is no longer valid.
+     */
+    OBSOLETE,
+    /**
+     * Task Event attempt failed and no further attempts exist.
+     * reached MAX attempts. When a reducer receives a TIPFAILED event it
+     * gives up trying to shuffle data from that map task.
+     */
+    TIPFAILED
+  }
   
   public static final TaskCompletionEvent[] EMPTY_ARRAY = 
 	    new TaskCompletionEvent[0];
diff --git a/hadoop-mapreduce-project/hadoop-mapreduce-client/hadoop-mapreduce-client-core/src/main/java/org/apache/hadoop/mapreduce/TaskCompletionEvent.java b/hadoop-mapreduce-project/hadoop-mapreduce-client/hadoop-mapreduce-client-core/src/main/java/org/apache/hadoop/mapreduce/TaskCompletionEvent.java
index 31643a94ac2..21c3823012f 100644
--- a/hadoop-mapreduce-project/hadoop-mapreduce-client/hadoop-mapreduce-client-core/src/main/java/org/apache/hadoop/mapreduce/TaskCompletionEvent.java
+++ b/hadoop-mapreduce-project/hadoop-mapreduce-client/hadoop-mapreduce-client-core/src/main/java/org/apache/hadoop/mapreduce/TaskCompletionEvent.java
@@ -36,7 +36,37 @@ import org.apache.hadoop.io.WritableUtils;
 public class TaskCompletionEvent implements Writable{
   @InterfaceAudience.Public
   @InterfaceStability.Evolving
-  static public enum Status {FAILED, KILLED, SUCCEEDED, OBSOLETE, TIPFAILED};
+  /**
+   * Task Completion Statuses
+   */
+  static public enum Status {
+    /**
+     * Task Event Attempt failed but there are attempts remaining.
+     */
+    FAILED,
+    /**
+     * Task Event was killed.
+     */
+    KILLED,
+    /**
+     * Task Event was successful.
+     */
+    SUCCEEDED,
+    /**
+     * Used to Override a previously successful event status.
+     * Example:  Map attempt runs and a SUCCEEDED event is sent. Later a task
+     * is retroactively failed due to excessive fetch failure during shuffle
+     * phase. When the retroactive attempt failure occurs, an OBSOLETE event is
+     * sent for the map attempt indicating the prior event is no longer valid.
+     */
+    OBSOLETE,
+    /**
+     * Task Event attempt failed and no further attempts exist.
+     * reached MAX attempts. When a reducer receives a TIPFAILED event it
+     * gives up trying to shuffle data from that map task.
+     */
+    TIPFAILED
+  }
     
   private int eventId; 
   private String taskTrackerHttp;