View Javadoc
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  }