Spring Boot @RefreshScope Example

1. Introduction

In the dynamic world of microservices, it’s essential to have a mechanism to refresh configuration properties on-the-fly. Spring Boot's @RefreshScope annotation provides just that. It marks Spring beans as eligible for refreshing when the configuration is updated. This feature is often used in conjunction with a centralized configuration management service like Spring Cloud Config. In this blog post, we'll walk through an example demonstrating @RefreshScope in action.

Key Points:

1. @RefreshScope makes it possible to refresh beans in the application context without restarting the application.

2. It is commonly used for updating configuration properties at runtime from a configuration management service.

3. When a refresh event is triggered, all beans annotated with @RefreshScope will have their configurations reloaded.

4. This approach minimizes downtime and avoids the need for a full application restart just to update properties.

5. Spring Cloud's /actuator/refresh endpoint is typically used to trigger a refresh event.

2. Implementation Steps

1. Add Spring Cloud dependencies and setup Spring Cloud Config if not already configured.

2. Create a configuration properties class and annotate it with @ConfigurationProperties.

3. Annotate the configuration properties class or any other bean that you want to be refreshable with @RefreshScope.

4. Expose the /actuator/refresh endpoint by adding the Spring Boot actuator dependency and setting the appropriate properties.

5. Trigger a refresh event to update the @RefreshScope beans after updating the configuration in the config server.

3. Implementation Example

// Step 1: Add dependencies for Spring Cloud Config and Spring Boot Actuator in your build file

// Step 2: Create a configuration properties class
@ConfigurationProperties(prefix = "greeting")
public class GreetingProperties {
    private String message = "Hello, World!";

    // Getters and setters
}

// Step 3: Annotate the configuration properties class with @RefreshScope
@RefreshScope
@ConfigurationProperties(prefix = "greeting")
public class GreetingProperties {
    // ...
}

// Step 4: Create a REST controller to expose the greeting message
@RestController
public class GreetingController {

    private final GreetingProperties greetingProperties;

    public GreetingController(GreetingProperties greetingProperties) {
        this.greetingProperties = greetingProperties;
    }

    @GetMapping("/greet")
    public String greet() {
        return greetingProperties.getMessage();
    }
}

// Step 5: Setup application properties for actuator and the config client
/*
spring.cloud.config.uri=http://localhost:8888
management.endpoints.web.exposure.include=refresh
*/

// Step 6: Enable the actuator refresh endpoint and run the application
@SpringBootApplication
public class RefreshScopeExampleApplication {

    public static void main(String[] args) {
        SpringApplication.run(RefreshScopeExampleApplication.class, args);
    }
}

// Use POST to the /actuator/refresh endpoint to trigger a refresh event
// curl -X POST http://localhost:8080/actuator/refresh

Output:

// Before the refresh, hitting the /greet endpoint will return:
Hello, World!
// After the refresh, if the message property has been updated in the config server, hitting the /greet endpoint will return the new message, for example:
Hello, Spring!

Explanation:

1. @ConfigurationProperties: This annotation binds the greeting.message property from the configuration file to the GreetingProperties class.

2. @RefreshScope: Marks the GreetingProperties class as eligible for refreshing when a refresh event is triggered.

3. GreetingController: A standard Spring MVC REST controller that responds with the current greeting message.

4. management.endpoints.web.exposure.include: Property in application.properties that exposes the /actuator/refresh endpoint.

5. @SpringBootApplication: Marks the application's entry point and configures Spring Boot auto-configuration, component scanning, etc.

6. @GetMapping: Annotation that maps the HTTP GET requests to the greet method in GreetingController.

7. curl -X POST http://localhost:8080/actuator/refresh: The curl command is used to trigger a refresh event.

8. SpringApplication.run(): Starts the Spring Boot application, including the actuator endpoints and the configuration client connected to the config server.