Common classes and their methods-Microservices Engine(MSE)-阿里云帮助中心

This topic describes the common classes and methods for flow control and circuit breaking.

BlockException: The exception class for flow control and circuit breaking

In Sentinel, all exceptions related to flow control and circuit breaking are subclasses of the BlockException class:

Flow control exception: FlowException
Degradation exception (DegradeException)
System protection exception: SystemException
Hot spot parameter flow control exception: ParamFlowException

You can use the following methods to identify throttling and performance degradation:

BlockException.isBlockException(Throwable t)

SphU and SphO: Resource definition classes

SphU and SphO are two utility classes for defining resources. SphU defines resources in a try-catch format, while SphO uses an if-else format.

The SphU class contains the following static methods:

Define a resource by passing its name:

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

The resource name is the value of the name parameter.

Define a method resource by passing a Method object:

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

The resource name is parsed from the Method object. The format is ClassName:MethodSignature, such as com.alibaba.csp.sentinel.demo.DemoService:foo(java.lang.String).

Asynchronous resource definition:

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

The parameters are described below.

Parameter name	Type	Description	Default value
entryType	EntryType	The traffic type of the resource call. It can be inbound traffic (`IN`), outbound traffic (`OUT`), or an internal call (`INTERNAL`). Note that adaptive system protection works only for the `IN` type.	`EntryType.OUT`
resourceType	Int	The classification of the resource call, such as Web, RPC, or DB_SQL.	`COMMON`(0)
batchCount	Int	The number of tokens for this resource call request. This is the number of calls to be counted.	1
args	Object[]	The passed parameters, used for hot spot parameter flow control.	None

Return value types:

A standard resource definition returns an Entry object, which represents the current resource call.
An asynchronous resource definition returns an AsyncEntry object, which represents the current asynchronous resource call.

For more information, see Define resources.

SentinelWrapper: The managed resource definition class

Note

SentinelWrapper was introduced in Java SDK 1.8.0 and later versions.

SentinelWrapper is used for the instrumentation of managed resources. Unlike SphU/SphO, SentinelWrapper requires you to provide a function that it will manage. This is similar to using the @SentinelResource annotation and supports mechanisms such as automatic retries and timeout-based circuit breaking. The SentinelWrapper class has two main methods:

execute: Throws an exception directly when an error occurs, including when a request is throttled.
executeWithFallback: Accepts a fallback function to handle exceptions and return a normal result.

The SentinelWrapper class defines a managed resource as follows:

public static <R> R execute(Callable<R> func, String resource, EntryType trafficType, int resourceType) throws Exception
public static <R> R execute(Callable<R> func, String resource, EntryType trafficType, int resourceType, Object[] args) throws Exception
public static <R> R executeWithFallback(Callable<R> func, CheckedFunction<Throwable, R> fallbackFunction, String resource, EntryType trafficType) throws Exception
public static <R> R executeWithFallback(Callable<R> func, CheckedFunction<Throwable, R> fallbackFunction, String resource, EntryType trafficType, int resourceType) throws Exception
public static <R> R executeWithFallback(Callable<R> func, CheckedFunction<Throwable, R> fallbackFunction, String resource, EntryType trafficType, int resourceType, Object[] args) throws Exception

Parameter name	Type	Description	Default value
func	Callable<R>	The function to execute. The result is provided in the return value.	None (Required)
fallbackFunction	CheckedFunction<Throwable, R>	The fallback function. When an exception occurs, this function is used to generate a fallback result.	None
entryType	EntryType	The traffic type of the resource call. It can be inbound traffic (`IN`), outbound traffic (`OUT`), or an internal call (`INTERNAL`). Note that adaptive system protection works only for the `IN` type.	`EntryType.OUT`
resourceType	Int	The classification of the resource call, such as Web, RPC, or DB_SQL.	COMMON(0)
args	Object[]	The passed parameters, used for hot spot parameter flow control.	None

Entry

An Entry object represents a single resource call. This object is returned after you define a resource using SphU or SphO. Its main method is:

public void exit() throws ErrorEntryFreeException: Indicates that the resource call has ended. This method must be paired with an entry method call.

Exception description:

ErrorEntryFreeException: This exception is thrown if the entry and exit calls for the current resource are not correctly paired.

Tracer: The business exception recording class

The Tracer class is used to record business exceptions. Its related methods are:

public static void trace(Throwable e): Records a business exception that is not a BlockException.
public static void trace(Throwable e, int count): Records a business exception. The number of exceptions is specified by the count parameter.

If you manually define resources using SphU or SphO, Sentinel cannot detect exceptions from your business logic. You must manually call Tracer.trace(ex) to record business exceptions. Otherwise, the exceptions are not included in Sentinel's exception count.

When you define resources using annotations, the Web Servlet adapter, or the Dubbo adapter, business exceptions are counted automatically. You do not need to manually call Tracer.trace(ex).

ContextUtil: The context utility class

Related methods:

Mark the entry point of a call chain (context):

The following static methods mark the entry point of a call chain:

public static Context enter(String contextName)
public static Context enter(String contextName, String origin)

The contextName parameter represents the name of the call chain entry point (context), and origin represents the name of the call source. By default, the call source is empty. The return value is a Context object, which is the context object for the call chain.

Note

The ContextUtil.enter(xxx) method takes effect only at the entry point of a call chain. This means it works only for the first call in the current thread. Subsequent calls do not overwrite the call chain of the current thread until exit is called. The Context is stored in a ThreadLocal variable. Therefore, it might be lost when you switch threads. To use the context across threads, combine it with the runOnContext method.

In a flow control rule, if you set "Throttling Method" to "By Call Chain", the entry resource name is the contextName described above.

Exit a call chain (clear the context):

public static void exit(): This method exits the call chain and clears the context of the current thread.

Retrieve the call chain context of the current thread:

public static Context getContext(): Retrieves the call chain context object of the current thread.

Execute code within a specific call chain context:

public static void runOnContext(Context context, Runnable f): This method is often used to switch contexts in asynchronous call chains.