Creating a Custom Auto-Configuration with Spring Boot

Auto-configuration in Spring Boot makes it easy to configure your application based on the libraries on the classpath. Custom auto-configuration allows you to bundle and distribute your configuration for reuse in multiple applications. This tutorial will guide you through creating a custom auto-configuration with Spring Boot step-by-step.

Prerequisites

• JDK 17 or later
• Maven or Gradle
• IDE (IntelliJ IDEA, Eclipse, etc.)

Step 1: Set Up the Custom Auto-Configuration Project

1.1 Create a New Maven Project

You can create a new Maven project using your IDE or by using the Spring Initializr. For this example, we will set up the project manually.

1.1.1 Directory Structure

Create the following directory structure for your custom auto-configuration:

custom-auto-configuration
├── src
│   ├── main
│   │   ├── java
│   │   │   └── com
│   │   │       └── example
│   │   │           └── autoconfig
│   │   │               ├── CustomAutoConfiguration.java
│   │   │               ├── CustomProperties.java
│   │   │               └── CustomService.java
│   │   ├── resources
│   │       └── META-INF
│   │           └── spring.factories
├── pom.xml

1.2 Create pom.xml

Create the pom.xml file for your custom auto-configuration project.

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.example</groupId>
    <artifactId>custom-auto-configuration</artifactId>
    <version>1.0.0</version>
    <packaging>jar</packaging>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.2.0</version>
    </parent>

    <dependencies>
        <!-- Spring Boot Auto-Configuration -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-autoconfigure</artifactId>
        </dependency>
        <!-- Spring Boot Starter -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter</artifactId>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

Explanation:

• The project inherits from spring-boot-starter-parent.
• It includes spring-boot-autoconfigure and spring-boot-starter dependencies.

Step 2: Create the Custom Auto-Configuration

2.1 Create CustomProperties.java

Define a properties class to hold custom configuration properties.

package com.example.autoconfig;

import org.springframework.boot.context.properties.ConfigurationProperties;

@ConfigurationProperties(prefix = "custom.service")
public class CustomProperties {

    private String message = "Hello from Custom Service!";

    public String getMessage() {
        return message;
    }

    public void setMessage(String message) {
        this.message = message;
    }
}

Explanation:

• @ConfigurationProperties(prefix = "custom.service"): Binds properties prefixed with custom.service to this class.
• This class holds a message property with a default value.

2.2 Create CustomService.java

Create a simple service that will be auto-configured.

package com.example.autoconfig;

public class CustomService {

    private final String message;

    public CustomService(String message) {
        this.message = message;
    }

    public String getMessage() {
        return message;
    }
}

2.3 Create CustomAutoConfiguration.java

Create the auto-configuration class for your custom service.

package com.example.autoconfig;

import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
@EnableConfigurationProperties(CustomProperties.class)
public class CustomAutoConfiguration {

    @Bean
    @ConditionalOnMissingBean
    public CustomService customService(CustomProperties properties) {
        return new CustomService(properties.getMessage());
    }
}

Explanation:

• @Configuration: Marks the class as a source of bean definitions.
• @EnableConfigurationProperties(CustomProperties.class): Enables support for @ConfigurationProperties annotated classes.
• @ConditionalOnMissingBean: Ensures that the bean is created only if a bean of the same type is not already defined.

Step 3: Register the Auto-Configuration

3.1 Create spring.factories

Create the spring.factories file in src/main/resources/META-INF.

# src/main/resources/META-INF/spring.factories

org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
com.example.autoconfig.CustomAutoConfiguration

Explanation:

• This file registers the auto-configuration class so that Spring Boot can discover and apply it.

Step 4: Publish the Custom Auto-Configuration to a Local Repository

4.1 Build and Install the Auto-Configuration

Run the following Maven command to build and install the custom auto-configuration to your local Maven repository.

./mvnw clean install

Explanation:

• This command compiles the code, runs tests, and installs the JAR file in the local Maven repository.

Step 5: Use the Custom Auto-Configuration in a Spring Boot Application

5.1 Create a New Spring Boot Application

Use Spring Initializr to create a new Spring Boot application with the following dependencies:

• Spring Web

Download and unzip the project, then open it in your IDE.

5.2 Add the Custom Auto-Configuration Dependency

Add the custom auto-configuration dependency to the pom.xml file of your Spring Boot application.

<dependency>
    <groupId>com.example</groupId>
    <artifactId>custom-auto-configuration</artifactId>
    <version>1.0.0</version>
</dependency>

5.3 Create a REST Controller

Create a REST controller to use the CustomService.

package com.example.demo;

import com.example.autoconfig.CustomService;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class HelloController {

    @Autowired
    private CustomService customService;

    @GetMapping("/hello")
    public String hello() {
        return customService.getMessage();
    }
}

Explanation:

• CustomService is auto-configured and injected into the HelloController via dependency injection.
• The /hello endpoint returns a message from CustomService.

Step 6: Run and Test the Application

6.1 Run the Application

Run the Spring Boot application using your IDE or the command line:

./mvnw spring-boot:run

6.2 Test the Endpoint

Open your browser and navigate to http://localhost:8080/hello. You should see the following response:

Hello from Custom Service!

Step 7: Customize the Auto-Configuration Properties

7.1 Modify application.properties

You can customize the properties in your application.properties file of the Spring Boot application.

# src/main/resources/application.properties

custom.service.message=Customized Hello from Custom Service!

7.2 Test the Customization

Restart the Spring Boot application and navigate to http://localhost:8080/hello. You should see the customized response:

Customized Hello from Custom Service!

Conclusion

In this tutorial, you have learned how to create a custom auto-configuration with Spring Boot. By following these steps, you can bundle and distribute common configurations and services for reuse in multiple applications, simplifying the setup and promoting consistency across projects.