Bean Definitions: Scanning vs. Functional

Bean Definitions: Scanning vs. Functional

The Spring Framework’s core functionality revolves around bean definitions, which serve as blueprints for object creation and lifecycle management within the application context. Two primary mechanisms exist for registering these definitions: component scanning and functional registration. The choice between them directly impacts startup performance, memory footprint, and control over configuration logic. This analysis evaluates both approaches through the lens of a production-grade logistics application, LogisticsCore, emphasizing JVM-level mechanics and runtime trade-offs.

Component Scanning

Component scanning relies on classpath inspection to detect types annotated with stereotypes such as @Component, @Service, @Repository, or @Controller. The @SpringBootApplication annotation implicitly enables scanning via @ComponentScan. At startup, Spring uses ASM (Apache Commons ASM) to parse bytecode metadata from .class files, identify candidates, and register ScannedGenericBeanDefinition instances in the BeanDefinitionRegistry [1].

// Example: Component Scanning in LogisticsCore
package com.logistics.core;

import org.springframework.stereotype.Service;
import java.util.concurrent.Executors;
import java.util.concurrent.ThreadFactory;

@Service
public class InventoryService {
    private final WarehouseRepository repository;
    
    public InventoryService(WarehouseRepository repository) {
        this.repository = repository;
    }
    
    // Java 21: Record for immutable DTO
    public record StockLevel(String itemId, int quantity, String location) {}
    
    // Virtual Threads for concurrent stock updates
    public void updateStockConcurrently() {
        try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
            // Concurrent operations on virtual threads
        }
    }
}

The scanning process incurs a startup cost proportional to the number of classes on the classpath. For applications with thousands of classes but few beans, this results in unnecessary metadata parsing and candidate caching, increasing both time and memory overhead [1]. No proxy is involved in the scanning mechanism itself; proxies apply only to @Configuration classes, as discussed later.

Functional Registration

Functional registration bypasses classpath scanning by programmatically defining and registering beans via the BeanDefinitionRegistry. This approach provides direct control over bean creation logic, reduces startup latency, and eliminates the need for annotation processing.

// Example: Functional Bean Registration in LogisticsCore
package com.logistics.core.config;

import org.springframework.context.ApplicationContextInitializer;
import org.springframework.context.ConfigurableApplicationContext;
import org.springframework.beans.factory.support.BeanDefinitionRegistry;
import org.springframework.beans.factory.support.RootBeanDefinition;
import com.logistics.core.InventoryService;
import com.logistics.core.WarehouseRepository;
import java.util.function.Supplier;

public class FunctionalBeanRegistrationInitializer 
        implements ApplicationContextInitializer<ConfigurableApplicationContext> {
    
    @Override
    public void initialize(ConfigurableApplicationContext context) {
        BeanDefinitionRegistry registry = (BeanDefinitionRegistry) context.getBeanFactory();
        
        // Register InventoryService with supplier
        RootBeanDefinition inventoryServiceDef = new RootBeanDefinition();
        inventoryServiceDef.setBeanClass(InventoryService.class);
        inventoryServiceDef.setInstanceSupplier(() -> {
            WarehouseRepository repo = context.getBean(WarehouseRepository.class);
            return new InventoryService(repo);
        });
        inventoryServiceDef.setScope("singleton");
        inventoryServiceDef.setLazyInit(false);
        
        registry.registerBeanDefinition("inventoryService", inventoryServiceDef);
        
        // Register configuration using Java 21 Record
        RootBeanDefinition configDef = new RootBeanDefinition();
        configDef.setInstanceSupplier(() -> {
            record AppConfig(int maxThreads, String region) {}
            return new AppConfig(100, "US-EAST-1");
        });
        registry.registerBeanDefinition("appConfig", configDef);
    }
}

This method avoids ASM-based classfile parsing entirely. Each bean definition is created in constant time, making it optimal for applications with large classpaths but minimal bean counts.

Comparison and Considerations

Aspect	Component Scanning	Functional Registration
Startup Overhead	High (scales with classpath size)	Low (constant per bean)
Memory Usage	Higher (ASM metadata, candidate cache)	Lower (direct definitions)
Flexibility	Limited (annotation-based)	High (programmatic control)
Runtime Performance	Same (once beans created)	Same (once beans created)
Bean Discovery	Automatic	Manual
Conditional Logic	@Conditional annotations	Programmatic if/else
Proxy Requirements	May need CGLIB proxies for @Configuration	No proxy requirements
Testability	Requires Spring context	Can test registration logic directly
Java 21 Integration	Annotations only	Can use Records, Pattern Matching, Virtual Threads in Suppliers

Functional registration enables use of modern Java features—such as pattern matching in suppliers or virtual threads during initialization—without being constrained by annotation processing rules.

Configuration Modes: Full vs. Lite

Spring supports two modes for @Configuration classes: Full mode (proxyBeanMethods=true) and Lite mode (proxyBeanMethods=false). The distinction determines how singleton scope is enforced during inter-bean method calls.

// Example: Full Mode with CGLIB Proxy
package com.logistics.core.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration // proxyBeanMethods=true by default → CGLIB proxy used
public class WarehouseConfig {
    
    @Bean
    public WarehouseRepository warehouseRepository() {
        return new InMemoryWarehouseRepository();
    }
    
    @Bean
    public InventoryService inventoryService() {
        // This call is intercepted by a CGLIB-generated proxy
        // Ensures singleton reuse via bean factory lookup
        return new InventoryService(warehouseRepository());
    }
}

In Full mode, Spring generates a CGLIB proxy that subclasses the @Configuration class. This proxy intercepts intra-configuration @Bean method calls to return existing singleton instances from the container, preventing unintended re-instantiation. The use of CGLIB requires the configuration class to be non-final and limits some JVM optimizations.

// Example: Lite Mode (No Proxy)
package com.logistics.core.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration(proxyBeanMethods = false) // No CGLIB proxy
public class WarehouseLiteConfig {
    
    @Bean
    public static WarehouseRepository warehouseRepository() {
        return new InMemoryWarehouseRepository();
    }
    
    @Bean
    public InventoryService inventoryService(WarehouseRepository repository) {
        // Direct method call; no interception
        // Singleton responsibility shifts to caller or DI
        return new InventoryService(repository);
    }
}

Lite mode disables CGLIB proxying. @Bean methods are treated as plain factory methods. This improves startup performance and allows final classes or static methods, but removes automatic singleton enforcement. If warehouseRepository() is called multiple times, it may return distinct instances unless dependency injection is used to pass the bean.

Thought Experiments

1. The 10,000 Class Problem: An application with 10,000 classes but only 50 beans forces component scanning to process all class metadata. Functional registration avoids this by directly registering definitions, reducing startup time from hundreds of milliseconds to near-constant overhead.
2. The Dynamic Configuration Challenge: When configuration depends on runtime properties (e.g., region, feature flags), functional registration allows pattern matching over configuration values within suppliers. Component scanning requires complex @Conditional hierarchies or @Profile, which are resolved at container refresh time and lack dynamic dispatch.
3. The Virtual Thread Integration: Functional registration enables InstanceSupplier implementations to run on virtual threads, allowing non-blocking bean initialization. This is impossible under annotation-driven scanning, where instantiation occurs synchronously within the container’s main initialization phase.

Conclusion

Component scanning is suitable for moderate-sized applications where development velocity outweighs startup cost. However, for systems requiring predictable initialization, minimal overhead, or integration with Java 21+ concurrency models, functional registration is superior. Full mode with CGLIB proxies ensures correctness in inter-bean dependencies but adds runtime cost; Lite mode removes proxies and shifts correctness burden to developers. These trade-offs must be evaluated based on application scale, performance SLAs, and operational constraints.

[1] Spring Framework Documentation: Core Technologies - The IoC Container