Writing Client Applications

Refer to the sample applications in the “traveler” repository to follow along with the code in this topic.

To use a circuit breaker in a Spring application with a Circuit Breaker Dashboard service instance, you must add the dependencies listed in the Client Dependencies topic to your application’s build file. Be sure to include the dependencies for Circuit Breaker Dashboard as well.

Use a Circuit Breaker

To work with a Circuit Breaker Dashboard instance, your application must include the @EnableCircuitBreaker annotation on a configuration class.

import org.springframework.cloud.client.circuitbreaker.EnableCircuitBreaker;
//...

@SpringBootApplication
@EnableDiscoveryClient
@RestController
@EnableCircuitBreaker
public class AgencyApplication {
    //...

To apply a circuit breaker to a method, annotate the method with @HystrixCommand, giving the annotation the name of a fallbackMethod.

    @HystrixCommand(fallbackMethod = "getBackupGuide")
    public String getGuide() {
        return restTemplate.getForObject("http://company/available", String.class);
    }

The getGuide() method uses a RestTemplate to obtain a guide name from another application called Company, which is registered with a Service Registry instance. (See the Service Registry documentation, specifically the Writing Client Applications topic.) The method thus relies on the Company application to return a response, and if the Company application fails to do so, calls to getGuide() will fail. When the failures exceed the threshold, the breaker on getGuide() will open the circuit.

While the circuit is open, the breaker redirects calls to the annotated method, and they instead call the designated fallbackMethod. The fallback method must be in the same class and have the same method signature (i.e., have the same return type and accept the same parameters) as the annotated method. In the Agency application, the getGuide() method on the TravelAgent class falls back to getBackupGuide().

    String getBackupGuide() {
        return "None available! Your backup guide is: Cookie";
    }

If you wish, you may also annotate fallback methods themselves with @HystrixCommand to create a fallback chain.

Use a Circuit Breaker with a Feign Client

You cannot apply @HystrixCommand directly to a Feign client interface at this time. Instead, you can call Feign client methods from a service class that is autowired as a Spring bean (either through the @Service or @Component annotations or by being declared as a @Bean in a configuration class) and then annotate the service class methods with @HystrixCommand.

In the Feign version of the Agency application, the AgencyApplication class is annotated with @EnableFeignClients.

//...
import org.springframework.cloud.netflix.feign.EnableFeignClients;

@SpringBootApplication
@EnableDiscoveryClient
@RestController
@EnableCircuitBreaker
@EnableFeignClients
public class AgencyApplication {
    // ...

The application has a Feign client called CompanyClient.

package agency;

import org.springframework.stereotype.Component;
import org.springframework.cloud.netflix.feign.FeignClient;
import org.springframework.web.bind.annotation.RequestMapping;

import static org.springframework.web.bind.annotation.RequestMethod.GET;

@FeignClient("https://company")
interface CompanyClient {
  @RequestMapping(value="/available", method = GET)
  String availableGuide();
}

The TravelAgent class is annotated as a @Service class. The CompanyClient class is injected through autowiring, and the getGuide() method uses the CompanyClient to access the Company application. @HystrixCommand is applied to the service method:

package agency;

import org.springframework.stereotype.Service;
import org.springframework.beans.factory.annotation.Autowired;

import com.netflix.hystrix.contrib.javanica.annotation.HystrixCommand;

@Service
public class TravelAgent {

    @Autowired
    CompanyClient company;

    @HystrixCommand(fallbackMethod = "getBackupGuide")
    public String getGuide() {
        return company.availableGuide();
    }

    String getBackupGuide() {
        return "None available! Your backup guide is: Cookie";
    }

}

If the Company application becomes unavailable or if the Agency application cannot access it, calls to getGuide() will fail. When successive failures build up to the threshold, Hystrix will open the circuit, and subsequent calls will be redirected to the getBackupGuide() method until the Company application is accessible again and the circuit is closed.