README.md

Recurrent

Simple, sophisticated retries.

Introduction

Recurrent is a simple, zero-dependency library for performing retries. It features:

• Zero external dependencies
• Synchronous and asynchronous retries
• Transparent integration into existing APIs
• Java 6/7/8 supported with Java 8 friendly functional interfaces
• Simple integration with asynchronous libraries

Usage

Retry Policies

Recurrent supports flexible retry policies that allow you to express the number of retries, delay between attempts, delay between attempts including backoff, and maximum duration:

RetryPolicy retryPolicy = new RetryPolicy()
	.withBackoff(1, 30, TimeUnit.SECONDS)
	.withMaxRetries(100);

Synchronous Retries

Synchronous invocations are performed and retried in the calling thread until the invocation succeeds or the retry policy is exceeded:

Connection connection = Recurrent.withRetries(() -> connect(), retryPolicy);

Asynchronous Retries

Asynchronous invocations are performed and retried on a scheduled executor. When the invocation succeeds or the retry policy is exceeded, the resulting ListenableFuture is completed and any CompletionListeners registered against it are called:

Recurrent.withRetries(() -> connect(), retryPolicy, executor)
  .whenComplete((connection, failure) -> {
    if (connection != null)
      log.info("Connection established");
    else
      log.error("Connection attempts failed", failure);
  });

Integrating with Asynchronous Code

Asynchronous code often reports failures via callbacks rather than throwing an exception. Recurrent provides nice integration with asynchronous code by allowing you to manually trigger retries as necessary:

Recurrent.withRetries((invocation) -> {
  someService.connect(host, port).addListener((connection, failure) -> {
    if (connection != null)
      log.info("Connection established");
    else if (!invocation.retry())
      log.error("Connection attempts failed", failure)
    }
  }, retryPolicy, eventLoopGroup));

Notes

On API Integration

A great way to add support for retries to your project's public API is to subclass the RetryPolicy class. This can allow you to offer retry support and policies to your users while keeping Recurrent hidden.

Docs

JavaDocs are available here.

License

Copyright 2015 Jonathan Halterman - Released under the Apache 2.0 license.