Sarge

Simple object supervision (for when stuff goes wrong)

Sarge creates supervised objects which automatically handle failures when they occur by performing retries, state resets, and failure escalation, allowing for easy and robust fault tolerance with little effort.

Usage

Sarge handles failures according to a Plan which takes an exception and directs Sarge to do something with it. Creating a Plan is straightforward:

Plan plan = Plans
  .retryOn(TimeoutException.class, 5, Duration.mins(1))
  .escalateOn(ConnectionClosedException.class)
  .rethrowOn(IllegalArgumentException.class, IllegalStateException.class)
  .make();

This Plan retries any method invocations that fail with a TimeoutException, escalates any ConnectionClosedExceptions, and rethrows any IllegalArgumentExceptions and IllegalStateExceptions.

Supervision

With our Plan in hand, we can create a supervised object:

Sarge sarge = new Sarge();
MailService service = sarge.supervised(MailService.class, plan);

Supervision is automatically applied according to the plan when any exception occurs while invoking a method against the object:

// Failures are handled according to the plan
service.sendMail();

Hierarchical supervision

Sarge can create a parent/child supervision hierarchy where the Supervisor's plan is applied to any failures that occur in the child:

class Parent implements Supervisor {
  @Override
  public Plan plan(){
    return Plans
      .retryOn(TimeoutException.class, 5, Duration.mins(1))
      .escalateOn(ConnectionClosedException.class)
      .make();
  }
}
 
Parent parent = new Parent(); 
Sarge sarge = new Sarge();
 
// Create a new Child that is supervised by the parent
Child child = sarge.supervised(Child.class, parent);

We can link additional supervisable objects into a parent-child supervision hierarchy, which will handle any failures that are escalated:

Parent parent = sarge.supervisable(Parent.class);
sarge.supervise(parent, uberParent);

More on plans

Aside from the Plans class, Plans can also be constructed directly by implementing the Plan interface and returning the desired Directive for handling each failure:

Plan plan = new Plan() {
  public Directive apply(Throwable cause) {
    if (cause instanceof TimeoutException)
      return Directive.Retry(5, Duration.min(1));
    if (cause instanceof ConnectionClosedException)
      return Directive.Escalate;
  }
};

Lifecycle hooks

Lifecycle hooks allow supervised objects to be notified prior to a supervision directive being carried out, allowing an object to reset its internal state if necessary:

class SupervisedService implements PreRetry {
  @Override
  public void preRetry(Throwable reason) {
    if (reason instanceof ConnectionClosedException)
      connect();
  }
}

3rd Party Integration

By default, supervised objects must be instantiated by Sarge since they require instrumentation. As an alternative, we can delegate instantiation of supervised objects to other libraries such as Spring or Guice by hooking into Sarge's SupervisedInterceptor. Have a look at the tests for examples on how to integrate 3rd party libraries.

Logging

Logging is provided via the slf4j API. Invocation exceptions are logged at the ERROR level and include only the exception message. Full exception logging can be enabled by setting the DEBUG log level for the net.jodah.sarge category.

Docs

JavaDocs are available here.

Limitations

Since Sarge relies on runtime bytecode generation to create supervised objects by subclassing them, it cannot supervise classes that are final, protected or private, or methods that are final or private.

Thanks

Sarge was inpsired by Erlang OTP's supervision trees and Akka's supervision implementation. Thanks to the their contributors for the great work.

jhalterman/sarge

jhalterman

Reviews

Repository Details