Stereotype Annotations

In the Spring Framework, annotations are not isolated keywords; they form an extensible, composable meta-annotation hierarchy. At the root of all Spring-managed components is @Component. Specialized stereotypes—such as @Service, @Repository, and @Controller—are meta-annotated with @Component, inheriting its component-scanning eligibility while adding specific semantic and infrastructure behavior.

A common misconception is that Spring uses standard Java reflection (Class.forName()) to inspect every file in a project during component scanning. In reality, loading hundreds of classes into JVM Metaspace simply to read annotations would severely degrade startup performance and trigger static initialization prematurely.

Instead, Spring's ClassPathScanningCandidateComponentProvider uses the ASM bytecode analysis library. It reads the raw .class bytecode streams directly from the filesystem or JARs, parsing annotation metadata without loading the class into the JVM ClassLoader until it is selected for bean registration.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

@Configuration
@ComponentScan(
    basePackages = "com.example.billing",
    includeFilters = @ComponentScan.Filter(
        type = FilterType.ANNOTATION, 
        classes = AuditedService.class
    ),
    excludeFilters = @ComponentScan.Filter(
        type = FilterType.REGEX, 
        pattern = ".*Mock.*"
    )
)
public class BillingModuleConfig {
    // Defines explicit scan boundaries with ASM-level filtering
}

Beyond documentation, @Repository triggers concrete runtime behavior: it enables automatic persistence exception translation. When a bean is annotated with @Repository, Spring registers a PersistenceExceptionTranslationAdvisor around it.

By default, @SpringBootApplication enables component scanning starting from the package in which the application class resides, searching all child packages. Placing a component in an external or sibling package leaves it completely undiscovered.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

// File 1: com.example.app.Application (Scan root: com.example.app.*)
package com.example.app;

@SpringBootApplication
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

// File 2: com.example.external.PaymentService (OUTSIDE the scan root!)
package com.example.external;

@Service
public class PaymentService {} // Undiscovered!

APPLICATION FAILED TO START
***************************
Description:
Field paymentService in com.example.app.CheckoutController required a bean of type 'com.example.external.PaymentService' that could not be found.

Action:
Consider defining a bean of type 'com.example.external.PaymentService' in your configuration,
or relocate PaymentService into package com.example.app or a sub-package.