Package ru.tinkoff.kora.resilient.circuitbreaker

Interface CircuitBreaker

public interface CircuitBreaker

A CircuitBreaker manages the state of a backend system. The CircuitBreaker is implemented via a finite state machine with five states: CLOSED, OPEN, HALF_OPEN. The CircuitBreaker does not know anything about the backend's state by itself, but uses the information provided by the decorators via releaseOnSuccess() and releaseOnError(Throwable) events. Before communicating with the backend, the permission to do so must be obtained via the method acquire()}.

The state of the CircuitBreaker changes from CLOSED to OPEN when the failure rate is greater than or equal to a (configurable) threshold. Then, all access to the backend is rejected for a (configurable) time duration. No further calls are permitted.

After the time duration has elapsed, the CircuitBreaker state changes from OPEN to HALF_OPEN and allows a number of calls to see if the backend is still unavailable or has become available again. If the failure rate is greater than or equal to the configured threshold, the state changes back to OPEN. If the failure rate is below or equal to the threshold, the state changes back to CLOSED.

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static enum	CircuitBreaker.State

Method Summary

Modifier and Type	Method	Description
<T> T	accept(Callable<T> callable)	Try to acquire CircuitBreaker and return result from Supplier or throws CallNotPermittedException if not acquired or fails with exception from Supplier if it occurred there
<T> T	accept(Callable<T> callable, Callable<T> fallback)	Try to acquire CircuitBreaker and return result from Supplier or result from Supplier fallback or fails with exception from Supplier if it occurred there
void	acquire()	Try to obtain a permission to execute a call.
void	releaseOnError(Throwable throwable)	Records a failed call.
void	releaseOnSuccess()	Records a successful call.
boolean	tryAcquire()	Try to obtain a permission to execute a call.

Method Details

accept

<T> T accept(@Nonnull
 Callable<T> callable)
      throws CallNotPermittedException,
CallException

Try to acquire CircuitBreaker and return result from Supplier or throws CallNotPermittedException if not acquired or fails with exception from Supplier if it occurred there

Type Parameters:

T - type of result

Parameters:

callable - to accept to execute for result

Returns:

result after tryAcquire() was successful or throws CallNotPermittedException

Throws:

CallNotPermittedException - when can't acquire

CallException - wraps callable exception if occurred

accept

<T> T accept(@Nonnull
 Callable<T> callable,
 @Nonnull
 Callable<T> fallback)
      throws CallFallbackException,
CallException

Try to acquire CircuitBreaker and return result from Supplier or result from Supplier fallback or fails with exception from Supplier if it occurred there

Type Parameters:

T - type of result

Parameters:

callable - to accept to execute for result

fallback - to execute if tryAcquire() failed

Returns:

result after tryAcquire() was successful or return fallback result

Throws:

CallException - wraps callable exception if occurred

CallFallbackException - wraps fallback callable exception if occurred

tryAcquire

boolean tryAcquire()

Try to obtain a permission to execute a call. If a call is not permitted, the number of not permitted calls is increased.

Throws a CallNotPermittedException when the state is OPEN or FORCED_OPEN. Returns when the state is CLOSED or DISABLED. Returns when the state is HALF_OPEN and further test calls are allowed. Throws a CallNotPermittedException when the state is HALF_OPEN and the number of test calls has been reached. If the state is HALF_OPEN, the number of allowed test calls is decreased. Important: Make sure to call onSuccess or onError after the call is finished. If the call is cancelled before it is invoked, you have to release the permission again.

Returns:

false when CircuitBreaker is OPEN or HALF_OPEN and no further test calls are permitted.

acquire

void acquire()
      throws CallNotPermittedException

Try to obtain a permission to execute a call. If a call is not permitted, the number of not permitted calls is increased.

Throws a CallNotPermittedException when the state is OPEN or FORCED_OPEN. Returns when the state is CLOSED or DISABLED. Returns when the state is HALF_OPEN and further test calls are allowed. Throws a CallNotPermittedException when the state is HALF_OPEN and the number of test calls has been reached. If the state is HALF_OPEN, the number of allowed test calls is decreased. Important: Make sure to call onSuccess or onError after the call is finished. If the call is cancelled before it is invoked, you have to release the permission again.

Throws:

CallNotPermittedException - when CircuitBreaker is OPEN or HALF_OPEN and no further test calls are permitted.

releaseOnSuccess

void releaseOnSuccess()

Records a successful call. This method must be invoked when a call was successful.

releaseOnError

void releaseOnError(@Nonnull
 Throwable throwable)

Records a failed call. This method must be invoked when a call failed.

Parameters:

throwable - The throwable which must be recorded