Common classes and methods-Application High Availability Service(AHAS)-阿里云帮助中心

This topic introduces the common classes and methods for throttling and circuit breaking.

The BlockException class for throttling and circuit breaking

In Sentinel, all exceptions related to throttling and circuit breaking are child classes of the BlockException class:

Throttling exception: FlowException
Degradation exception: DegradeException
System protection exception: SystemException
Hot spot parameter throttling exception: ParamFlowException

You can use the following method to determine whether an exception is related to throttling or circuit breaking:

BlockException.isBlockException(Throwable t);

The SphU and SphO resource definition classes

SphU and SphO are two common utility classes for defining resources. SphU defines resources using a try-catch block. SphO defines resources using an if-else statement.

The SphU class includes the following static methods:

Define a resource by passing a resource 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 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 only applies to 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 that are counted.	1
args	`Object[]`	The passed parameters. They are used for hot spot parameter throttling.	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.

The SentinelWrapper class for managed resource definition

Note SentinelWrapper was introduced in Java SDK 1.8.0 and later versions.

SentinelWrapper is used to define instrumentation for managed resources. SentinelWrapper differs from SphU/SphO because it requires a function to run and manages its execution. This is similar to using the @SentinelResource annotation and supports mechanisms such as automatic retries and timeout-based circuit breaking. SentinelWrapper has two main functions:

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

The following is the managed resource definition class SentinelWrapper:

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 reflected in the return value.	None (required)
fallbackFunction	`CheckedFunction<Throwable, R>`	The fallback function. When an exception occurs, this function generates 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 only applies to 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. They are used for hot spot parameter throttling.	None

Entry

An Entry object represents a resource call. This object is returned after a resource is defined using SphU or SphO. The main method is:

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

Exception description:

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

The Tracer class for recording business exceptions

The Tracer class is used to record business exceptions. This class includes the following methods:

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 a resource using SphU or SphO, Sentinel cannot automatically detect business exceptions. You must manually call Tracer.trace(ex) to record business exceptions. Otherwise, these exceptions are not included in Sentinel's exception statistics.

When you define resources using annotations, business exceptions are automatically counted and you do not need to manually call Tracer.trace(ex). The Web Servlet and Dubbo adapters also automatically count business exceptions.

The ContextUtil 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 and are used to distinguish different call chains:

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

contextName is the name of the call chain entry point, also known as the context name. origin is the name of the call source, which is empty by default. The method returns a Context object, which is the generated context object for the call chain.

Note ContextUtil.enter(xxx) method is effective only at the entry point of a call chain, specifically for the first call within the current thread. Subsequent calls do not overwrite the context of the current thread until the context is exited. The Context is stored in a ThreadLocal. Therefore, the context can be lost when you switch threads. To propagate the context across threads, you can use the runOnContext method.

In a throttling rule, if the throttling strategy is set to 'Link', the entry resource name is the contextName mentioned above.

Exit a call chain (clear the context):

public static void exit(): This method is used to exit a call chain and clear the context of the current thread.

Obtain the call chain context of the current thread:

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

Execute code in a specific call chain context:

public static void runOnContext(Context context, Runnable f): This method is often used to run code within a specific context, especially for asynchronous call chains.