Руководство пользователя

Фон

Проект содержит множество сценариев, требующих повторных попыток. Каждый раз приходится писать следующую логику:

for (int i=0;i++;i<retry){
    try{
        do(//логическая часть кода);
        if(success){
          break;
        }
    }catch(Exception e){
    }
}

Такой подход приводит к следующим проблемам:

• необходимость написания аналогичных управляющих операторов для каждой повторной попытки, что приводит к избыточности кода;
• смешение бизнес-логики и логики управления;
• фиксированное количество повторных попыток, затрудняющее динамическое управление.

Этот компонент предлагает унифицированное решение для этой простой, но неудобной проблемы.

Быстрый старт

Самый простой способ использования:

new RetryBuilder().build().proceed((round, nanos) -> "success");

С дополнительными параметрами управления:

new RetryBuilder()
  .retry(10)
  .delay(1000)
  .timeout(5000)
  .pool(Executors.newSingleThreadExecutor())
  .build()
  .async((round, nanos) -> "success");

В форме обратного вызова:

new RetryBuilder()
  .build()
  .proceed(
      new Retryable<Integer>() {
          @Override
          public Integer proceed(int round, long nanos) {
              logger.info("success");
              return 1;
          }

          @Override
          public Integer whenFinish(Integer ret, int round, long nanos) {
              logger.info("finish");
              return 999;
          }

          @Override
          public boolean postCondition(Integer ret, int round, long nanos) {
              logger.info(round + "");
              return true;
          }

          @Override
          public boolean preCondition(int round, long nanos) {
              return true;
          }
      });

Без обратного вызова:

Class[] failOn = {IllegalAccessException.class};
Class[] continueOn = {IllegalArgumentException.class};
new RetryBuilder()
    .withCondition()
    .failOn(failOn)
    .continueOn(continueOn)
    .build()
    .proceed(() -> "success");

Обратите внимание: new RetryBuilder().build() создаёт RetryLoop, который не является потокобезопасным.

Описание параметров RetryBuilder

Параметры:

• retry — количество повторных попыток (по умолчанию: 1);
• delay — интервал между повторными попытками (по умолчанию: 0);
• timeout — время ожидания выполнения (не поддерживается в режиме proceed) (по умолчанию: FOREVER);
• pool — пользовательский пул потоков (по умолчанию: глобальный уникальный CachedThreadPool);
• timeoutPolice — стратегия остановки при превышении времени ожидания. SetFlag: только устанавливает флаг, поток должен завершить один цикл перед выходом. InterruptAndSetFlag: вызывает прерывание и устанавливает флаг (по умолчанию: InterruptAndSetFlag).

Обратные вызовы (действуют в форме обратного вызова):

• whenError — обратный вызов при возникновении исключения в процессе повторной попытки и возвращает, нужно ли выйти из цикла;
• whenFinish — обратный вызов после успешного завершения всего процесса повторной попытки;
• postCondition — обратный вызов после завершения каждого цикла повторной попытки;
• preCondition — обратный вызов перед каждым выполнением;
• whenTimeout — обратный вызов при превышении времени ожидания повторной попытки, после чего whenFinish больше не вызывается.

Об исключениях

Исключения в whenError будут проигнорированы, а исключения в postCondition, preCondition и методе proceed будут преобразованы в ProceedException. Исключения в whenFinish будут выброшены напрямую.

Условия (действительны в форме условия):

• withCondition — переход в форму условия;
• failOn — условие сбоя цикла;
• continueOn — условие продолжения цикла.

[Две формы: обратный вызов|условие](doc/две формы.md)

[Три режима выполнения: proceed|sync|async](doc/три режима.md)

[Интеграция со Spring](doc/интеграция с spring.md)

Планы на будущее

• Интеграция со Spring, запуск с использованием аннотаций (завершено);
• Разделение по сервисам для реализации механизма автоматического переключения при отказе (в планах);
• Поддержка dashboard для отображения информации о неудачных попытках повторных действий (в разработке).