Writing Client Applications

Pivotal Web Services End of Availability Announced
For more information, see Frequently Asked Questions.

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

To use a circuit breaker in a Spring app with a Circuit Breaker Dashboard service instance, you must add the dependencies listed in Client Dependencies to your app’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 app must include the @EnableCircuitBreaker annotation on a configuration class.

@SpringBootApplication
@EnableDiscoveryClient
@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 rest.getForObject("https://company/available", String.class);
  }

The getGuide() method uses a RestTemplate to obtain a guide name from another app called Company, which is registered with a Service Registry instance. (See the Service Registry documentation, specifically Writing Client Applications.) The method thus relies on the Company app to return a response, and if the Company app 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 app, 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

If you want to use the Spring Cloud OpenFeign support for Hystrix circuit breakers, you must set the feign.hystrix.enabled property to true. In the Feign version of the Agency app, this property is configured in application.yml:

feign:
  hystrix:
    enabled: true

To provide a circuit breaker on a Feign client, you must specify a fallback class using a fallback attribute in the @FeignClient annotation on the client interface. Fallback methods must be Spring beans. In the Feign version of the Agency app, the CompanyClient interface uses a CompanyFallback class, which is annotated with @Component:

@FeignClient(name = "company", fallback = CompanyClient.CompanyFallback.class)
public interface CompanyClient {
  @RequestMapping(method = GET, value="/available")
  String availableGuide();

@Component
  public static class CompanyFallback implements CompanyClient {
    @Override
    public String availableGuide() {
      return "None available!";
    }
  }
}

The AgencyApplication class is annotated with @EnableFeignClients:

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

If the Company app becomes unavailable or if the Agency app cannot access it, calls to the Company app through the client’s availableGuide() method will fail. When successive failures build up to the threshold, Hystrix will open the circuit, and subsequent calls will be redirected to the fallback class’s method until the Company app is accessible again and the circuit is closed.