1 package net.secodo.jcircuitbreaker.breaker; 2 3 import java.util.concurrent.Callable; 4 import net.secodo.jcircuitbreaker.breaker.execution.ExecutionContext; 5 import net.secodo.jcircuitbreaker.breakhandler.BreakHandler; 6 import net.secodo.jcircuitbreaker.breakhandler.exception.BreakHandlerException; 7 import net.secodo.jcircuitbreaker.breakstrategy.BreakStrategy; 8 import net.secodo.jcircuitbreaker.exception.CircuitBreakerException; 9 import net.secodo.jcircuitbreaker.exception.TaskExecutionException; 10 import net.secodo.jcircuitbreaker.task.Task; 11 12 13 /** 14 * This interface defines the circuit breaker contract. 15 * 16 * <p>For details refer to comments on methods. 17 * 18 * @param <R> the return value that the breaker returns (if breaker wants to return any value) 19 */ 20 public interface CircuitBreaker<R> { 21 /** 22 * Executes the given {@link Callable} only when given {@link BreakStrategy} allows the execution at the time of call. 23 * If execution is not allowed {@link BreakHandler} is used to handle this situation and return fallback value. 24 * 25 * @param task encapsulates java method to be executed - called <i>target-method</i> in this context 26 * @param breakStrategy decides whether to execute the task or prevent execution and executed breakHandler instead 27 * @param breakHandler handles the situation when the strategy does not allow method execution 28 * @return the return value of the executed task or the fallback value returned by breakHandler in case of 29 * execution of method did not take place 30 * @throws TaskExecutionException if execution of task resulted in exception 31 * @throws BreakHandlerException if breakHandler (if executed) could not provide the fallback value 32 * @throws CircuitBreakerException if unexpected problem occurred while processing the task within CircuitBreaker 33 */ 34 default R execute(Task<R> task, BreakStrategy<R> breakStrategy, BreakHandler<R> breakHandler) 35 throws TaskExecutionException, BreakHandlerException, CircuitBreakerException { 36 return execute(task, breakStrategy, breakHandler, null); 37 } 38 39 40 /** 41 * Executes the given {@link Callable} only when given {@link BreakStrategy} allows the execution at the time of call. 42 * If execution is not allowed {@link BreakHandler} is used to handle this situation and return fallback value. 43 * <p> 44 * Allows to pass some custom data to the strategy which will be available via {@link ExecutionContext#getUserData()} 45 * 46 * @param task encapsulates java method to be executed - called <i>target-method</i> in this context 47 * @param breakStrategy decides whether to execute the task or prevent execution and executed breakHandler instead 48 * @param breakHandler handles the situation when the strategy does not allow method execution 49 * @param userData custom user data which will be available to strategies via 50 * {@link ExecutionContext#getUserData()} 51 * @param <U> the type of user data passed to execution context 52 * @return the return value of the executed task or the fallback value returned by breakHandler in case of 53 * execution of method did not take place 54 * @throws TaskExecutionException if execution of task resulted in exception 55 * @throws BreakHandlerException if breakHandler (if executed) could not provide the fallbackvalue 56 * @throws CircuitBreakerException if the method execution resulted in exception or breakHandler resulted in exception 57 */ 58 <U> R execute(Task<R> task, BreakStrategy<R> breakStrategy, BreakHandler<R> breakHandler, 59 U userData) throws TaskExecutionException, BreakHandlerException, CircuitBreakerException; 60 61 }