sdlc.dev

Spring Boot path · The container · Topic 3 of 12

Auto-configuration and starters

Not started

Spring Boot's best trick is that adding a dependency changes what your application does. Put spring-boot-starter-data-jpa on the classpath and, with no code, you get a DataSource, a connection pool, an EntityManagerFactory, a transaction manager and repository support. None of that is magic: it is a long list of ordinary configuration classes, each of which asks a few yes-or-no questions before it registers any beans.

Why it matters: When Boot does something you didn't ask for, or doesn't do something you expected, the answer is always in a condition, and you can read which one.

  1. 1Starters bring jars

    A starter is just a dependency bundle. Adding spring-boot-starter-web puts Spring MVC, Jackson and Tomcat on the classpath.

  2. 2Auto-configurations bring beans

    Ordinary @Configuration classes listed in an imports file, each guarded by conditions.

  3. 3Conditions decide

    Typical guards: is this class on the classpath, is this property set, has the user already defined this bean?

  4. 4Your bean wins

    Most auto-configured beans are @ConditionalOnMissingBean, so declaring your own makes Boot's version back away.

1

How it works

The explanation, with examples you can run.

Starters and auto-configurations are different things

A starter is a Maven or Gradle dependency with no code of its own; it pulls in a coherent set of libraries. An auto-configuration is a class marked @AutoConfiguration, shipped mostly in spring-boot-autoconfigure, and listed in a file called META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports. @SpringBootApplication includes @EnableAutoConfiguration, which reads those files from every jar and evaluates each class after your own configuration has been registered.

Conditions

A simplified version of what Boot does for a connection pool looks like this:

@AutoConfiguration@ConditionalOnClass(DataSource.class)              // the JDBC API is present@EnableConfigurationProperties(DataSourceProperties.class)public class MyDataSourceAutoConfiguration {   @Bean  @ConditionalOnMissingBean(DataSource.class)       // you haven't made one  @ConditionalOnProperty(prefix = "spring.datasource", name = "url")  DataSource dataSource(DataSourceProperties props) {    return props.initializeDataSourceBuilder().build();  }}

The conditions you will see most:

  • @ConditionalOnClass / @ConditionalOnMissingClass: is a library on the classpath?
  • @ConditionalOnBean / @ConditionalOnMissingBean: has someone already defined this?
  • @ConditionalOnProperty: is a property set (by default, present and not false)?
  • @ConditionalOnWebApplication: is this a servlet or reactive web app?

Because the auto-configuration runs last and backs away when your bean exists, the way to customise Boot is usually to declare the bean yourself, or, better still, to set a property that Boot's own bean reads.

Seeing the decisions

Start the application with --debug (or debug=true in application.properties) and Boot prints a conditions evaluation report: every auto-configuration, whether it matched, and which condition decided. With Actuator, /actuator/conditions shows the same at runtime, if you expose it.

DataSourceAutoConfiguration matched:   - @ConditionalOnClass found required classes 'javax.sql.DataSource', ...MongoAutoConfiguration:   Did not match:      - @ConditionalOnClass did not find required class 'com.mongodb.client.MongoClient'

To switch one off entirely:

@SpringBootApplication(exclude = DataSourceAutoConfiguration.class)public class App { }

The same mechanism is open to you: a company "starter" for logging or tracing is an auto-configuration class, an imports file and a few conditions, so teams get sensible defaults they can still override.

2

Check yourself

3 questions. Get them all right to finish this topic.

  1. 1.You declare your own ObjectMapper bean. What happens to the one Boot's Jackson auto-configuration would create?
  2. 2.How do you find out why DataSourceAutoConfiguration did or did not apply?
  3. 3.Where does Spring Boot 3 look for the list of auto-configuration classes in a jar?

0 of 3 right so far. Get all three to finish this topic.

Go deeper