Spring Breaker

@CircuitBreaker annotation

As the name implies, @CircuitBreaker is used to demarcate methods that are to be wrapped in circuit breaker logic. In its simplest form, the annotation declaration requires the name of the circuit breaker associated with the annotated method:

@CircuitBreaker(name = "FindBookGuard")
public Book findBook(ISBN isbn) {...}

In the snippet above, the method findBook is transparently wrapped in circuit breaker logic. Each time the method is called, the method invocation is passed to the circuit manager implementation and executed accordingly.

@CircuitProperty annotation

For cases where the circuit manager can be passed some configuration information about the circuit breaker, one can use the @CircuitProperty annotation. This annotation provides key/value semantics. Each will be resolved to map entries that are available to the circuit manager at execution time.

Enable circuit breaker annotations

It is important to note that declaring the circuit breaker annotations does not automatically triggers their actions - like many things in Spring. The feature has to be declaratively enabled (which means if you ever suspect circuit breaker is to blame, you can disable it by removing only one configuration line rather then all the annotations in your code).

To enable circuit breaker annotations add the annotation @EnableCircuitBreakers to one of your @Configuration classes:

@Configuration
@EnableCircuitBreakers
public class AppConfig {

}

Alternatively for XML configuration use the breaker:annotation-driven element:

<beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:breaker="http://www.developmentsprint.com/schema/spring/breaker"
    xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
        http://www.developmentsprint.com/schema/spring/breaker http://www.developmentsprint.com/schema/spring/breaker.xsd">
    <breaker:annotation-driven />
</beans>

Both the breaker:annotation-driven element and @EnableCircuitBreakers annotation allow various options to be specified that influence the way the circuit breaker behavior is added to the application through AOP. The configuration is intentionally similar with that of @Transactional:

CircuitBreaker annotation settings

Note <breaker:annotation-driven /> only looks for @CircuitBreaker on beans in the same application context it is defined in. This means that, if you put <breaker:annotation-driven /> in a WebApplicationContext for a DispatcherServlet, it only checks for @CircuitBreaker beans in your controllers, and not your services. See Section 17.2, “The DispatcherServlet” for more information.

Method visibility and @CircuitBreaker When using proxies, you should apply the @CircuitBreaker annotations only to methods with public visibility. If you do annotate protected, private or package-visible methods with these annotations, no error is raised, but the annotated method does not exhibit the configured circuit breaker settings. Consider the use of AspectJ (see below) if you need to annotate non-public methods as it changes the bytecode itself.

Tip Spring recommends that you only annotate concrete classes (and methods of concrete classes) with the @CircuitBreaker annotation, as opposed to annotating interfaces. You certainly can place the @CircuitBreaker annotation on an interface (or an interface method), but this works only as you would expect it to if you are using interface-based proxies. The fact that Java annotations are not inherited from interfaces means that if you are using class-based proxies (proxy-target-class=“true”) or the weaving-based aspect (mode=“aspectj”), then the circuit breaker settings are not recognized by the proxying and weaving infrastructure, and the object will not be wrapped in a circuit breaker proxy, which would be decidedly bad.

Note In proxy mode (which is the default), only external method calls coming in through the proxy are intercepted. This means that self-invocation, in effect, a method within the target object calling another method of the target object, will not lead to an actual circuit breaker at runtime even if the invoked method is marked with @CircuitBreaker - considering using the aspectj mode in this case.

Using custom annotations

The circuit breaker abstraction allows one to use her own annotations to identify what method trigger circuit breaker behavior. This is quite handy as a template mechanism as it eliminates the need to duplicate annotation declarations or if the foreign imports are not allowed in your code base. Similar to the rest of the stereotype annotations, @CircuitBreaker can be used as a meta-annotation, that is an annotation that can annotate other annotations. To wit, let us replace a common @CircuitBreaker declaration with our own, custom annotation:

@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.METHOD})
@CircuitBreaker(commandName = "SlowServiceBreaker", properties = {
    @CircuitProperty(key = "fallbackClass", value = "com.foo.bar.Fallback")
})
public @interface SlowService {
}

Above, we have defined our own SlowService annotation which itself is annotated with @CircuitBreaker - now we can replace the following code:

@CircuitBreaker(commandName = "SlowServiceBreaker", properties = {
    @CircuitProperty(key = "fallbackClass", value = "com.foo.bar.Fallback")
})
public Book findBook(ISBN isbn, boolean checkWarehouse, boolean includeUsed)

with:

@SlowService
public Book findBook(ISBN isbn, boolean checkWarehouse, boolean includeUsed)

Even though @SlowService is not a Spring annotation, the container automatically picks up its declaration at runtime and understands its meaning. Note that as mentioned above, the annotation-driven behavior needs to be enabled.

Netflix Hystrix-based Circuit Breaker

The Hystrix-based CircuitManager implementation resides under com.developmentsprint.spring.breaker.hystrix package. It allows one to use HystrixCommand as the core circuit breaker class.

<!-- Hystrix circuit breaker manager -->
<bean id="circuitManager" class="com.developmentsprint.spring.breaker.hystrix.HystrixCircuitManager">
</bean>

The snippet above uses the HystrixCircuitManager to create a CircuitManager. According to Netflix’s own information, the circuit breaker provides massive resiliency. There are many properties that can be set on the circuit breaker declarations that will get passed on to the Hystrix system. For a full list see https://github.com/Netflix/Hystrix/wiki/Configuration#command-properties.

@CircuitBreaker(properties = {
    @CircuitProperty(key = "execution.isolation.strategy", value = "SEMAPHORE"),
    @CircuitProperty(key = "execution.isolation.semaphore.maxConcurrentRequests", value = "10")
})
public Object slowMethod() {
    // ...
    return null;
}

In the example above, the citcuit breaker is configured to use semaphore based execution isolation with a maximum number of concurrent requests of 10. These settings are described futher here and here, respectively.

Dealing with circuit breakera without a backing circuit manager

Sometimes when switching environments or doing testing, one might have circuit breaker declarations without an actual backing circuit manager configured. As this is an invalid configuration, at runtime an exception will be thrown since the circuit braeker infrastructure is unable to find a suitable circuit manager. In situations like this, rather then removing the circuit breaker declarations (which can prove tedious), one can wire in a simple, dummy circuit manager that performs no circuit breaking - that is, it passes through to the uderlying methods to be executed every time:

<bean id="circuitManager" class="com.developmentsprint.spring.breaker.support.CompositeCircuitManager">
    <property name="circuitManagers"><list>
        <ref bean="histrixManager"/>
        <ref bean="customManager"/>
    </list></property>
    <property name="fallbackToNoOpCircuitManager" value="true"/>
</bean>

The CompositeCircuitManager above chains multiple CircuitManagers and additionally, through the fallbackToNoOpCircuitManager flag, adds a no op circuit manager that for all the definitions not handled by the configured circuit managers. That is, every circuit breaker definition not found in either histrixManager or customManager (configured above) will be handled by the no op circuit manager.

Plugging-in different circuit breaker implementations {#plugging-in-circuit-breaker-implementations}

There are a few circuit breaker implementations out there that can be used as a circuit manager. To plug them in, one needs to provide a CircuitManager and circuit breaker implementation since unfortunately there is no available standard that we can use instead. This may sound harder then it is since in practice. Theese classes tend to be simple adapters that map the circuit breaker abstraction framework on top of the circuit breaker implementation’s API as the Hystrix classes demonstrate. In time, the libraries that provide integration with Spring can fill in this small configuration gap.