com.alibaba.csp.sentinel

Class SphU

java.lang.Object

com.alibaba.csp.sentinel.SphU

public class SphU
extends Object

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 Rule's threshold is exceeded. Once blocked, a BlockException will be thrown.

To configure the criteria, we can use XxxRuleManager.loadRules() to load rules.

Following code is an example, "abc" represent a unique name for the protected resource:

  public void foo() {
     Entry entry = null;
     try {
        entry = SphU.entry("abc");
        // resource that need protection
     } catch (BlockException blockException) {
         // when goes there, it is blocked
         // add blocked handle logic here
     } catch (Throwable bizException) {
         // business exception
         Tracer.trace(bizException);
     } finally {
         // ensure finally be executed
         if (entry != null){
             entry.exit();
         }
     }
  }
 

Make sure SphU.entry() and Entry.exit() be paired in the same thread, otherwise ErrorEntryFreeException will be thrown.

Author:

jialiang.linjl, Eric Zhao

See Also:

SphO

Method Summary

Modifier and Type	Method and Description
static AsyncEntry	asyncEntry(String name) Record statistics and check all rules of the resource that indicates an async invocation.
static AsyncEntry	asyncEntry(String name, EntryType trafficType) Record statistics and check all rules of the resource that indicates an async invocation.
static AsyncEntry	asyncEntry(String name, EntryType trafficType, int batchCount, Object... args) Record statistics and check all rules of the resource that indicates an async invocation.
static AsyncEntry	asyncEntry(String name, int resourceType, EntryType trafficType) Record statistics and perform rule checking for the given resource that indicates an async invocation.
static AsyncEntry	asyncEntry(String name, int resourceType, EntryType trafficType, int batchCount, Object[] args) Record statistics and perform rule checking for the given resource that indicates an async invocation.
static AsyncEntry	asyncEntry(String name, int resourceType, EntryType trafficType, Object[] args) Record statistics and perform rule checking for the given resource that indicates an async invocation.
static Entry	entry(Method method) Checking all Rules about the protected method.
static Entry	entry(Method method, EntryType trafficType) Checking all Rules about the protected method.
static Entry	entry(Method method, EntryType trafficType, int batchCount) Checking all Rules about the protected method.
static Entry	entry(Method method, EntryType trafficType, int batchCount, Object... args) Checking all Rules about the protected method.
static Entry	entry(Method method, int batchCount) Checking all Rules about the protected method.
static Entry	entry(String name) Record statistics and perform rule checking for the given resource.
static Entry	entry(String name, EntryType trafficType) Record statistics and perform rule checking for the given resource.
static Entry	entry(String name, EntryType trafficType, int batchCount) Record statistics and perform rule checking for the given resource.
static Entry	entry(String name, EntryType trafficType, int batchCount, Object... args) Record statistics and perform rule checking for the given resource.
static Entry	entry(String name, int batchCount) Record statistics and perform rule checking for the given resource.
static Entry	entry(String name, int resourceType, EntryType trafficType) Record statistics and perform rule checking for the given resource.
static Entry	entry(String name, int resourceType, EntryType trafficType, Object[] args) Record statistics and perform rule checking for the given resource.
static Entry	entryWithPriority(String name) Record statistics and perform rule checking for the given resource.
static Entry	entryWithPriority(String name, EntryType trafficType) Record statistics and perform rule checking for the given resource.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

entry

public static Entry entry(String name)
                   throws BlockException

Record statistics and perform rule checking for the given resource.

Parameters:

name - the unique name of the protected resource

Returns:

the 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)

entry

public static Entry entry(Method method)
                   throws BlockException

Checking all Rules about the protected method.

Parameters:

method - the protected method

Returns:

the 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)

entry

public static Entry entry(Method method,
                          int batchCount)
                   throws BlockException

Checking all Rules about the protected method.

Parameters:

method - the protected method

batchCount - the amount of calls within the invocation (e.g. batchCount=2 means request for 2 tokens)

Returns:

the 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)

entry

public static Entry entry(String name,
                          int batchCount)
                   throws BlockException

Record statistics and perform rule checking for the given resource.

Parameters:

name - the unique string for the resource

batchCount - the amount of calls within the invocation (e.g. batchCount=2 means request for 2 tokens)

Returns:

the 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)

entry

public static Entry entry(Method method,
                          EntryType trafficType)
                   throws BlockException

Checking all Rules about the protected method.

Parameters:

method - the protected method

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 SystemRule

Throws:

BlockException - if the block criteria is met (e.g. metric exceeded the threshold of any rules)

entry

public static Entry entry(String name,
                          EntryType trafficType)
                   throws BlockException

Record statistics and perform rule checking for the given resource.

Parameters:

name - the unique name for the protected resource

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 SystemRule

Throws:

BlockException - if the block criteria is met (e.g. metric exceeded the threshold of any rules)

entry

public static Entry entry(Method method,
                          EntryType trafficType,
                          int batchCount)
                   throws BlockException

Checking all Rules about the protected method.

Parameters:

method - the protected method

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 SystemRule

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)

entry

public static Entry entry(String name,
                          EntryType trafficType,
                          int batchCount)
                   throws BlockException

Record statistics and perform rule checking for the given resource.

Parameters:

name - the unique name for the protected resource

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 SystemRule

batchCount - the amount of calls within the invocation (e.g. batchCount=2 means request for 2 tokens)

Returns:

the 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)

entry

public static Entry entry(Method method,
                          EntryType trafficType,
                          int batchCount,
                          Object... args)
                   throws BlockException

Checking all Rules about the protected method.

Parameters:

method - the protected method

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 SystemRule

batchCount - the amount of calls within the invocation (e.g. batchCount=2 means request for 2 tokens)

args - args for parameter flow control or customized slots

Returns:

the 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)

entry

public static Entry entry(String name,
                          EntryType trafficType,
                          int batchCount,
                          Object... args)
                   throws BlockException

Record statistics and perform rule checking for the given resource.

Parameters:

name - the unique name for the protected resource

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 SystemRule

batchCount - the amount of calls within the invocation (e.g. batchCount=2 means request for 2 tokens)

args - args for parameter flow control

Throws:

BlockException - if the block criteria is met (e.g. metric exceeded the threshold of any rules)

asyncEntry

public static AsyncEntry asyncEntry(String name)
                             throws BlockException

Record statistics and check all rules of the resource that indicates an async invocation.

Parameters:

name - the unique name of the protected resource

Throws:

BlockException - if the block criteria is met (e.g. metric exceeded the threshold of any rules)

Since:

0.2.0

asyncEntry

public static AsyncEntry asyncEntry(String name,
                                    EntryType trafficType)
                             throws BlockException

Record statistics and check all rules of the resource that indicates an async invocation.

Parameters:

name - the unique name for the protected resource

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 SystemRule

Returns:

the 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

asyncEntry

public static AsyncEntry asyncEntry(String name,
                                    EntryType trafficType,
                                    int batchCount,
                                    Object... args)
                             throws BlockException

Record statistics and check all rules of the resource that indicates an async invocation.

Parameters:

name - the unique name for the protected resource

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 SystemRule

batchCount - the amount of calls within the invocation (e.g. batchCount=2 means request for 2 tokens)

args - args for parameter flow control

Returns:

the 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

entryWithPriority

public static Entry entryWithPriority(String name)
                               throws BlockException

Record statistics and perform rule checking for the given resource. The entry is prioritized.

Parameters:

name - the unique name for the protected resource

Throws:

BlockException - if the block criteria is met (e.g. metric exceeded the threshold of any rules)

Since:

1.4.0

entryWithPriority

public static Entry entryWithPriority(String name,
                                      EntryType trafficType)
                               throws BlockException

Record statistics and perform rule checking for the given resource. The entry is prioritized.

Parameters:

name - the unique name for the protected resource

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 SystemRule

Returns:

the 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

entry

public static Entry entry(String name,
                          int resourceType,
                          EntryType trafficType)
                   throws BlockException

Record statistics and perform rule checking for the given resource.

Parameters:

name - the unique name for the protected resource

resourceType - classification of the resource (e.g. Web or RPC)

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 SystemRule

Returns:

the 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

entry

public static Entry entry(String name,
                          int resourceType,
                          EntryType trafficType,
                          Object[] args)
                   throws BlockException

Record statistics and perform rule checking for the given resource.

Parameters:

name - the unique name for the protected resource

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 SystemRule

resourceType - classification of the resource (e.g. Web or RPC)

args - args for parameter flow control or customized slots

Returns:

the 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

asyncEntry

public static AsyncEntry asyncEntry(String name,
                                    int resourceType,
                                    EntryType trafficType)
                             throws BlockException

Record statistics and perform rule checking for the given resource that indicates an async invocation.

Parameters:

name - the unique name for the protected resource

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 SystemRule

resourceType - classification of the resource (e.g. Web or RPC)

Returns:

the 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

asyncEntry

public static AsyncEntry asyncEntry(String name,
                                    int resourceType,
                                    EntryType trafficType,
                                    Object[] args)
                             throws BlockException

Record statistics and perform rule checking for the given resource that indicates an async invocation.

Parameters:

name - the unique name for the protected resource

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 SystemRule

resourceType - classification of the resource (e.g. Web or RPC)

args - args for parameter flow control or customized slots

Returns:

the 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

asyncEntry

public static AsyncEntry asyncEntry(String name,
                                    int resourceType,
                                    EntryType trafficType,
                                    int batchCount,
                                    Object[] args)
                             throws BlockException

Record statistics and perform rule checking for the given resource that indicates an async invocation.

Parameters:

name - the unique name for the protected resource

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 SystemRule

resourceType - classification of the resource (e.g. Web or RPC)

batchCount - the amount of calls within the invocation (e.g. batchCount=2 means request for 2 tokens)

args - args for parameter flow control or customized slots

Returns:

the 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