From 99d435531864de16a2e4f07dde455839b8f6fe0d Mon Sep 17 00:00:00 2001 From: Eric Zhao Date: Mon, 11 May 2020 17:45:48 +0800 Subject: [PATCH] Polish code comments of the fundamental Sph/SphO/SphU class Signed-off-by: Eric Zhao --- .../java/com/alibaba/csp/sentinel/Sph.java | 163 ++++++----- .../java/com/alibaba/csp/sentinel/SphO.java | 71 ++--- .../csp/sentinel/SphResourceTypeSupport.java | 58 ++-- .../java/com/alibaba/csp/sentinel/SphU.java | 277 +++++++++--------- 4 files changed, 299 insertions(+), 270 deletions(-) diff --git a/sentinel-core/src/main/java/com/alibaba/csp/sentinel/Sph.java b/sentinel-core/src/main/java/com/alibaba/csp/sentinel/Sph.java index 32643b46..ab34176a 100755 --- a/sentinel-core/src/main/java/com/alibaba/csp/sentinel/Sph.java +++ b/sentinel-core/src/main/java/com/alibaba/csp/sentinel/Sph.java @@ -18,11 +18,10 @@ package com.alibaba.csp.sentinel; import java.lang.reflect.Method; import com.alibaba.csp.sentinel.slots.block.BlockException; +import com.alibaba.csp.sentinel.slots.system.SystemRule; /** - * Interface to get {@link Entry} for resource protection. If any block criteria is met, - * a {@link BlockException} or its subclasses will be thrown. Successfully getting a entry - * indicates permitting the invocation pass. + * The basic interface for recording statistics and performing rule checking for resources. * * @author qinan.qn * @author jialiang.linjl @@ -32,158 +31,166 @@ import com.alibaba.csp.sentinel.slots.block.BlockException; public interface Sph extends SphResourceTypeSupport { /** - * Create a protected resource. + * Record statistics and perform rule checking for the given resource. * * @param name the unique name of the protected resource - * @return entry get. + * @return the {@link Entry} of this invocation (used for mark the invocation complete and get context data). * @throws BlockException if the block criteria is met */ Entry entry(String name) throws BlockException; /** - * Create a protected method. + * Record statistics and perform rule checking for the given method. * * @param method the protected method - * @return entry get. + * @return the {@link Entry} of this invocation (used for mark the invocation complete and get context data). * @throws BlockException if the block criteria is met */ Entry entry(Method method) throws BlockException; /** - * Create a protected method. + * Record statistics and perform rule checking for the given method. * - * @param method the protected method - * @param count the count that the resource requires - * @return entry get. + * @param method the protected method + * @param batchCount the amount of calls within the invocation (e.g. batchCount=2 means request for 2 tokens) + * @return the {@link Entry} of this invocation (used for mark the invocation complete and get context data). * @throws BlockException if the block criteria is met */ - Entry entry(Method method, int count) throws BlockException; + Entry entry(Method method, int batchCount) throws BlockException; /** - * Create a protected resource. + * Record statistics and perform rule checking for the given resource. * - * @param name the unique string for the resource - * @param count the count that the resource requires - * @return entry get. + * @param name the unique string for the resource + * @param batchCount the amount of calls within the invocation (e.g. batchCount=2 means request for 2 tokens) + * @return the {@link Entry} of this invocation (used for mark the invocation complete and get context data). * @throws BlockException if the block criteria is met */ - Entry entry(String name, int count) throws BlockException; + Entry entry(String name, int batchCount) throws BlockException; /** - * Create a protected method. + * Record statistics and perform rule checking for the given method. * - * @param method the protected method - * @param type the resource is an inbound or an outbound method. This is used - * to mark whether it can be blocked when the system is unstable - * @return entry get. + * @param method the protected method + * @param trafficType the traffic type (inbound, outbound or internal). This is used + * to mark whether it can be blocked when the system is unstable, + * only inbound traffic could be blocked by {@link SystemRule} + * @return the {@link Entry} of this invocation (used for mark the invocation complete and get context data). * @throws BlockException if the block criteria is met */ - Entry entry(Method method, EntryType type) throws BlockException; + Entry entry(Method method, EntryType trafficType) throws BlockException; /** - * Create a protected resource. + * Record statistics and perform rule checking for the given resource. * - * @param name the unique name for the protected resource - * @param type the resource is an inbound or an outbound method. This is used - * to mark whether it can be blocked when the system is unstable - * @return entry get. + * @param name the unique name for the protected resource + * @param trafficType the traffic type (inbound, outbound or internal). This is used + * to mark whether it can be blocked when the system is unstable, + * only inbound traffic could be blocked by {@link SystemRule} + * @return the {@link Entry} of this invocation (used for mark the invocation complete and get context data). * @throws BlockException if the block criteria is met */ - Entry entry(String name, EntryType type) throws BlockException; + Entry entry(String name, EntryType trafficType) throws BlockException; /** - * Create a protected method. + * Record statistics and perform rule checking for the given method. * - * @param method the protected method - * @param type the resource is an inbound or an outbound method. This is used - * to mark whether it can be blocked when the system is unstable - * @param count the count that the resource requires - * @return entry get. + * @param method the protected method + * @param trafficType the traffic type (inbound, outbound or internal). This is used + * to mark whether it can be blocked when the system is unstable, + * only inbound traffic could be blocked by {@link SystemRule} + * @param batchCount the amount of calls within the invocation (e.g. batchCount=2 means request for 2 tokens) + * @return the {@link Entry} of this invocation (used for mark the invocation complete and get context data). * @throws BlockException if the block criteria is met */ - Entry entry(Method method, EntryType type, int count) throws BlockException; + Entry entry(Method method, EntryType trafficType, int batchCount) throws BlockException; /** - * Create a protected resource. + * Record statistics and perform rule checking for the given resource. * - * @param name the unique name for the protected resource - * @param type the resource is an inbound or an outbound method. This is used - * to mark whether it can be blocked when the system is unstable - * @param count the count that the resource requires - * @return entry get. + * @param name the unique name for the protected resource + * @param trafficType the traffic type (inbound, outbound or internal). This is used + * to mark whether it can be blocked when the system is unstable, + * only inbound traffic could be blocked by {@link SystemRule} + * @param batchCount the amount of calls within the invocation (e.g. batchCount=2 means request for 2 tokens) + * @return the {@link Entry} of this invocation (used for mark the invocation complete and get context data). * @throws BlockException if the block criteria is met */ - Entry entry(String name, EntryType type, int count) throws BlockException; + Entry entry(String name, EntryType trafficType, int batchCount) throws BlockException; /** - * Create a protected resource. + * Record statistics and perform rule checking for the given resource. * - * @param method the protected method - * @param type the resource is an inbound or an outbound method. This is used - * to mark whether it can be blocked when the system is unstable - * @param count the count that the resource requires - * @param args the parameters of the method. It can also be counted by setting - * hot parameter rule - * @return entry get. + * @param method the protected method + * @param trafficType the traffic type (inbound, outbound or internal). This is used + * to mark whether it can be blocked when the system is unstable, + * only inbound traffic could be blocked by {@link SystemRule} + * @param batchCount the amount of calls within the invocation (e.g. batchCount=2 means request for 2 tokens) + * @param args parameters of the method for flow control or customized slots + * @return the {@link Entry} of this invocation (used for mark the invocation complete and get context data). * @throws BlockException if the block criteria is met */ - Entry entry(Method method, EntryType type, int count, Object... args) throws BlockException; + Entry entry(Method method, EntryType trafficType, int batchCount, Object... args) throws BlockException; /** - * Create a protected resource. + * Record statistics and perform rule checking for the given resource. * - * @param name the unique name for the protected resource - * @param type the resource is an inbound or an outbound method. This is used - * to mark whether it can be blocked when the system is unstable - * @param count the count that the resource requires - * @param args the parameters of the method. It can also be counted by setting hot parameter rule - * @return entry get + * @param name the unique name for the protected resource + * @param trafficType the traffic type (inbound, outbound or internal). This is used + * to mark whether it can be blocked when the system is unstable, + * only inbound traffic could be blocked by {@link SystemRule} + * @param batchCount the amount of calls within the invocation (e.g. batchCount=2 means request for 2 tokens) + * @param args args for parameter flow control or customized slots + * @return the {@link Entry} of this invocation (used for mark the invocation complete and get context data) * @throws BlockException if the block criteria is met */ - Entry entry(String name, EntryType type, int count, Object... args) throws BlockException; + Entry entry(String name, EntryType trafficType, int batchCount, Object... args) throws BlockException; /** * Create a protected asynchronous resource. * - * @param name the unique name for the protected resource - * @param type the resource is an inbound or an outbound method. This is used - * to mark whether it can be blocked when the system is unstable - * @param count the count that the resource requires - * @param args the parameters of the method. It can also be counted by setting hot parameter rule + * @param name the unique name for the protected resource + * @param trafficType the traffic type (inbound, outbound or internal). This is used + * to mark whether it can be blocked when the system is unstable, + * only inbound traffic could be blocked by {@link SystemRule} + * @param batchCount the amount of calls within the invocation (e.g. batchCount=2 means request for 2 tokens) + * @param args args for parameter flow control or customized slots * @return created asynchronous entry * @throws BlockException if the block criteria is met * @since 0.2.0 */ - AsyncEntry asyncEntry(String name, EntryType type, int count, Object... args) throws BlockException; + AsyncEntry asyncEntry(String name, EntryType trafficType, int batchCount, Object... args) throws BlockException; /** * Create a protected resource with priority. * * @param name the unique name for the protected resource - * @param type the resource is an inbound or an outbound method. This is used - * to mark whether it can be blocked when the system is unstable - * @param count the count that the resource requires + * @param trafficType the traffic type (inbound, outbound or internal). This is used + * to mark whether it can be blocked when the system is unstable, + * only inbound traffic could be blocked by {@link SystemRule} + * @param batchCount the amount of calls within the invocation (e.g. batchCount=2 means request for 2 tokens) * @param prioritized whether the entry is prioritized - * @return entry get + * @return the {@link Entry} of this invocation (used for mark the invocation complete and get context data) * @throws BlockException if the block criteria is met * @since 1.4.0 */ - Entry entryWithPriority(String name, EntryType type, int count, boolean prioritized) throws BlockException; + Entry entryWithPriority(String name, EntryType trafficType, int batchCount, boolean prioritized) + throws BlockException; /** * Create a protected resource with priority. * * @param name the unique name for the protected resource - * @param type the resource is an inbound or an outbound method. This is used - * to mark whether it can be blocked when the system is unstable - * @param count the count that the resource requires + * @param trafficType the traffic type (inbound, outbound or internal). This is used + * to mark whether it can be blocked when the system is unstable, + * only inbound traffic could be blocked by {@link SystemRule} + * @param batchCount the amount of calls within the invocation (e.g. batchCount=2 means request for 2 tokens) * @param prioritized whether the entry is prioritized - * @param args the parameters of the method. It can also be counted by setting hot parameter - * rule - * @return entry get + * @param args args for parameter flow control or customized slots + * @return the {@link Entry} of this invocation (used for mark the invocation complete and get context data) * @throws BlockException if the block criteria is met * @since 1.5.0 */ - Entry entryWithPriority(String name, EntryType type, int count, boolean prioritized, Object... args) + Entry entryWithPriority(String name, EntryType trafficType, int batchCount, boolean prioritized, Object... args) throws BlockException; } diff --git a/sentinel-core/src/main/java/com/alibaba/csp/sentinel/SphO.java b/sentinel-core/src/main/java/com/alibaba/csp/sentinel/SphO.java index 6f6231da..76677412 100755 --- a/sentinel-core/src/main/java/com/alibaba/csp/sentinel/SphO.java +++ b/sentinel-core/src/main/java/com/alibaba/csp/sentinel/SphO.java @@ -18,8 +18,8 @@ package com.alibaba.csp.sentinel; import java.lang.reflect.Method; import java.util.List; -import com.alibaba.csp.sentinel.log.RecordLog; import com.alibaba.csp.sentinel.context.ContextUtil; +import com.alibaba.csp.sentinel.log.RecordLog; import com.alibaba.csp.sentinel.slots.block.BlockException; import com.alibaba.csp.sentinel.slots.block.Rule; import com.alibaba.csp.sentinel.slots.block.degrade.DegradeRuleManager; @@ -63,6 +63,7 @@ import com.alibaba.csp.sentinel.slots.system.SystemRuleManager; * * @author jialiang.linjl * @author leyou + * @author Eric Zhao * @see SphU */ public class SphO { @@ -70,7 +71,7 @@ public class SphO { private static final Object[] OBJECTS0 = new Object[0]; /** - * Checking all {@link Rule}s about the resource. + * Record statistics and perform rule checking for the given resource. * * @param name the unique name of the protected resource * @return true if no rule's threshold is exceeded, otherwise return false. @@ -92,23 +93,23 @@ public class SphO { /** * Checking all {@link Rule}s about the protected method. * - * @param method the protected method - * @param count tokens required + * @param method the protected method + * @param batchCount the amount of calls within the invocation (e.g. batchCount=2 means request for 2 tokens) * @return true if no rule's threshold is exceeded, otherwise return false. */ - public static boolean entry(Method method, int count) { - return entry(method, EntryType.OUT, count, OBJECTS0); + public static boolean entry(Method method, int batchCount) { + return entry(method, EntryType.OUT, batchCount, OBJECTS0); } /** - * Checking all {@link Rule}s about the resource. + * Record statistics and perform rule checking for the given resource. * - * @param name the unique string for the resource - * @param count tokens required + * @param name the unique string for the resource + * @param batchCount the amount of calls within the invocation (e.g. batchCount=2 means request for 2 tokens) * @return true if no rule's threshold is exceeded, otherwise return false. */ - public static boolean entry(String name, int count) { - return entry(name, EntryType.OUT, count, OBJECTS0); + public static boolean entry(String name, int batchCount) { + return entry(name, EntryType.OUT, batchCount, OBJECTS0); } /** @@ -125,7 +126,7 @@ public class SphO { } /** - * Checking all {@link Rule}s about the resource. + * Record statistics and perform rule checking for the given resource. * * @param name the unique name for the protected resource * @param type the resource is an inbound or an outbound method. This is used @@ -144,7 +145,7 @@ public class SphO { * @param type the resource is an inbound or an outbound method. This is used * to mark whether it can be blocked when the system is unstable, * only inbound traffic could be blocked by {@link SystemRule} - * @param count tokens required + * @param count the amount of calls within the invocation (e.g. batchCount=2 means request for 2 tokens) * @return true if no rule's threshold is exceeded, otherwise return false. */ public static boolean entry(Method method, EntryType type, int count) { @@ -152,13 +153,13 @@ public class SphO { } /** - * Checking all {@link Rule}s about the resource. + * Record statistics and perform rule checking for the given resource. * * @param name the unique name for the protected resource * @param type the resource is an inbound or an outbound method. This is used * to mark whether it can be blocked when the system is unstable, * only inbound traffic could be blocked by {@link SystemRule} - * @param count tokens required + * @param count the amount of calls within the invocation (e.g. batchCount=2 means request for 2 tokens) * @return true if no rule's threshold is exceeded, otherwise return false. */ public static boolean entry(String name, EntryType type, int count) { @@ -166,46 +167,46 @@ public class SphO { } /** - * Checking all {@link Rule}s about the resource. + * Record statistics and perform rule checking for the given resource. * - * @param name the unique name for the protected resource - * @param type the resource is an inbound or an outbound method. This is used - * to mark whether it can be blocked when the system is unstable, - * only inbound traffic could be blocked by {@link SystemRule} - * @param count tokens required - * @param args extra parameters. + * @param name the unique name for the protected resource + * @param trafficType the traffic type (inbound, outbound or internal). This is used + * to mark whether it can be blocked when the system is unstable, + * only inbound traffic could be blocked by {@link SystemRule} + * @param batchCount the amount of calls within the invocation (e.g. batchCount=2 means request for 2 tokens) + * @param args args for parameter flow control or customized slots * @return true if no rule's threshold is exceeded, otherwise return false. */ - public static boolean entry(String name, EntryType type, int count, Object... args) { + public static boolean entry(String name, EntryType trafficType, int batchCount, Object... args) { try { - Env.sph.entry(name, type, count, args); + Env.sph.entry(name, trafficType, batchCount, args); } catch (BlockException e) { return false; } catch (Throwable e) { - RecordLog.info("[Sentinel] Fatal error", e); + RecordLog.warn("SphO fatal error", e); return true; } return true; } /** - * Checking all {@link Rule}s about the protected method. + * Record statistics and perform rule checking for the given method resource. * - * @param method the protected method - * @param type the resource is an inbound or an outbound method. This is used - * to mark whether it can be blocked when the system is unstable, - * only inbound traffic could be blocked by {@link SystemRule} - * @param count tokens required - * @param args the parameters of the method. + * @param method the protected method + * @param trafficType the traffic type (inbound, outbound or internal). This is used + * to mark whether it can be blocked when the system is unstable, + * only inbound traffic could be blocked by {@link SystemRule} + * @param batchCount the amount of calls within the invocation (e.g. batchCount=2 means request for 2 tokens) + * @param args args for parameter flow control or customized slots * @return true if no rule's threshold is exceeded, otherwise return false. */ - public static boolean entry(Method method, EntryType type, int count, Object... args) { + public static boolean entry(Method method, EntryType trafficType, int batchCount, Object... args) { try { - Env.sph.entry(method, type, count, args); + Env.sph.entry(method, trafficType, batchCount, args); } catch (BlockException e) { return false; } catch (Throwable e) { - RecordLog.info("[Sentinel] Fatal error", e); + RecordLog.warn("SphO fatal error", e); return true; } return true; diff --git a/sentinel-core/src/main/java/com/alibaba/csp/sentinel/SphResourceTypeSupport.java b/sentinel-core/src/main/java/com/alibaba/csp/sentinel/SphResourceTypeSupport.java index 4349473f..ab9574e4 100644 --- a/sentinel-core/src/main/java/com/alibaba/csp/sentinel/SphResourceTypeSupport.java +++ b/sentinel-core/src/main/java/com/alibaba/csp/sentinel/SphResourceTypeSupport.java @@ -16,6 +16,7 @@ package com.alibaba.csp.sentinel; import com.alibaba.csp.sentinel.slots.block.BlockException; +import com.alibaba.csp.sentinel.slots.system.SystemRule; /** * @author Eric Zhao @@ -24,46 +25,53 @@ import com.alibaba.csp.sentinel.slots.block.BlockException; public interface SphResourceTypeSupport { /** - * Create a protected resource with provided classification. + * Record statistics and perform rule checking for the given resource with provided classification. * - * @param name the unique name of the protected resource + * @param name the unique name of the protected resource * @param resourceType the classification of the resource - * @param entryType the traffic entry type (IN/OUT) of the resource - * @param count tokens required - * @param args extra parameters - * @return new entry of the resource + * @param trafficType the traffic type (inbound, outbound or internal). This is used + * to mark whether it can be blocked when the system is unstable, + * only inbound traffic could be blocked by {@link SystemRule} + * @param batchCount the amount of calls within the invocation (e.g. batchCount=2 means request for 2 tokens) + * @param args args for parameter flow control or customized slots + * @return the {@link Entry} of this invocation (used for mark the invocation complete and get context data) * @throws BlockException if the block criteria is met */ - Entry entryWithType(String name, int resourceType, EntryType entryType, int count, Object[] args) + Entry entryWithType(String name, int resourceType, EntryType trafficType, int batchCount, Object[] args) throws BlockException; /** - * Create a protected resource with provided classification. + * Record statistics and perform rule checking for the given resource with the provided classification. * - * @param name the unique name of the protected resource - * @param resourceType the classification of the resource - * @param entryType the traffic entry type (IN/OUT) of the resource - * @param count tokens required - * @param prioritized whether the entry is prioritized - * @param args extra parameters - * @return new entry of the resource + * @param name the unique name of the protected resource + * @param resourceType classification of the resource (e.g. Web or RPC) + * @param trafficType the traffic type (inbound, outbound or internal). This is used + * to mark whether it can be blocked when the system is unstable, + * only inbound traffic could be blocked by {@link SystemRule} + * @param batchCount the amount of calls within the invocation (e.g. batchCount=2 means request for 2 tokens) + * @param prioritized whether the entry is prioritized + * @param args args for parameter flow control or customized slots + * @return the {@link Entry} of this invocation (used for mark the invocation complete and get context data) * @throws BlockException if the block criteria is met */ - Entry entryWithType(String name, int resourceType, EntryType entryType, int count, boolean prioritized, + Entry entryWithType(String name, int resourceType, EntryType trafficType, int batchCount, boolean prioritized, Object[] args) throws BlockException; /** - * Create an asynchronous resource with provided classification. + * Record statistics and perform rule checking for the given resource that indicates an async invocation. * - * @param name the unique name of the protected resource - * @param resourceType the classification of the resource - * @param entryType the traffic entry type (IN/OUT) of the resource - * @param count tokens required - * @param prioritized whether the entry is prioritized - * @param args extra parameters - * @return new entry of the resource + * @param name the unique name for the protected resource + * @param resourceType classification of the resource (e.g. Web or RPC) + * @param trafficType the traffic type (inbound, outbound or internal). This is used + * to mark whether it can be blocked when the system is unstable, + * only inbound traffic could be blocked by {@link SystemRule} + * @param batchCount the amount of calls within the invocation (e.g. batchCount=2 means request for 2 tokens) + * @param prioritized whether the entry is prioritized + * @param args args for parameter flow control or customized slots + * @return the {@link Entry} of this invocation (used for mark the invocation complete and get context data) * @throws BlockException if the block criteria is met */ - AsyncEntry asyncEntryWithType(String name, int resourceType, EntryType entryType, int count, boolean prioritized, + AsyncEntry asyncEntryWithType(String name, int resourceType, EntryType trafficType, int batchCount, + boolean prioritized, Object[] args) throws BlockException; } diff --git a/sentinel-core/src/main/java/com/alibaba/csp/sentinel/SphU.java b/sentinel-core/src/main/java/com/alibaba/csp/sentinel/SphU.java index a7ad2aa1..04feea0c 100755 --- a/sentinel-core/src/main/java/com/alibaba/csp/sentinel/SphU.java +++ b/sentinel-core/src/main/java/com/alibaba/csp/sentinel/SphU.java @@ -16,25 +16,21 @@ package com.alibaba.csp.sentinel; import java.lang.reflect.Method; -import java.util.List; import com.alibaba.csp.sentinel.slots.block.BlockException; import com.alibaba.csp.sentinel.slots.block.Rule; -import com.alibaba.csp.sentinel.slots.block.degrade.DegradeRuleManager; -import com.alibaba.csp.sentinel.slots.block.flow.FlowRuleManager; import com.alibaba.csp.sentinel.slots.system.SystemRule; -import com.alibaba.csp.sentinel.slots.system.SystemRuleManager; /** + *

The fundamental Sentinel API for recording statistics and performing rule checking for resources.

+ *

* Conceptually, physical or logical resource that need protection should be * surrounded by an entry. The requests to this resource will be blocked if any * criteria is met, eg. when any {@link Rule}'s threshold is exceeded. Once blocked, * a {@link BlockException} will be thrown. - * + *

*

- * To configure the criteria, we can use XXXRuleManager.loadRules() to add rules, eg. - * {@link FlowRuleManager#loadRules(List)}, {@link DegradeRuleManager#loadRules(List)}, - * {@link SystemRuleManager#loadRules(List)}. + * To configure the criteria, we can use XxxRuleManager.loadRules() to load rules. *

* *

@@ -79,10 +75,11 @@ public class SphU { private SphU() {} /** - * Checking all {@link Rule}s about the resource. + * Record statistics and perform rule checking for the given resource. * * @param name the unique name of the protected resource - * @throws BlockException if the block criteria is met, eg. when any rule's threshold is exceeded. + * @return the {@link Entry} of this invocation (used for mark the invocation complete and get context data) + * @throws BlockException if the block criteria is met (e.g. metric exceeded the threshold of any rules) */ public static Entry entry(String name) throws BlockException { return Env.sph.entry(name, EntryType.OUT, 1, OBJECTS0); @@ -92,7 +89,8 @@ public class SphU { * Checking all {@link Rule}s about the protected method. * * @param method the protected method - * @throws BlockException if the block criteria is met, eg. when any rule's threshold is exceeded. + * @return the {@link Entry} of this invocation (used for mark the invocation complete and get context data) + * @throws BlockException if the block criteria is met (e.g. metric exceeded the threshold of any rules) */ public static Entry entry(Method method) throws BlockException { return Env.sph.entry(method, EntryType.OUT, 1, OBJECTS0); @@ -101,114 +99,120 @@ public class SphU { /** * Checking all {@link Rule}s about the protected method. * - * @param method the protected method - * @param count tokens required - * @throws BlockException if the block criteria is met, eg. when any rule's threshold is exceeded. + * @param method the protected method + * @param batchCount the amount of calls within the invocation (e.g. batchCount=2 means request for 2 tokens) + * @return the {@link Entry} of this invocation (used for mark the invocation complete and get context data) + * @throws BlockException if the block criteria is met (e.g. metric exceeded the threshold of any rules) */ - public static Entry entry(Method method, int count) throws BlockException { - return Env.sph.entry(method, EntryType.OUT, count, OBJECTS0); + public static Entry entry(Method method, int batchCount) throws BlockException { + return Env.sph.entry(method, EntryType.OUT, batchCount, OBJECTS0); } /** - * Checking all {@link Rule}s about the resource. + * Record statistics and perform rule checking for the given resource. * - * @param name the unique string for the resource - * @param count tokens required - * @throws BlockException if the block criteria is met, eg. when any rule's threshold is exceeded. + * @param name the unique string for the resource + * @param batchCount the amount of calls within the invocation (e.g. batchCount=2 means request for 2 tokens) + * @return the {@link Entry} of this invocation (used for mark the invocation complete and get context data) + * @throws BlockException if the block criteria is met (e.g. metric exceeded the threshold of any rules) */ - public static Entry entry(String name, int count) throws BlockException { - return Env.sph.entry(name, EntryType.OUT, count, OBJECTS0); + public static Entry entry(String name, int batchCount) throws BlockException { + return Env.sph.entry(name, EntryType.OUT, batchCount, OBJECTS0); } /** * Checking all {@link Rule}s about the protected method. * - * @param method the protected method - * @param type the resource is an inbound or an outbound method. This is used - * to mark whether it can be blocked when the system is unstable, - * only inbound traffic could be blocked by {@link SystemRule} - * @throws BlockException if the block criteria is met, eg. when any rule's threshold is exceeded. + * @param method the protected method + * @param trafficType the traffic type (inbound, outbound or internal). This is used + * to mark whether it can be blocked when the system is unstable, + * only inbound traffic could be blocked by {@link SystemRule} + * @throws BlockException if the block criteria is met (e.g. metric exceeded the threshold of any rules) */ - public static Entry entry(Method method, EntryType type) throws BlockException { - return Env.sph.entry(method, type, 1, OBJECTS0); + public static Entry entry(Method method, EntryType trafficType) throws BlockException { + return Env.sph.entry(method, trafficType, 1, OBJECTS0); } /** - * Checking all {@link Rule}s about the resource. + * Record statistics and perform rule checking for the given resource. * - * @param name the unique name for the protected resource - * @param type the resource is an inbound or an outbound method. This is used - * to mark whether it can be blocked when the system is unstable, - * only inbound traffic could be blocked by {@link SystemRule} - * @throws BlockException if the block criteria is met, eg. when any rule's threshold is exceeded. + * @param name the unique name for the protected resource + * @param trafficType the traffic type (inbound, outbound or internal). This is used + * to mark whether it can be blocked when the system is unstable, + * only inbound traffic could be blocked by {@link SystemRule} + * @throws BlockException if the block criteria is met (e.g. metric exceeded the threshold of any rules) */ - public static Entry entry(String name, EntryType type) throws BlockException { - return Env.sph.entry(name, type, 1, OBJECTS0); + public static Entry entry(String name, EntryType trafficType) throws BlockException { + return Env.sph.entry(name, trafficType, 1, OBJECTS0); } /** * Checking all {@link Rule}s about the protected method. * - * @param method the protected method - * @param type the resource is an inbound or an outbound method. This is used - * to mark whether it can be blocked when the system is unstable, - * only inbound traffic could be blocked by {@link SystemRule} - * @param count tokens required - * @throws BlockException if the block criteria is met, eg. when any rule's threshold is exceeded. + * @param method the protected method + * @param trafficType the traffic type (inbound, outbound or internal). This is used + * to mark whether it can be blocked when the system is unstable, + * only inbound traffic could be blocked by {@link SystemRule} + * @param batchCount the amount of calls within the invocation (e.g. batchCount=2 means request for 2 tokens) + * @throws BlockException if the block criteria is met (e.g. metric exceeded the threshold of any rules) */ - public static Entry entry(Method method, EntryType type, int count) throws BlockException { - return Env.sph.entry(method, type, count, OBJECTS0); + public static Entry entry(Method method, EntryType trafficType, int batchCount) throws BlockException { + return Env.sph.entry(method, trafficType, batchCount, OBJECTS0); } /** - * Checking all {@link Rule}s about the resource. + * Record statistics and perform rule checking for the given resource. * - * @param name the unique name for the protected resource - * @param type the resource is an inbound or an outbound method. This is used - * to mark whether it can be blocked when the system is unstable, - * only inbound traffic could be blocked by {@link SystemRule} - * @param count tokens required - * @throws BlockException if the block criteria is met, eg. when any rule's threshold is exceeded. + * @param name the unique name for the protected resource + * @param trafficType the traffic type (inbound, outbound or internal). This is used + * to mark whether it can be blocked when the system is unstable, + * only inbound traffic could be blocked by {@link SystemRule} + * @param batchCount the amount of calls within the invocation (e.g. batchCount=2 means request for 2 tokens) + * @return the {@link Entry} of this invocation (used for mark the invocation complete and get context data) + * @throws BlockException if the block criteria is met (e.g. metric exceeded the threshold of any rules) */ - public static Entry entry(String name, EntryType type, int count) throws BlockException { - return Env.sph.entry(name, type, count, OBJECTS0); + public static Entry entry(String name, EntryType trafficType, int batchCount) throws BlockException { + return Env.sph.entry(name, trafficType, batchCount, OBJECTS0); } /** * Checking all {@link Rule}s about the protected method. * - * @param method the protected method - * @param type the resource is an inbound or an outbound method. This is used - * to mark whether it can be blocked when the system is unstable, - * only inbound traffic could be blocked by {@link SystemRule} - * @param count tokens required - * @param args the parameters of the method. - * @throws BlockException if the block criteria is met, eg. when any rule's threshold is exceeded. + * @param method the protected method + * @param trafficType the traffic type (inbound, outbound or internal). This is used + * to mark whether it can be blocked when the system is unstable, + * only inbound traffic could be blocked by {@link SystemRule} + * @param batchCount the amount of calls within the invocation (e.g. batchCount=2 means request for 2 tokens) + * @param args args for parameter flow control or customized slots + * @return the {@link Entry} of this invocation (used for mark the invocation complete and get context data) + * @throws BlockException if the block criteria is met (e.g. metric exceeded the threshold of any rules) */ - public static Entry entry(Method method, EntryType type, int count, Object... args) throws BlockException { - return Env.sph.entry(method, type, count, args); + public static Entry entry(Method method, EntryType trafficType, int batchCount, Object... args) + throws BlockException { + return Env.sph.entry(method, trafficType, batchCount, args); } /** - * Checking all {@link Rule}s about the resource. + * Record statistics and perform rule checking for the given resource. * - * @param name the unique name for the protected resource - * @param type the resource is an inbound or an outbound method. This is used - * to mark whether it can be blocked when the system is unstable, - * only inbound traffic could be blocked by {@link SystemRule} - * @param count tokens required - * @param args extra parameters. - * @throws BlockException if the block criteria is met, eg. when any rule's threshold is exceeded. + * @param name the unique name for the protected resource + * @param trafficType the traffic type (inbound, outbound or internal). This is used + * to mark whether it can be blocked when the system is unstable, + * only inbound traffic could be blocked by {@link SystemRule} + * @param batchCount the amount of calls within the invocation (e.g. batchCount=2 means request for 2 tokens) + * @param args args for parameter flow control + * @throws BlockException if the block criteria is met (e.g. metric exceeded the threshold of any rules) */ - public static Entry entry(String name, EntryType type, int count, Object... args) throws BlockException { - return Env.sph.entry(name, type, count, args); + public static Entry entry(String name, EntryType trafficType, int batchCount, Object... args) + throws BlockException { + return Env.sph.entry(name, trafficType, batchCount, args); } /** - * Checking all rules about the asynchronous resource. + * Record statistics and check all rules of the resource that indicates an async invocation. * * @param name the unique name of the protected resource - * @throws BlockException if the block criteria is met, eg. when any rule's threshold is exceeded + * @throws BlockException if the block criteria is met (e.g. metric exceeded the threshold of any rules) * @since 0.2.0 */ public static AsyncEntry asyncEntry(String name) throws BlockException { @@ -216,40 +220,43 @@ public class SphU { } /** - * Checking all {@link Rule}s about the asynchronous resource. + * Record statistics and check all rules of the resource that indicates an async invocation. * - * @param name the unique name for the protected resource - * @param type the resource is an inbound or an outbound method. This is used - * to mark whether it can be blocked when the system is unstable, - * only inbound traffic could be blocked by {@link SystemRule} - * @throws BlockException if the block criteria is met, eg. when any rule's threshold is exceeded + * @param name the unique name for the protected resource + * @param trafficType the traffic type (inbound, outbound or internal). This is used + * to mark whether it can be blocked when the system is unstable, + * only inbound traffic could be blocked by {@link SystemRule} + * @return the {@link Entry} of this invocation (used for mark the invocation complete and get context data) + * @throws BlockException if the block criteria is met (e.g. metric exceeded the threshold of any rules) * @since 0.2.0 */ - public static AsyncEntry asyncEntry(String name, EntryType type) throws BlockException { - return Env.sph.asyncEntry(name, type, 1, OBJECTS0); + public static AsyncEntry asyncEntry(String name, EntryType trafficType) throws BlockException { + return Env.sph.asyncEntry(name, trafficType, 1, OBJECTS0); } /** - * Checking all {@link Rule}s about the asynchronous resource. + * Record statistics and check all rules of the resource that indicates an async invocation. * - * @param name the unique name for the protected resource - * @param type the resource is an inbound or an outbound method. This is used - * to mark whether it can be blocked when the system is unstable, - * only inbound traffic could be blocked by {@link SystemRule} - * @param count tokens required - * @param args extra parameters - * @throws BlockException if the block criteria is met, eg. when any rule's threshold is exceeded + * @param name the unique name for the protected resource + * @param trafficType the traffic type (inbound, outbound or internal). This is used + * to mark whether it can be blocked when the system is unstable, + * only inbound traffic could be blocked by {@link SystemRule} + * @param batchCount the amount of calls within the invocation (e.g. batchCount=2 means request for 2 tokens) + * @param args args for parameter flow control + * @return the {@link Entry} of this invocation (used for mark the invocation complete and get context data) + * @throws BlockException if the block criteria is met (e.g. metric exceeded the threshold of any rules) * @since 0.2.0 */ - public static AsyncEntry asyncEntry(String name, EntryType type, int count, Object... args) throws BlockException { - return Env.sph.asyncEntry(name, type, count, args); + public static AsyncEntry asyncEntry(String name, EntryType trafficType, int batchCount, Object... args) + throws BlockException { + return Env.sph.asyncEntry(name, trafficType, batchCount, args); } /** - * Checking all {@link Rule}s related the resource. The entry is prioritized. + * Record statistics and perform rule checking for the given resource. The entry is prioritized. * * @param name the unique name for the protected resource - * @throws BlockException if the block criteria is met, eg. when any rule's threshold is exceeded. + * @throws BlockException if the block criteria is met (e.g. metric exceeded the threshold of any rules) * @since 1.4.0 */ public static Entry entryWithPriority(String name) throws BlockException { @@ -257,99 +264,105 @@ public class SphU { } /** - * Checking all {@link Rule}s related the resource. The entry is prioritized. + * Record statistics and perform rule checking for the given resource. The entry is prioritized. * - * @param name the unique name for the protected resource - * @param type the resource is an inbound or an outbound method. This is used - * to mark whether it can be blocked when the system is unstable, - * only inbound traffic could be blocked by {@link SystemRule} - * @throws BlockException if the block criteria is met, eg. when any rule's threshold is exceeded. + * @param name the unique name for the protected resource + * @param trafficType the traffic type (inbound, outbound or internal). This is used + * to mark whether it can be blocked when the system is unstable, + * only inbound traffic could be blocked by {@link SystemRule} + * @return the {@link Entry} of this invocation (used for mark the invocation complete and get context data) + * @throws BlockException if the block criteria is met (e.g. metric exceeded the threshold of any rules) * @since 1.4.0 */ - public static Entry entryWithPriority(String name, EntryType type) throws BlockException { - return Env.sph.entryWithPriority(name, type, 1, true); + public static Entry entryWithPriority(String name, EntryType trafficType) throws BlockException { + return Env.sph.entryWithPriority(name, trafficType, 1, true); } /** - * Record statistics and check all rules of the resource. + * Record statistics and perform rule checking for the given resource. * * @param name the unique name for the protected resource * @param resourceType classification of the resource (e.g. Web or RPC) - * @param type the resource is an inbound or an outbound method. This is used + * @param trafficType the traffic type (inbound, outbound or internal). This is used * to mark whether it can be blocked when the system is unstable, * only inbound traffic could be blocked by {@link SystemRule} - * @throws BlockException if the block criteria is met, eg. when any rule's threshold is exceeded + * @return the {@link Entry} of this invocation (used for mark the invocation complete and get context data) + * @throws BlockException if the block criteria is met (e.g. metric exceeded the threshold of any rules) * @since 1.7.0 */ - public static Entry entry(String name, int resourceType, EntryType type) throws BlockException { - return Env.sph.entryWithType(name, resourceType, type, 1, OBJECTS0); + public static Entry entry(String name, int resourceType, EntryType trafficType) throws BlockException { + return Env.sph.entryWithType(name, resourceType, trafficType, 1, OBJECTS0); } /** - * Record statistics and check all rules of the resource. + * Record statistics and perform rule checking for the given resource. * * @param name the unique name for the protected resource - * @param type the resource is an inbound or an outbound method. This is used + * @param trafficType the traffic type (inbound, outbound or internal). This is used * to mark whether it can be blocked when the system is unstable, * only inbound traffic could be blocked by {@link SystemRule} * @param resourceType classification of the resource (e.g. Web or RPC) - * @param args extra parameters. - * @throws BlockException if the block criteria is met, eg. when any rule's threshold is exceeded + * @param args args for parameter flow control or customized slots + * @return the {@link Entry} of this invocation (used for mark the invocation complete and get context data) + * @throws BlockException if the block criteria is met (e.g. metric exceeded the threshold of any rules) * @since 1.7.0 */ - public static Entry entry(String name, int resourceType, EntryType type, Object[] args) + public static Entry entry(String name, int resourceType, EntryType trafficType, Object[] args) throws BlockException { - return Env.sph.entryWithType(name, resourceType, type, 1, args); + return Env.sph.entryWithType(name, resourceType, trafficType, 1, args); } /** - * Record statistics and check all rules of the resource. + * Record statistics and perform rule checking for the given resource that indicates an async invocation. * * @param name the unique name for the protected resource - * @param type the resource is an inbound or an outbound method. This is used + * @param trafficType the traffic type (inbound, outbound or internal). This is used * to mark whether it can be blocked when the system is unstable, * only inbound traffic could be blocked by {@link SystemRule} * @param resourceType classification of the resource (e.g. Web or RPC) - * @throws BlockException if the block criteria is met, eg. when any rule's threshold is exceeded + * @return the {@link Entry} of this invocation (used for mark the invocation complete and get context data) + * @throws BlockException if the block criteria is met (e.g. metric exceeded the threshold of any rules) * @since 1.7.0 */ - public static AsyncEntry asyncEntry(String name, int resourceType, EntryType type) + public static AsyncEntry asyncEntry(String name, int resourceType, EntryType trafficType) throws BlockException { - return Env.sph.asyncEntryWithType(name, resourceType, type, 1, false, OBJECTS0); + return Env.sph.asyncEntryWithType(name, resourceType, trafficType, 1, false, OBJECTS0); } /** - * Record statistics and check all rules of the resource. + * Record statistics and perform rule checking for the given resource that indicates an async invocation. * * @param name the unique name for the protected resource - * @param type the resource is an inbound or an outbound method. This is used + * @param trafficType the traffic type (inbound, outbound or internal). This is used * to mark whether it can be blocked when the system is unstable, * only inbound traffic could be blocked by {@link SystemRule} * @param resourceType classification of the resource (e.g. Web or RPC) - * @param args extra parameters - * @throws BlockException if the block criteria is met, eg. when any rule's threshold is exceeded + * @param args args for parameter flow control or customized slots + * @return the {@link Entry} of this invocation (used for mark the invocation complete and get context data) + * @throws BlockException if the block criteria is met (e.g. metric exceeded the threshold of any rules) * @since 1.7.0 */ - public static AsyncEntry asyncEntry(String name, int resourceType, EntryType type, Object[] args) + public static AsyncEntry asyncEntry(String name, int resourceType, EntryType trafficType, Object[] args) throws BlockException { - return Env.sph.asyncEntryWithType(name, resourceType, type, 1, false, args); + return Env.sph.asyncEntryWithType(name, resourceType, trafficType, 1, false, args); } /** - * Record statistics and check all rules of the resource. + * Record statistics and perform rule checking for the given resource that indicates an async invocation. * * @param name the unique name for the protected resource - * @param type the resource is an inbound or an outbound method. This is used + * @param trafficType the traffic type (inbound, outbound or internal). This is used * to mark whether it can be blocked when the system is unstable, * only inbound traffic could be blocked by {@link SystemRule} * @param resourceType classification of the resource (e.g. Web or RPC) - * @param acquireCount tokens required - * @param args extra parameters - * @throws BlockException if the block criteria is met, eg. when any rule's threshold is exceeded + * @param batchCount the amount of calls within the invocation (e.g. batchCount=2 means request for 2 tokens) + * @param args args for parameter flow control or customized slots + * @return the {@link Entry} of this invocation (used for mark the invocation complete and get context data) + * @throws BlockException if the block criteria is met (e.g. metric exceeded the threshold of any rules) * @since 1.7.0 */ - public static AsyncEntry asyncEntry(String name, int resourceType, EntryType type, int acquireCount, + public static AsyncEntry asyncEntry(String name, int resourceType, EntryType trafficType, int batchCount, Object[] args) throws BlockException { - return Env.sph.asyncEntryWithType(name, resourceType, type, acquireCount, false, args); + return Env.sph.asyncEntryWithType(name, resourceType, trafficType, batchCount, false, args); } }