Component Scanning

Why Component Scanning Matters

Production applications contain hundreds of beans. Manual registration (@Bean methods for each class) becomes unmaintainable at scale. Component scanning auto-discovers beans via annotations, reducing configuration from hundreds of @Bean methods to a single @ComponentScan declaration.

Java Standard Library Baseline

Manual bean registration requires explicit factory methods:

// => Configuration class: manual bean registration
public class ApplicationFactory {

    // => Manual registration: one method per class
    public static ZakatCalculator createZakatCalculator() {
        // => Manually creates PriceConverter dependency
        PriceConverter converter = createPriceConverter();
        // => Manually wires dependency
        return new ZakatCalculator(converter);
    }

    public static PriceConverter createPriceConverter() {
        // => Manual instantiation
        return new GoldPriceConverter();
    }

    public static ZakatService createZakatService() {
        // => Must know entire dependency graph
        ZakatCalculator calculator = createZakatCalculator();
        ZakatRepository repository = createZakatRepository();
        NotificationService notifications = createNotificationService();
        // => Manual wiring of multiple dependencies
        return new ZakatService(calculator, repository, notifications);
    }

    public static ZakatRepository createZakatRepository() {
        // => Manual database connection
        DataSource dataSource = createDataSource();
        return new ZakatRepositoryImpl(dataSource);
    }

    public static NotificationService createNotificationService() {
        return new EmailNotificationService();
    }

    public static DataSource createDataSource() {
        return new HikariDataSource();
    }
}

// => Application: manual factory calls
public class Application {
    public static void main(String[] args) {
        // => Must manually call factory for every bean
        ZakatService service = ApplicationFactory.createZakatService();
        service.processZakat(new BigDecimal("100"));
    }
}

Limitations:

Manual registration: One factory method per class
Maintenance burden: Add new class = add new factory method
Coupling: Factory knows all implementation details
No discovery: Must explicitly register every class
Verbose: Hundreds of factory methods for large apps

Spring @Bean Configuration (Manual)

Spring’s @Bean methods provide type-safe manual registration:

@Configuration  // => Configuration class
public class ApplicationConfig {

    // => @Bean method: manually registers each class
    @Bean
    public PriceConverter priceConverter() {
        return new GoldPriceConverter();
    }

    @Bean
    public ZakatCalculator zakatCalculator(PriceConverter priceConverter) {
        // => Spring injects dependency
        return new ZakatCalculator(priceConverter);
    }

    @Bean
    public DataSource dataSource() {
        return new HikariDataSource();
    }

    @Bean
    public ZakatRepository zakatRepository(DataSource dataSource) {
        return new ZakatRepositoryImpl(dataSource);
    }

    @Bean
    public NotificationService notificationService() {
        return new EmailNotificationService();
    }

    @Bean
    public ZakatService zakatService(
            ZakatCalculator calculator,
            ZakatRepository repository,
            NotificationService notifications) {
        return new ZakatService(calculator, repository, notifications);
    }

    // => For 100 classes: need 100 @Bean methods
}

Benefits over manual Java:

Type safety, dependency injection

Limitations:

Still verbose: one @Bean method per class
Maintenance burden: new class = new @Bean method

Spring Component Scanning (Auto-Discovery)

Component scanning auto-discovers beans via annotations:

// => Configuration class: enables component scanning
@Configuration  // => Configuration class marker
@ComponentScan(basePackages = "com.ayokoding.zakat")
// => Scans package recursively for stereotype annotations
// => Discovers: @Component, @Service, @Repository, @Controller
// => Registers discovered classes as beans automatically
public class ApplicationConfig {

    // => No @Bean methods needed for stereotype-annotated classes

    @Bean  // => Still use @Bean for third-party libraries
    public DataSource dataSource() {
        // => Can't add @Component to HikariDataSource (not our code)
        return new HikariDataSource();
    }
}

// => Service layer: auto-discovered
@Service  // => Stereotype annotation: marks class as service bean
          // => Component scanning registers this as bean
          // => Bean name: "zakatService" (camelCase class name)
public class ZakatService {

    private final ZakatCalculator calculator;  // => Dependency
    private final ZakatRepository repository;
    private final NotificationService notifications;

    // => Constructor injection: Spring auto-injects dependencies
    public ZakatService(
            ZakatCalculator calculator,
            ZakatRepository repository,
            NotificationService notifications) {
        this.calculator = calculator;
        this.repository = repository;
        this.notifications = notifications;
    }

    public void processZakat(BigDecimal amount) {
        BigDecimal zakat = calculator.calculateZakat(amount);
        repository.save(zakat);
        notifications.notifyUser("Zakat processed: " + zakat);
    }
}

// => Business logic: auto-discovered
@Component  // => Generic stereotype: marks class as Spring bean
            // => Use when class doesn't fit service/repository/controller
public class ZakatCalculator {

    private final PriceConverter priceConverter;

    // => Constructor injection: Spring auto-injects
    public ZakatCalculator(PriceConverter priceConverter) {
        this.priceConverter = priceConverter;
    }

    public BigDecimal calculateZakat(BigDecimal goldGrams) {
        BigDecimal value = priceConverter.convertToMoney(goldGrams);
        BigDecimal nisab = new BigDecimal("85");
        if (goldGrams.compareTo(nisab) >= 0) {
            return value.multiply(new BigDecimal("0.025"));
        }
        return BigDecimal.ZERO;
    }
}

// => Data access layer: auto-discovered
@Repository  // => Stereotype for data access beans
             // => Enables persistence exception translation
             // => SQLException → DataAccessException
public class ZakatRepositoryImpl implements ZakatRepository {

    private final DataSource dataSource;

    public ZakatRepositoryImpl(DataSource dataSource) {
        this.dataSource = dataSource;
    }

    public void save(BigDecimal zakat) {
        // => Database operations
    }
}

// => Notification layer: auto-discovered
@Service  // => Service stereotype
public class EmailNotificationService implements NotificationService {

    public void notifyUser(String message) {
        // => Send email notification
        System.out.println("Email sent: " + message);
    }
}

// => Generic component: auto-discovered
@Component  // => Generic stereotype
public class GoldPriceConverter implements PriceConverter {

    public BigDecimal convertToMoney(BigDecimal goldGrams) {
        return goldGrams.multiply(new BigDecimal("60"));
    }
}

// => Application: component scanning wires everything
public class Application {
    public static void main(String[] args) {
        // => Creates Spring container with component scanning
        ApplicationContext context =
            new AnnotationConfigApplicationContext(ApplicationConfig.class);

        // => Component scanning auto-discovered and registered:
        // - ZakatService, ZakatCalculator, ZakatRepositoryImpl
        // - EmailNotificationService, GoldPriceConverter

        // => Retrieve fully-wired service
        ZakatService service = context.getBean(ZakatService.class);
        service.processZakat(new BigDecimal("100"));
    }
}

Benefits:

Zero configuration: No @Bean methods for application classes
Auto-discovery: New classes automatically registered
Convention-based: Annotations on classes, not config
Maintainable: Add class = add annotation (no config changes)

Stereotype Annotations

Spring provides semantic stereotype annotations:

// => @Component: generic stereotype for any Spring bean
@Component  // => Use when class doesn't fit other stereotypes
public class ConfigValidator {
    // => Utility class, helper, etc.
}

// => @Service: business logic layer
@Service  // => Semantic meaning: service layer bean
          // => Functionally identical to @Component
          // => Better code readability
public class OrderService {
    // => Business logic, orchestration, workflows
}

// => @Repository: data access layer
@Repository  // => Semantic meaning: data access bean
             // => Enables persistence exception translation
             // => SQLException → DataAccessException
public class OrderRepository {
    // => Database operations, queries, persistence
}

// => @Controller: web layer (Spring MVC)
@Controller  // => Semantic meaning: web controller
             // => Handles HTTP requests, renders views
public class OrderController {
    // => HTTP endpoints, request mapping
}

// => @RestController: REST API layer (Spring MVC)
@RestController  // => @Controller + @ResponseBody
                 // => Returns JSON/XML, not views
public class OrderApiController {
    // => REST endpoints, JSON responses
}

// => Custom stereotype: domain-specific semantics
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Service  // => Meta-annotated with @Service
@Transactional  // => All methods transactional by default
public @interface HalalService {
    // => Custom stereotype for Sharia-compliant services
}

@HalalService  // => Custom stereotype usage
public class HalalFoodOrderService {
    // => Automatically @Service + @Transactional
}