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.


Comments