Component Scan

Imagine a new manager taking over a large bookshop. She does not walk around asking each worker to introduce themselves. She takes the staff badge list and checks every counter in the building. Anyone with a badge on the list joins the team. A person standing in the shop next door, even if they wear a badge, is never counted because the manager never looked there.

Spring works like this manager. When your app starts, it walks through your packages looking for classes with special badges, and it turns each one into a bean. That walk is called component scan. In this guide you will see how it decides where to look, which badges it recognises, and what to do when a class is missed.

What is Component Scan?

Without component scan you would have to list every class by hand. With it, you write the annotation on the class and Spring finds it on its own.

The badges Spring looks for are called stereotype annotations.

@Service, @Repository, @Controller and @Configuration are all built on top of @Component. So they are all found by the same scan. The different names help you and your team read the code, and some add extra behaviour.

Why is it used?

Component scan saves you from writing long lists.

• Less setup. Add an annotation and the class is picked up. No XML, no registration code.
• Easy to grow. A new service class only needs its annotation. Nothing else in the project changes.
• Clear structure. Because scan follows packages, your folder layout matters and stays tidy.
• Speed for beginners. You can focus on writing features. Spring handles the wiring.

There is one catch. Scan only looks where it has been told to look. Knowing where that is will save you hours of head scratching.

How it works

Every Spring Boot app has a main class with @SpringBootApplication. That annotation includes @ComponentScan. If you give no settings, the scan starts in the package of that main class and goes down through every package below it.

text
com.bookhub.shop   <- main class
   |
   +-- catalog          scanned
   |
   +-- billing          scanned

com.bookhub.partner  NOT scanned

The main class sits in com.bookhub.shop. Everything inside com.bookhub.shop, including catalog and billing, is searched. The package com.bookhub.partner is a sibling, not a child, so it is skipped. Annotated classes there stay ordinary classes.

Here is the routine step by step.

text
+--------------------------------+
|  App starts, main class found  |
+--------------------------------+
                |
                v
+--------------------------------+
|  Scan the main class package   |
|  and all packages below it     |
+--------------------------------+
                |
                v
+--------------------------------+
|  Class has a stereotype        |
|  annotation? Make a bean       |
+--------------------------------+
                |
                v
+--------------------------------+
|  Beans are created and wired   |
+--------------------------------+

Spring checks each class it meets. If it carries @Component or one of its relatives, Spring records a bean definition. Classes without a badge are ignored. Only after the scan finishes does Spring create the beans and connect them.

If a class must live outside that tree, you widen the search. scanBasePackages on @SpringBootApplication lists exactly the packages to scan. You can also use @ComponentScan with basePackages on any configuration class, and add filters to include or exclude certain classes.

Real-Life Example

A school principal prepares the list of teachers for exam duty. She checks the staff room, the science block and the arts block, all inside the main campus. A teacher who works at the sister school across the road is not on her list, even though they are just as qualified, because the principal only looked inside her own campus.

The campus is the main class package and its subpackages. The teachers with badges are the annotated classes. The sister school is a package outside the scan area. To include them, the principal must add that school to her list, which is what scanBasePackages does.

text
bookhub/
└─ src/main/java/com/bookhub/
   ├─ shop/
   │  ├─ ShopApplication.java
   │  ├─ ScanRunner.java
   │  ├─ catalog/
   │  │  ├─ CatalogService.java
   │  │  └─ BookRepository.java
   │  └─ billing/
   │     └─ BillingService.java
   └─ partner/
      └─ PartnerOffers.java

java
package com.bookhub.shop;

import org.springframework.boot.Banner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.WebApplicationType;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class ShopApplication {

    public static void main(String[] args) {
        SpringApplication app = new SpringApplication(ShopApplication.class);
        app.setWebApplicationType(WebApplicationType.NONE);
        app.setBannerMode(Banner.Mode.OFF);
        app.setLogStartupInfo(false);
        app.run(args);
    }
}

java
package com.bookhub.shop.catalog;

import org.springframework.stereotype.Service;

@Service
public class CatalogService {
}

java
package com.bookhub.shop.catalog;

import org.springframework.stereotype.Repository;

@Repository
public class BookRepository {
}

java
package com.bookhub.shop.billing;

import org.springframework.stereotype.Service;

@Service
public class BillingService {
}

java
package com.bookhub.partner;

import org.springframework.stereotype.Component;

@Component
public class PartnerOffers {
}

java
package com.bookhub.shop;

import com.bookhub.partner.PartnerOffers;
import com.bookhub.shop.billing.BillingService;
import com.bookhub.shop.catalog.BookRepository;
import com.bookhub.shop.catalog.CatalogService;

import org.springframework.boot.CommandLineRunner;
import org.springframework.context.ApplicationContext;
import org.springframework.stereotype.Component;

@Component
public class ScanRunner implements CommandLineRunner {

    private final ApplicationContext context;

    public ScanRunner(ApplicationContext context) {
        this.context = context;
    }

    @Override
    public void run(String... args) {
        show(CatalogService.class);
        show(BookRepository.class);
        show(BillingService.class);
        show(PartnerOffers.class);
    }

    private void show(Class<?> type) {
        int count = context.getBeanNamesForType(type).length;
        System.out.println(type.getSimpleName() + " found: " + count);
    }
}

bash
mvn -q package
java -jar target/shop-0.0.1-SNAPSHOT.jar

text
CatalogService found: 1
BookRepository found: 1
BillingService found: 1
PartnerOffers found: 0

java
@SpringBootApplication(scanBasePackages = {"com.bookhub.shop", "com.bookhub.partner"})
public class ShopApplication {

text
PartnerOffers found: 1

Code Explained

• @Service and @Repository are stereotypes built on @Component, so the scan picks them up.
• CatalogService and BookRepository are in a subpackage of com.bookhub.shop, so they are found without any extra setting.
• PartnerOffers is in a package outside the tree, so it is skipped and getBeanNamesForType returns an empty array.
• scanBasePackages replaces the default starting point, so we list the original package too. If we listed only com.bookhub.partner, the shop classes would no longer be scanned.
• The runner prints how many bean names match each type. Zero means the class never became a bean.

Common Mistakes

• Class outside the scan tree. This is the most common cause of "No qualifying bean" errors and controllers that return 404. Move the class below the main package or add its package to scanBasePackages.
• Missing annotation. A class with no stereotype is invisible to the scan.
• Listing only the new package. When you set scanBasePackages, include your own main package as well.
• Scanning too widely. Pointing the scan at a huge package such as com slows startup and may pull in beans you did not want.

Interview Questions

Frequently Asked Questions

What is component scan in Spring Boot?

It is the search Spring performs at startup to find classes with annotations like @Component and turn them into beans. In Spring Boot it is switched on by @SpringBootApplication.

Why does my controller return 404?

Very often the controller class is outside the package tree of the main class, so component scan never registered it. Move it below the main package or widen the scan.

Can I exclude a class from component scan?

Yes. @ComponentScan accepts excludeFilters, where you can leave out a class, a package pattern or every class with a given annotation.

Does component scan slow the app down?

Slightly, because Spring reads class files at startup. In a normally sized project you will not notice it. Keep the scan area tight and it stays fast.

Related Topics

• Spring Beans: see what the scan turns your classes into.
• Configuration and Bean: create beans without scanning.
• Spring Boot Project Structure: place your packages so scanning just works.
• Auto Configuration: learn how Spring Boot adds beans on its own.