alexpanov / retries

Forget about your retry boilerplate

Retries

You need to make a call that may fail. You need to wait for a value that meets your criteria. You write your own retry boilerplate. Why? Throw it away. You need not to support it anymore.

Motivation

Have you ever written a retry/wait code that looks like this?

private String computeWithRetries() {
    int numberOfTries = 10;
    int sleepTimeout = 1000; // one sec
    for (int i = 0; i < numberOfTries; i++) {
        try {
            String value = computeValue();
        } catch (Exception e) {
            try {
                Thread.sleep(sleepTimeout);
            } catch (InterruptedException ie) {
                ie.printStackTrace();
            }
            continue;
        }
        if (value != null && !value.startsWith("B")) {
            return value;
        }
    }
    throw new RuntimeException("Could not compute anything");
}

Ugh. That's terrible and you know it. It's hard to figure out what's going on, hard to extend, hard to reuse and easy to get it wrong. Luckily, there is an alternative.

Build tools

Add retries to your dependencies. Note that Guava is automatically added too.

Maven:

<dependency>
    <groupId>me.alexpanov</groupId>
    <artifactId>retries</artifactId>
    <version>0.0.3</version>
</dependency>

Gradle:

compile "me.alexpanov:retries:0.0.3"

Getting started

Create a retryable:

//Nasty call that returns so much nulls
Retryable<String> retryable = new Retryable<String>() {
            @Override
            public String tryOnce() throws Exception {
                return null;
            }
        };

One call, one failure, RetryException is thrown

String resultAfterRetries = new Retries<String>(retryable).stopOnMaxFailures(1).perform();

Code above will throw a subclass of RetryException:

me.alexpanov.retries.FailedToComputeAValueException

Same thing asynchronously, java.util.concurrent.ExecutionException is thrown

Future<String> resultAfterRetries = new Retries<String>(retryable).stopOnMaxFailures(1).performAsync();
String result = resultAfterRetries.get();

Code above will throw an ExecutionException with a subclass of RetryException as a cause:

me.alexpanov.retries.FailedToComputeAValueException

One call, one failure, default value is returned

String resultAfterRetries = new Retries<String>(retryable).stopOnMaxFailures(1)
                                                          .orElse("default value")
                                                          .perform();
resultAfterRetries.equals("default value"); //true

Several calls, configured wait timeout

String resultAfterRetries = new Retries<String>(retryable).stopOnMaxFailures(10)
                                                          .waitAfterFailureAtLeast(10, TimeUnit.SECONDS)
                                                          .orElse("default value")
                                                          .perform();

Ignoring results

Predicate<String> startsWithLetterB = new Predicate<String>() {
            @Override
            public boolean apply(String input) {
                return input.startsWith("B");
            }
        };
String resultAfterRetries = new Retries<String>(retryable).stopOnMaxFailures(2)
                                                          .ignoreIfResult(startsWithLetterB)
                                                          .perform();

Subscribing to failures for logging etc.

FailureSubscriber<String> logTheError = new FailureSubscriber<String>() {
            @Override
            public void onFailure(RetryFailure<String> details) {
                LOG.info("Failure");
            }
        };
String resultAfterRetries = new Retries<String>(retryable).stopOnMaxFailures(10)
                                                          .onEachFailureDo(logTheError)
                                                          .perform();

The code above will append a log message each time a call failed (exception, null or skipped result).

But what about my Callable(s)!?

I got you covered, man.

Retryable<String> retryable = new CallableToRetryable<String>(yourCallable);

Licence

The Apache Software License, Version 2.0

Issues

Please feel free to add any issues regarding new functionality, improvements etc. in the Issues section

retries's Issues

Add JavaDoc to all public APIs

Timeout is not used when result is rejected

This test fails:

    @Test
    public void shouldWaitAfterResultNotMatched() throws Exception {
        int numberOfRetries = 100;
        int timeout = 2;
        String dumbData = "hello";
        Retries<String> retries = new Retries<String>(alwaysReturn(dumbData)).stopOnMaxFailures(numberOfRetries)
                                                                             .ignoreIfResult(containsPattern(dumbData))
                                                                             .waitAfterFailureAtLeast(timeout,
                                                                                                      MILLISECONDS);
        Stopwatch stopwatch = Stopwatch.createStarted();
        retries.perform();
        assertThat(stopwatch.stop().elapsed(MILLISECONDS)).isGreaterThanOrEqualTo(numberOfRetries * timeout);
    }

    private Retryable<String> alwaysReturn(final String dumbData) {
        return new Retryable<String>() {
            @Override
            public String tryOnce() throws Exception {
                return dumbData;
            }
        };
    }

Add futures support

Callable wrapper

To allow users to migrate their existing code, a callable to retryable bridge has to be provided:

Retryable<String> retryable = new CallableToRetryable(callable);

Release to maven central