Spring Boot Annotations

Spring Boot annotations are metadata markers that instruct the Spring container on configuration, bean management, and runtime behavior. They eliminate complex XML configurations, simplify dependency injection, and make creating REST APIs faster and more maintainable.

1. Core Bootstrapping Annotations

These annotations are used to bootstrap a Spring Boot application and initialize the Spring container.

@SpringBootApplication

Marks the main entry point of a Spring Boot application.

Internally includes three annotations:

• @SpringBootConfiguration → Marks a class as a configuration source.
• @EnableAutoConfiguration → Automatically configures beans based on classpath dependencies.
• @ComponentScan → Scans packages for Spring components (@Component, @Service, @Repository).

Example:

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

@EnableAutoConfiguration

• Automatically configures Spring beans based on classpath dependencies.
• Reduces manual bean creation and XML configuration.
• Example: If spring-boot-starter-web is on the classpath, it auto-configures DispatcherServlet, embedded Tomcat, and MVC beans.

@SpringBootConfiguration

• Marks a class as a configuration source.
• Functionally similar to @Configuration.
• Included automatically in @SpringBootApplication.

@ComponentScan

• Tells Spring which packages to scan for Spring components like @Component, @Service, @Repository, and @Controller.
• By default, scans the package of the class annotated with @SpringBootApplication and its sub-packages.
• Can be customized:

@ComponentScan(basePackages = "com.example.services")
public class AppConfig { }

2. Dependency Injection & Bean Management Annotations

Spring Boot uses Dependency Injection (DI) to manage objects (beans) automatically. This makes your code loosely coupled, easier to test, and maintainable. To work with DI, Spring provides several key annotations for defining and managing beans.

Stereotype Annotations

@Component

• Marks a class as a Spring-managed bean.
• Generic stereotype; used for any component in the application.
• Spring will create an instance of this class and manage its lifecycle automatically.

Example:

@Component
public class NotificationService {
    public void send(String message) {
        System.out.println("Sending: " + message);
    }
}

@Service

• Specialization of @Component.
• Used specifically for service layer classes (business logic).
• Helps readers and developers quickly identify that this class holds business logic.

Example:

@Service
public class UserService {
    public void createUser(String name) {
        System.out.println("Creating user: " + name);
    }
}

@Repository

• Specialization of @Component.
• Used for DAO (Data Access Objects) or classes that interact with the database.
• Automatically translates database exceptions into Spring’s DataAccessException.

Example:

@Repository
public class UserRepository {
    public void save(User user) {
        System.out.println("User saved: " + user.getName());
    }
}

@Controller

• Marks a class as a Spring MVC controller.
• Handles web requests and returns views (like JSP, Thymeleaf).

Example:

@Controller
public class HomeController {
    @GetMapping("/")
    public String home() {
        return "home"; // returns view name
    }
}

@RestController

• Combines @Controller + @ResponseBody.
• Used for REST APIs. Spring automatically converts returned objects to JSON or XML.

Example:

@RestController
@RequestMapping("/api/users")
public class UserRestController {
    @GetMapping("/{id}")
    public User getUser(@PathVariable int id) {
        return new User(id, "John Doe");
    }
}

Dependency Injection

@Autowired

• Automatically injects dependencies into your beans.
• Can be used on fields, constructors, or setters.
• Eliminates the need to manually instantiate objects.

Example (field injection):

@Service
public class OrderService {
    @Autowired
    private UserRepository userRepository;

    public void placeOrder(String userName) {
        System.out.println("Placing order for: " + userName);
    }
}

Example (constructor injection - recommended):

@Service
public class OrderService {
    private final UserRepository userRepository;

    @Autowired
    public OrderService(UserRepository userRepository) {
        this.userRepository = userRepository;
    }
}

@Qualifier

• Used with @Autowired when multiple beans of the same type exist.
• Helps Spring choose which bean to inject.

@Service
public class PaymentService {
    @Autowired
    @Qualifier("paypalPayment")
    private PaymentProcessor paymentProcessor;
}

@Primary

• Marks a bean as the default candidate for injection when multiple beans of the same type exist.
• Only one @Primary bean should exist per type.

@Component
@Primary
public class CreditCardPayment implements PaymentProcessor { }

3. Configuration & Properties Annotations

Spring Boot provides annotations to define configuration classes, beans, and inject properties from files like application.properties or application.yml. These annotations make your application flexible, maintainable, and environment-friendly.

@Configuration

• Marks a class as a configuration source for Spring beans.
• Classes annotated with @Configuration can define beans using @Bean.
• Similar to XML-based configuration but Java-based and type-safe.

Example:

@Configuration
public class AppConfig {

    @Bean
    public MyService myService() {
        return new MyServiceImpl();
    }
}

@Bean

• Marks a method that returns a Spring-managed bean.
• Used inside @Configuration classes.
• Spring calls the method once and manages the returned object as a singleton (by default).

Example:

@Configuration
public class AppConfig {

    @Bean
    public UserService userService() {
        return new UserServiceImpl();
    }
}

@Value

• Injects individual property values from application.properties or application.yml.
• Supports default values if the property is not found.

Example:

@Component
public class AppInfo {

    @Value("${app.name}")
    private String appName;

    @Value("${app.version:1.0}")
    private String appVersion; // default 1.0
}

@ConfigurationProperties

• Maps grouped properties from application.properties or application.yml to a Java POJO.
• Makes handling related configuration properties clean and structured.
• Requires the class to be a Spring component (@Component) or registered via @EnableConfigurationProperties.

Example (application.yml):

app:
  name: MyApp
  version: 2.0
  features:
    login: true
    signup: false

Example (Java class):

@Component
@ConfigurationProperties(prefix = "app")
public class AppProperties {
    private String name;
    private double version;
    private Features features;

    // getters and setters

    public static class Features {
        private boolean login;
        private boolean signup;
        // getters and setters
    }
}

@PropertySource

• Used to load external property files into the Spring environment.
• Useful if you want to use a custom properties file instead of the default application.properties.

Example:

@Configuration
@PropertySource("classpath:custom.properties")
public class CustomConfig { }

4. Spring Web & REST Annotations

Spring Boot makes it easy to build web applications and REST APIs. These annotations are mainly used in controllers to handle HTTP requests and responses.

@Controller

• Marks a class as a Spring MVC controller.
• Handles HTTP requests and usually returns views (like JSP or Thymeleaf templates).
• Works well for traditional web applications.

Example:

@Controller
public class HomeController {

    @GetMapping("/")
    public String home() {
        return "home"; // returns view name
    }
}

@RestController

• Combines @Controller + @ResponseBody.
• Used for REST APIs.
• Automatically converts Java objects to JSON or XML in the response.

Example:

@RestController
@RequestMapping("/api/users")
public class UserRestController {

    @GetMapping("/{id}")
    public User getUser(@PathVariable int id) {
        return new User(id, "John Doe");
    }
}

@RequestMapping

• Maps HTTP requests to handler methods in a controller.
• Can specify path, HTTP method, parameters, headers, etc.

Example:

@Controller
@RequestMapping("/products")
public class ProductController {

    @RequestMapping(value = "/list", method = RequestMethod.GET)
    public String listProducts() {
        return "productList";
    }
}

Shorthand Request Mappings

Spring Boot provides specific annotations for common HTTP methods:

Example:

@RestController
@RequestMapping("/api/orders")
public class OrderController {

    @GetMapping("/{id}")
    public Order getOrder(@PathVariable int id) { ... }

    @PostMapping
    public Order createOrder(@RequestBody Order order) { ... }
}

@PathVariable

• Extracts values from the URL path.
• Used when the URL has dynamic segments.

@GetMapping("/users/{id}")
public User getUser(@PathVariable int id) {
    return userService.getUserById(id);
}

@RequestParam

• Extracts query parameters from the URL.
• Useful for optional filters, search, or pagination.

@GetMapping("/search")
public List<User> searchUsers(@RequestParam String name) {
    return userService.findByName(name);
}

@RequestBody

• Binds the HTTP request body (usually JSON) to a Java object.
• Commonly used in POST and PUT requests.

@PostMapping("/users")
public User createUser(@RequestBody User user) {
    return userService.saveUser(user);
}

@ResponseBody

• Sends the method return value as the HTTP response body.
• Automatically converts Java objects to JSON or XML.
• Usually not needed in @RestController since it’s included by default.

@CrossOrigin

• Enables CORS (Cross-Origin Resource Sharing) on a controller or method.
• Useful when your frontend and backend are on different domains or ports.

@CrossOrigin(origins = "<http://localhost:3000>")
@GetMapping("/users")
public List<User> getUsers() {
    return userService.getAllUsers();
}

5. Conditional & Profile Annotations

Spring Boot allows you to load beans or configurations conditionally, depending on properties, environment, or active profiles. This makes your application flexible, environment-aware, and production-ready.

@ConditionalOnProperty

• Loads a bean or configuration only if a specific property is set in application.properties or application.yml.
• Useful for feature toggles or optional components.

Example:

@Component
@ConditionalOnProperty(name = "feature.payment.enabled", havingValue = "true")
public class PaymentService {
    public void processPayment() {
        System.out.println("Processing payment...");
    }
}

application.properties:

feature.payment.enabled=true

• If the property is false or missing, Spring will not create the bean.

@Profile

• Marks a bean or configuration to be active only for a specific environment profile.
• Commonly used to separate dev, test, and production configurations.

Example:

@Component
@Profile("dev")
public class DevDatabaseConfig implements DatabaseConfig {
    // Development database settings
}

@Component
@Profile("prod")
public class ProdDatabaseConfig implements DatabaseConfig {
    // Production database settings
}

Activating a profile:

In application.properties:

spring.profiles.active=dev

Or via command line:

java -jar myapp.jar --spring.profiles.active=prod

• Only beans matching the active profile are loaded.

@ConditionalOnMissingBean

• Creates a bean only if no other bean of the same type already exists.
• Useful for providing a default implementation that can be overridden.

Example:

@Bean
@ConditionalOnMissingBean
public UserService userService() {
    return new DefaultUserService();
}

@ConditionalOnBean

• Creates a bean only if a specific bean exists in the Spring context.
• Useful when your bean depends on another bean being available.

Example:

@Bean
@ConditionalOnBean(UserRepository.class)
public UserService userService(UserRepository repo) {
    return new UserServiceImpl(repo);
}

@ConditionalOnClass

• Loads a bean only if a specific class is present on the classpath.
• Useful for optional features based on external libraries.

Example:

@ConditionalOnClass(name = "com.external.PaymentGateway")
@Bean
public PaymentService paymentService() {
    return new PaymentServiceImpl();
}

6. Scheduling & Asynchronous Annotations

Spring Boot allows you to run tasks at scheduled intervals or execute methods asynchronously in separate threads. These features are essential for background jobs, batch processing, and performance optimization.

@EnableScheduling

• Enables Spring’s scheduling support in your application.
• Usually placed on a configuration class or the main application class.

Example:

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

@Scheduled

• Marks a method to be run at fixed intervals, fixed delays, or using cron expressions.
• Can be used for background jobs, cleanup tasks, or periodic processing.

Example (fixed rate):

@Component
public class ReportScheduler {

    @Scheduled(fixedRate = 5000) // runs every 5 seconds
    public void generateReport() {
        System.out.println("Generating report at " + LocalDateTime.now());
    }
}

Example (cron expression):

@Scheduled(cron = "0 0 9 * * ?") // runs every day at 9 AM
public void dailyReport() {
    System.out.println("Daily report generated");
}

Notes:

• fixedRate → interval between method start times.
• fixedDelay → interval between method completion and next start.
• cron → flexible scheduling using cron expressions.

@EnableAsync

• Enables asynchronous method execution in Spring Boot.
• Typically used in combination with @Async.

Example:

@SpringBootApplication
@EnableAsync
public class MyApplication { ... }

@Async

• Marks a method to be executed asynchronously in a separate thread.
• Improves performance by not blocking the main thread.

Example:

@Service
public class EmailService {

    @Async
    public void sendEmail(String recipient) {
        System.out.println("Sending email to " + recipient + " in thread " + Thread.currentThread().getName());
    }
}

• Callers can continue immediately without waiting for the method to finish.

Notes:

• By default, Spring uses a simple thread pool.
• You can customize the thread pool using @EnableAsync and Executor beans.

Other Useful Spring Boot Annotations

Spring Boot provides several additional annotations that are useful for transactions, event handling, bean management, and configuration organization.

@Transactional

• Ensures that a method or class executes within a database transaction.
• If any exception occurs, all operations within the transaction are rolled back automatically.
• Commonly used in service layer methods involving multiple database operations.

Example:

@Service
public class UserService {

    @Transactional
    public void createUserAndProfile(User user, Profile profile) {
        userRepository.save(user);
        profileRepository.save(profile);
        // Both succeed or both rollback on error
    }
}

@ComponentScan

• Tells Spring which packages to scan for components like @Component, @Service, @Repository, and @Controller.
• By default, it scans the package of the main application class and all its sub-packages.
• Can be customized for modular projects.

Example:

@Configuration
@ComponentScan(basePackages = "com.example.services")
public class AppConfig { }

@Import

• Imports other configuration classes or beans into the current Spring context.
• Useful to organize configurations into multiple classes for better modularity.

Example:

@Configuration
@Import(DatabaseConfig.class)
public class AppConfig { }

@EventListener

• Marks a method to listen for Spring events (built-in or custom).
• Helps implement event-driven logic in your application.

Example:

@Component
public class UserEventListener {

    @EventListener
    public void handleUserCreated(UserCreatedEvent event) {
        System.out.println("User created: " + event.getUserName());
    }
}

Summary Table of Common Annotations

Best Practices

1. Always use @SpringBootApplication as the main entry point.

2. Prefer constructor-based dependency injection for mandatory beans.
3. Use stereotype annotations appropriately for modular design (@Service, @Repository, @Controller).
4. Use conditional annotations for environment-specific or optional beans.
5. Use @ConfigurationProperties for structured property mapping.
6. Avoid field injection in production for better testability and maintainability.