Update javadoc for core classes

Signed-off-by: Eric Zhao <[email protected]>

sentinel-core/src/main/java/com/alibaba/csp/sentinel/context/ContextUtil.java

@@ -47,12 +47,12 @@ public class ContextUtil {
     /**
      * Store the context in ThreadLocal for easy access.
      */
-    private static ThreadLocal<Context> contextHolder = new ThreadLocal<Context>();
+    private static ThreadLocal<Context> contextHolder = new ThreadLocal<>();
 
     /**
-     * Holds all {@link EntranceNode}.
+     * Holds all {@link EntranceNode}. Each {@link EntranceNode} is associated with a distinct context name.
      */
-    private static volatile Map<String, DefaultNode> contextNameNodeMap = new HashMap<String, DefaultNode>();
+    private static volatile Map<String, DefaultNode> contextNameNodeMap = new HashMap<>();
 
     private static final ReentrantLock LOCK = new ReentrantLock();
     private static final Context NULL_CONTEXT = new NullContext();
@@ -82,33 +82,34 @@ static void resetContextMap() {
 
     /**
      * <p>
-     * Enter the invocation context. The context is ThreadLocal, meaning that
-     * each thread has it's own {@link Context}. New context will be created if
-     * current thread doesn't have one.
+     * Enter the invocation context, which marks as the entrance of an invocation chain.
+     * The context is wrapped with {@code ThreadLocal}, meaning that each thread has it's own {@link Context}.
+     * New context will be created if current thread doesn't have one.
      * </p>
      * <p>
-     * A context will be related to a {@link EntranceNode}, which represents the entrance
-     * of the invocation tree. New {@link EntranceNode} will be created if
+     * A context will be bound with an {@link EntranceNode}, which represents the entrance statistic node
+     * of the invocation chain. New {@link EntranceNode} will be created if
      * current context does't have one. Note that same context name will share
      * same {@link EntranceNode} globally.
      * </p>
      * <p>
-     * Note that each distinct {@code origin} of {@code name} will lead to creating a new
-     * {@link Node}, meaning that total {@link Node} created will be of:<br/>
-     * {@code distinct context name count * distinct origin count} <br/>
-     * So when origin is too many, memory efficiency should be carefully considered.
+     * The origin node will be created in {@link com.alibaba.csp.sentinel.slots.clusterbuilder.ClusterBuilderSlot}.
+     * Note that each distinct {@code origin} of different resources will lead to creating different new
+     * {@link Node}, meaning that total amount of created origin statistic nodes will be:<br/>
+     * {@code distinct resource name amount * distinct origin count}.<br/>
+     * So when there are too many origins, memory footprint should be carefully considered.
      * </p>
      * <p>
      * Same resource in different context will count separately, see {@link NodeSelectorSlot}.
      * </p>
      *
-     * @param name   the context name.
+     * @param name   the context name
      * @param origin the origin of this invocation, usually the origin could be the Service
      *               Consumer's app name. The origin is useful when we want to control different
      *               invoker/consumer separately.
-     * @return The invocation context of the current thread.
+     * @return The invocation context of the current thread
      */
-    static public Context enter(String name, String origin) {
+    public static Context enter(String name, String origin) {
         if (Constants.CONTEXT_DEFAULT_NAME.equals(name)) {
             throw new ContextNameDefineException(
                 "The " + Constants.CONTEXT_DEFAULT_NAME + " can't be permit to defined!");
@@ -138,8 +139,7 @@ protected static Context trueEnter(String name, String origin) {
                                 // Add entrance node.
                                 Constants.ROOT.addChild(node);
 
-                                Map<String, DefaultNode> newMap = new HashMap<String, DefaultNode>(
-                                    contextNameNodeMap.size() + 1);
+                                Map<String, DefaultNode> newMap = new HashMap<>(contextNameNodeMap.size() + 1);
                                 newMap.putAll(contextNameNodeMap);
                                 newMap.put(name, node);
                                 contextNameNodeMap = newMap;
@@ -172,22 +172,22 @@ private static void setNullContext() {
 
     /**
      * <p>
-     * Enter the invocation context. The context is ThreadLocal, meaning that
-     * each thread has it's own {@link Context}. New context will be created if
-     * current thread doesn't have one.
+     * Enter the invocation context, which marks as the entrance of an invocation chain.
+     * The context is wrapped with {@code ThreadLocal}, meaning that each thread has it's own {@link Context}.
+     * New context will be created if current thread doesn't have one.
      * </p>
      * <p>
-     * A context will related to A {@link EntranceNode}, which is the entrance
-     * of the invocation tree. New {@link EntranceNode} will be created if
-     * current context does't have one. Note that same resource name will share
+     * A context will be bound with an {@link EntranceNode}, which represents the entrance statistic node
+     * of the invocation chain. New {@link EntranceNode} will be created if
+     * current context does't have one. Note that same context name will share
      * same {@link EntranceNode} globally.
      * </p>
      * <p>
      * Same resource in different context will count separately, see {@link NodeSelectorSlot}.
      * </p>
      *
-     * @param name the context name.
-     * @return The invocation context of the current thread.
+     * @param name the context name
+     * @return The invocation context of the current thread
      */
     public static Context enter(String name) {
         return enter(name, "");

sentinel-core/src/main/java/com/alibaba/csp/sentinel/node/ClusterNode.java

@@ -25,7 +25,7 @@
 /**
  * <p>
  * This class stores summary runtime statistics of the resource, including rt, thread count, qps
- * and so on. Same resource shares the same {@link ClusterNode} globally, no matter in witch
+ * and so on. Same resource shares the same {@link ClusterNode} globally, no matter in which
  * {@link com.alibaba.csp.sentinel.context.Context}.
  * </p>
  * <p>
@@ -43,9 +43,12 @@
 public class ClusterNode extends StatisticNode {
 
     /**
-     * The longer the application runs, the more stable this mapping will
-     * become. so we don't concurrent map but a lock. as this lock only happens
+     * <p>The origin map holds the pair: (origin, originNode) for one specific resource.</p>
+     * <p>
+     * The longer the application runs, the more stable this mapping will become.
+     * So we didn't use concurrent map here, but a lock, as this lock only happens
      * at the very beginning while concurrent map will hold the lock all the time.
+     * </p>
      */
     private Map<String, StatisticNode> originCountMap = new HashMap<String, StatisticNode>();
 
@@ -69,8 +72,7 @@ public Node getOrCreateOriginNode(String origin) {
                 if (statisticNode == null) {
                     // The node is absent, create a new node for the origin.
                     statisticNode = new StatisticNode();
-                    HashMap<String, StatisticNode> newMap = new HashMap<String, StatisticNode>(
-                        originCountMap.size() + 1);
+                    HashMap<String, StatisticNode> newMap = new HashMap<>(originCountMap.size() + 1);
                     newMap.putAll(originCountMap);
                     newMap.put(origin, statisticNode);
                     originCountMap = newMap;

sentinel-core/src/main/java/com/alibaba/csp/sentinel/node/DefaultNode.java

@@ -27,12 +27,12 @@
 
 /**
  * <p>
- * A {@link Node} use to hold statistics for specific resource name in the specific context.
+ * A {@link Node} used to hold statistics for specific resource name in the specific context.
  * Each distinct resource in each distinct {@link Context} will corresponding to a {@link DefaultNode}.
  * </p>
  * <p>
- * This class may have a list of sub {@link DefaultNode}s. sub-node will be created when
- * call {@link SphU}#entry() or {@link SphO}@entry() multi times in the same {@link Context}.
+ * This class may have a list of sub {@link DefaultNode}s. Child nodes will be created when
+ * calling {@link SphU}#entry() or {@link SphO}@entry() multiple times in the same {@link Context}.
  * </p>
  *
  * @author qinan.qn

sentinel-core/src/main/java/com/alibaba/csp/sentinel/slots/clusterbuilder/ClusterBuilderSlot.java

@@ -40,7 +40,7 @@
  * </p>
  * <p>
  * One resource has only one cluster node, while one resource can have multiple
- * default node.
+ * default nodes.
  * </p>
  *
  * @author jialiang.linjl
@@ -65,8 +65,7 @@ public class ClusterBuilderSlot extends AbstractLinkedProcessorSlot<DefaultNode>
      * at the very beginning while concurrent map will hold the lock all the time.
      * </p>
      */
-    private static volatile Map<ResourceWrapper, ClusterNode> clusterNodeMap
-        = new HashMap<ResourceWrapper, ClusterNode>();
+    private static volatile Map<ResourceWrapper, ClusterNode> clusterNodeMap = new HashMap<>();
 
     private static final Object lock = new Object();
 
@@ -81,7 +80,7 @@ public void entry(Context context, ResourceWrapper resourceWrapper, DefaultNode
                 if (clusterNode == null) {
                     // Create the cluster node.
                     clusterNode = Env.nodeBuilder.buildClusterNode();
-                    HashMap<ResourceWrapper, ClusterNode> newMap = new HashMap<ResourceWrapper, ClusterNode>(Math.max(clusterNodeMap.size(), 16));
+                    HashMap<ResourceWrapper, ClusterNode> newMap = new HashMap<>(Math.max(clusterNodeMap.size(), 16));
                     newMap.putAll(clusterNodeMap);
                     newMap.put(node.getId(), clusterNode);