spring-context-indexer

Active contributors: Stéphane Nicoll, Juergen Hoeller

Purpose

spring-context-indexer is an annotation processor that runs at compile time and emits a META-INF/spring.components file listing every bean candidate (classes annotated with @Component, @Service, @Repository, @Controller, or any meta-annotated derivative). At runtime, CandidateComponentsIndexLoader (in spring-context) reads this file to skip classpath scanning — saving startup time on large applications.

Directory layout

spring-context-indexer/
├── spring-context-indexer.gradle
└── src/main/java/org/springframework/context/index/processor/
    ├── CandidateComponentsIndexer.java            # the AbstractProcessor
    ├── MetadataStore.java
    └── …

How it works

graph LR
    SRC[Annotated source files] -->|"javac with this processor"| PROC[CandidateComponentsIndexer]
    PROC -->|"generates"| INDEX["META-INF/spring.components"]
    INDEX -->|"packaged in JAR"| RT[Runtime]
    RT -->|"CandidateComponentsIndexLoader reads"| MAP[ClassName → stereotype map]
    MAP -.replaces.-> SCAN[Classpath scanner]

To use:

1. Add spring-context-indexer as an annotationProcessor dependency.
2. Compile.
3. Inspect the resulting META-INF/spring.components file in the JAR.

When a Spring ApplicationContext starts and component-scans, it first checks for a candidate-index. If present, it iterates the index instead of walking the classpath — orders of magnitude faster for large applications.

Tradeoffs

• Benefit: Startup time savings, especially for fat applications with thousands of classes on the path.
• Cost: Each module must opt in by adding the processor; without it, no entries are added.
• Modern alternative: Spring AOT processing (introduced in Spring 6) generates a richer set of metadata at build time, including for native images. Most Spring Boot apps today rely on AOT rather than the indexer.

Integration points

• Read by org.springframework.context.index.CandidateComponentsIndexLoader in spring-context.
• Standalone — depends only on the JDK's annotation processing API.

See also

• spring-context — runtime consumer
• features/dependency-injection — component scanning context