Spring Framework & the IoC Container

Component Scanning & Stereotypes

18 min Lesson 6 of 13

Component Scanning & Stereotypes

In the previous lessons you registered beans explicitly — either in a @Configuration class with @Bean methods or in an XML file. That works well when you own every bean definition and want full visibility. In real applications, however, you may have dozens or hundreds of classes. Declaring each one manually quickly becomes tedious and error-prone. Component scanning is Spring's answer: you annotate your classes and let the container discover them automatically.

How Component Scanning Works

When the Spring container starts with component scanning enabled, it walks the classpath — starting from one or more base packages — looking for classes that carry specific annotations. Any class it finds is registered as a bean definition automatically, as if you had written a @Bean method for it yourself.

You enable scanning on a configuration class with @ComponentScan:

import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.AnnotationConfigApplicationContext;

@Configuration
@ComponentScan(basePackages = "com.example.shop")
public class AppConfig {
    // No @Bean methods needed for auto-detected classes
}

// Bootstrap
public class Main {
    public static void main(String[] args) {
        var ctx = new AnnotationConfigApplicationContext(AppConfig.class);
        // All @Component-annotated classes in com.example.shop are now beans
        ctx.close();
    }
}

Spring Boot shortcut: @SpringBootApplication already includes @ComponentScan rooted at the package of the annotated class. In a Boot project you rarely write @ComponentScan explicitly — but knowing what it does is essential for diagnosing scan failures.

@Component — The Base Stereotype

@Component is the root annotation. Any class annotated with it is a candidate for auto-detection. By default the bean name is the simple class name with the first letter lower-cased:

import org.springframework.stereotype.Component;

@Component
public class EmailValidator {

    public boolean isValid(String address) {
        return address != null && address.contains("@");
    }
}

This class is now a singleton bean named emailValidator. Any other bean can declare a dependency on it, and Spring will inject the same instance everywhere.

The Stereotype Annotations — Semantic Layers

Spring ships three specialised annotations that all extend @Component:

@Service — marks a class as belonging to the business / service layer. It holds business logic, orchestrates calls to repositories, and may apply transaction boundaries.
@Repository — marks a class as a data-access object (DAO). It talks to a database or external store. Spring additionally wraps it with an AOP advisor that translates data-access exceptions into Spring's unified DataAccessException hierarchy.
@Controller — marks a class as a web MVC controller. Spring MVC's dispatcher servlet scans for these to map HTTP requests to handler methods. (For REST APIs you use @RestController, which adds @ResponseBody.)

Use the right stereotype. All four annotations behave identically as far as bean registration goes, but the semantic label matters: it communicates intent, enables layer-specific AOP (exception translation for @Repository, request mapping for @Controller), and makes package organisation immediately readable.

A Realistic Three-Layer Example

Here is a simple order-processing slice that shows all three stereotypes working together. Spring wires the dependency chain automatically.

// --- Repository layer ---
import org.springframework.stereotype.Repository;
import java.util.Map;
import java.util.concurrent.ConcurrentHashMap;

@Repository
public class OrderRepository {

    private final Map<Long, String> store = new ConcurrentHashMap<>();

    public void save(Long id, String order) {
        store.put(id, order);
    }

    public String findById(Long id) {
        return store.get(id);
    }
}

// --- Service layer ---
import org.springframework.stereotype.Service;

@Service
public class OrderService {

    private final OrderRepository orderRepository;

    // Constructor injection — Spring detects the single constructor automatically
    public OrderService(OrderRepository orderRepository) {
        this.orderRepository = orderRepository;
    }

    public void placeOrder(Long id, String description) {
        if (description == null || description.isBlank()) {
            throw new IllegalArgumentException("Order description cannot be blank");
        }
        orderRepository.save(id, description);
    }

    public String getOrder(Long id) {
        return orderRepository.findById(id);
    }
}

// --- Controller layer (Spring MVC) ---
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.ResponseBody;

@Controller
public class OrderController {

    private final OrderService orderService;

    public OrderController(OrderService orderService) {
        this.orderService = orderService;
    }

    @GetMapping("/orders/{id}")
    @ResponseBody
    public String getOrder(@PathVariable Long id) {
        return orderService.getOrder(id);
    }
}

Notice that no @Bean method exists for any of these three classes. Spring discovers them, resolves the dependency chain (OrderController → OrderService → OrderRepository), and wires everything automatically.

Controlling the Bean Name

By default the bean name is the uncapitalised simple class name (orderService, orderRepository). You can override it:

@Service("legacyOrderService")
public class LegacyOrderService implements OrderService { ... }

Custom names are useful when you have multiple implementations of the same interface and need to qualify injection points — something you will tackle formally in Lesson 8 on qualifiers.

Filtering What Gets Scanned

@ComponentScan accepts includeFilters and excludeFilters so you can fine-tune what the scanner picks up:

import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.ComponentScan.Filter;
import org.springframework.context.annotation.FilterType;
import org.springframework.context.annotation.Configuration;

@Configuration
@ComponentScan(
    basePackages = "com.example.shop",
    excludeFilters = @Filter(
        type = FilterType.ANNOTATION,
        classes = org.springframework.stereotype.Controller.class
    )
)
public class ServiceConfig {
    // Controllers are excluded — useful for non-web application contexts
}

This pattern is common in multi-context applications where the root context holds services and repositories while the web context holds controllers.

@Repository and Exception Translation

One concrete, functional difference between @Repository and plain @Component is persistence exception translation. Spring applies a post-processor (PersistenceExceptionTranslationPostProcessor) to every @Repository bean. If a method throws a low-level, vendor-specific exception (e.g. a Hibernate ConstraintViolationException or a JDBC SQLException), the proxy wraps it in the appropriate Spring DataAccessException subclass. Your service layer stays decoupled from the persistence technology.

Do not put business logic in @Repository classes. Exception translation and the single-responsibility principle both demand that your DAO classes deal only with data access. Business rules belong in @Service beans.

Summary

Component scanning removes the boilerplate of explicit bean registration. Annotate your classes with the right stereotype — @Component for generic helpers, @Service for business logic, @Repository for data access, @Controller or @RestController for web endpoints — and @ComponentScan handles discovery. The semantic choice of stereotype is not cosmetic: it drives AOP, exception translation, and the readability of your architecture. In the next lesson you will boot a full ApplicationContext and interact with the beans you have just learned to declare.