diff --git a/hbase-common/src/main/java/org/apache/hadoop/hbase/util/EnvironmentEdgeManager.java b/hbase-common/src/main/java/org/apache/hadoop/hbase/util/EnvironmentEdgeManager.java index b9c1bf2..ff3c2a0 100644 --- a/hbase-common/src/main/java/org/apache/hadoop/hbase/util/EnvironmentEdgeManager.java +++ b/hbase-common/src/main/java/org/apache/hadoop/hbase/util/EnvironmentEdgeManager.java @@ -24,6 +24,37 @@ import org.apache.hadoop.hbase.classification.InterfaceAudience; * Manages a singleton instance of the environment edge. This class shall * implement static versions of the interface {@link EnvironmentEdge}, then * defer to the delegate on invocation. + * + * Original Motivation: + * The main purpose of the Environment Edge Manager was to have better control + * over the tests so that they behave the same when runin any system. + * (Refer: HBASE-2578 - The issue which added the {@link org.apache.hadoop.hbase.util.EnvironmentEdgeManager}). + * The idea is to have a central place where time can be assigned. That makes + * it easier to inject different implementation of time. The default environment edge is the Java + * Current Time in millis. The environment edge manager class is designed to be able + * to plug in a new implementation of time by simply injecting an implementation + * of Environment Edge interface. + + Problems with Environment Edge: + 1. One of the major problems is the side effects of injecting Edge into Environment Edge. + For example, A test could inject edge to fast forward time in order to avoid thread + sleep to save time, but it could trigger a premature waking up of another thread waiting + on a condition dependent on difference in time which could potentially affect the normal + working of the system leading to failure of tests. + 2. Every test should ensure it is setting the Environment Edge it needs for the test to + perform in an expected way. Because another test which might have run before the current test + could have injected its own custom Environment Edge which may not be applicable to this + test. This is still solvable but the problem is that the tests can run in parallel + leading to different combinations of environment edge’s being injected causing unexpected + results. + 3. Another important issue with respect to injecting time through Environment Edge is that + the milliseconds unit of time is ingrained throughout the codebase in the form of hardcoded + sleep time or timeouts that any change of time unit or making it fast or slow can potentially + trigger unexpected failures due to timeout or unintended flow of execution. + + Because of the above issues, only {@link org.apache.hadoop.hbase.util.DefaultEnvironmentEdge} + is being used whose implementation of time returns the {@link System#currentTimeMillis()}. It + is advised not to inject any other {@link org.apache.hadoop.hbase.util.EnvironmentEdge}. */ @InterfaceAudience.Private public class EnvironmentEdgeManager {