From 4073053b3ae2211ce16c41b6c4b36f1009b1476d Mon Sep 17 00:00:00 2001 From: Eric Zhao Date: Mon, 11 Mar 2019 18:07:29 +0800 Subject: [PATCH] Update javadoc for core classes Signed-off-by: Eric Zhao --- .../csp/sentinel/context/ContextUtil.java | 50 +++++++++---------- .../csp/sentinel/node/ClusterNode.java | 12 +++-- .../csp/sentinel/node/DefaultNode.java | 6 +-- .../clusterbuilder/ClusterBuilderSlot.java | 7 ++- 4 files changed, 38 insertions(+), 37 deletions(-) diff --git a/sentinel-core/src/main/java/com/alibaba/csp/sentinel/context/ContextUtil.java b/sentinel-core/src/main/java/com/alibaba/csp/sentinel/context/ContextUtil.java index 3da93330..9af5f762 100755 --- a/sentinel-core/src/main/java/com/alibaba/csp/sentinel/context/ContextUtil.java +++ b/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 contextHolder = new ThreadLocal(); + private static ThreadLocal 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 contextNameNodeMap = new HashMap(); + private static volatile Map contextNameNodeMap = new HashMap<>(); private static final ReentrantLock LOCK = new ReentrantLock(); private static final Context NULL_CONTEXT = new NullContext(); @@ -82,33 +82,34 @@ public class ContextUtil { /** *

- * 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. *

*

- * 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. *

*

- * 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:
- * {@code distinct context name count * distinct origin count}
- * 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:
+ * {@code distinct resource name amount * distinct origin count}.
+ * So when there are too many origins, memory footprint should be carefully considered. *

*

* Same resource in different context will count separately, see {@link NodeSelectorSlot}. *

* - * @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 @@ public class ContextUtil { // Add entrance node. Constants.ROOT.addChild(node); - Map newMap = new HashMap( - contextNameNodeMap.size() + 1); + Map newMap = new HashMap<>(contextNameNodeMap.size() + 1); newMap.putAll(contextNameNodeMap); newMap.put(name, node); contextNameNodeMap = newMap; @@ -172,22 +172,22 @@ public class ContextUtil { /** *

- * 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. *

*

- * 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. *

*

* Same resource in different context will count separately, see {@link NodeSelectorSlot}. *

* - * @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, ""); diff --git a/sentinel-core/src/main/java/com/alibaba/csp/sentinel/node/ClusterNode.java b/sentinel-core/src/main/java/com/alibaba/csp/sentinel/node/ClusterNode.java index e11ca5a6..c342697d 100755 --- a/sentinel-core/src/main/java/com/alibaba/csp/sentinel/node/ClusterNode.java +++ b/sentinel-core/src/main/java/com/alibaba/csp/sentinel/node/ClusterNode.java @@ -25,7 +25,7 @@ import com.alibaba.csp.sentinel.slots.block.BlockException; /** *

* 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}. *

*

@@ -43,9 +43,12 @@ import com.alibaba.csp.sentinel.slots.block.BlockException; 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 + *

The origin map holds the pair: (origin, originNode) for one specific resource.

+ *

+ * 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. + *

*/ private Map originCountMap = new HashMap(); @@ -69,8 +72,7 @@ public class ClusterNode extends StatisticNode { if (statisticNode == null) { // The node is absent, create a new node for the origin. statisticNode = new StatisticNode(); - HashMap newMap = new HashMap( - originCountMap.size() + 1); + HashMap newMap = new HashMap<>(originCountMap.size() + 1); newMap.putAll(originCountMap); newMap.put(origin, statisticNode); originCountMap = newMap; diff --git a/sentinel-core/src/main/java/com/alibaba/csp/sentinel/node/DefaultNode.java b/sentinel-core/src/main/java/com/alibaba/csp/sentinel/node/DefaultNode.java index 5a71fd2a..2ef5fc4c 100755 --- a/sentinel-core/src/main/java/com/alibaba/csp/sentinel/node/DefaultNode.java +++ b/sentinel-core/src/main/java/com/alibaba/csp/sentinel/node/DefaultNode.java @@ -27,12 +27,12 @@ import com.alibaba.csp.sentinel.slots.nodeselector.NodeSelectorSlot; /** *

- * 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}. *

*

- * 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}. *

* * @author qinan.qn diff --git a/sentinel-core/src/main/java/com/alibaba/csp/sentinel/slots/clusterbuilder/ClusterBuilderSlot.java b/sentinel-core/src/main/java/com/alibaba/csp/sentinel/slots/clusterbuilder/ClusterBuilderSlot.java index acbc3895..7b7010b3 100755 --- a/sentinel-core/src/main/java/com/alibaba/csp/sentinel/slots/clusterbuilder/ClusterBuilderSlot.java +++ b/sentinel-core/src/main/java/com/alibaba/csp/sentinel/slots/clusterbuilder/ClusterBuilderSlot.java @@ -40,7 +40,7 @@ import com.alibaba.csp.sentinel.slotchain.StringResourceWrapper; *

*

* One resource has only one cluster node, while one resource can have multiple - * default node. + * default nodes. *

* * @author jialiang.linjl @@ -65,8 +65,7 @@ public class ClusterBuilderSlot extends AbstractLinkedProcessorSlot * at the very beginning while concurrent map will hold the lock all the time. *

*/ - private static volatile Map clusterNodeMap - = new HashMap(); + private static volatile Map clusterNodeMap = new HashMap<>(); private static final Object lock = new Object(); @@ -81,7 +80,7 @@ public class ClusterBuilderSlot extends AbstractLinkedProcessorSlot if (clusterNode == null) { // Create the cluster node. clusterNode = Env.nodeBuilder.buildClusterNode(); - HashMap newMap = new HashMap(Math.max(clusterNodeMap.size(), 16)); + HashMap newMap = new HashMap<>(Math.max(clusterNodeMap.size(), 16)); newMap.putAll(clusterNodeMap); newMap.put(node.getId(), clusterNode);