Spring Boot Annotations Explained with Examples

package com.javabytechie.library;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class LibraryApplication {

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

@SpringBootApplication
@ComponentScan(basePackages = {"com.javabytechie.library", "com.javabytechie.shared"})
public class LibraryApplication {
    // ...
}

@Component
public class SlugGenerator {

    public String toSlug(String title) {
        return title.trim()
                .toLowerCase()
                .replaceAll("[^a-z0-9]+", "-")
                .replaceAll("(^-|-$)", "");
    }
}

@Service
public class BookService {

    private final BookRepository bookRepository;

    public BookService(BookRepository bookRepository) {
        this.bookRepository = bookRepository;
    }

    public Book findByIsbn(String isbn) {
        return bookRepository.findByIsbn(isbn)
                .orElseThrow(() -> new BookNotFoundException(isbn));
    }
}

@Repository
public class JdbcBookRepository {

    private final JdbcClient jdbcClient;

    public JdbcBookRepository(JdbcClient jdbcClient) {
        this.jdbcClient = jdbcClient;
    }

    public int countAll() {
        return jdbcClient.sql("SELECT COUNT(*) FROM books")
                .query(Integer.class)
                .single();
    }
}

@Controller
public class HomeController {

    @GetMapping("/")
    public String home(Model model) {
        model.addAttribute("message", "Welcome to the library");
        return "home"; // renders templates/home.html
    }
}

@RestController
@RequestMapping("/api/books")
public class BookController {

    private final BookService bookService;

    public BookController(BookService bookService) {
        this.bookService = bookService;
    }

    @GetMapping("/{isbn}")
    public Book getBook(@PathVariable String isbn) {
        return bookService.findByIsbn(isbn); // converted to JSON automatically
    }
}

@Service
public class LoanService {

    private final BookService bookService;
    private final MemberService memberService;

    // Only one constructor, so @Autowired is optional
    public LoanService(BookService bookService, MemberService memberService) {
        this.bookService = bookService;
        this.memberService = memberService;
    }
}

public interface Notifier {
    void send(String to, String message);
}

@Component("emailNotifier")
public class EmailNotifier implements Notifier { /* ... */ }

@Component("smsNotifier")
public class SmsNotifier implements Notifier { /* ... */ }

@Service
public class ReminderService {

    private final Notifier notifier;

    public ReminderService(@Qualifier("smsNotifier") Notifier notifier) {
        this.notifier = notifier;
    }
}

@Primary
@Component("emailNotifier")
public class EmailNotifier implements Notifier {
    // used wherever a Notifier is injected without a qualifier
}

@Lazy
@Component
public class ReportGenerator {
    // created only when another bean first calls it
}

@Configuration
public class AppConfig {

    @Bean
    public Clock clock() {
        return Clock.systemUTC();
    }

    @Bean
    public RestClient catalogClient(RestClient.Builder builder) {
        return builder.baseUrl("https://catalog.example.com").build();
    }
}

library.name=City Library
library.max-loans=5

@Component
public class LibraryInfo {

    private final String name;
    private final int maxLoans;

    public LibraryInfo(@Value("${library.name}") String name,
                       @Value("${library.max-loans:3}") int maxLoans) {
        this.name = name;
        this.maxLoans = maxLoans;
    }
}

library.loan.max-books=5
library.loan.duration-days=14
library.loan.late-fee-per-day=0.50

@ConfigurationProperties(prefix = "library.loan")
public record LoanProperties(int maxBooks, int durationDays, BigDecimal lateFeePerDay) {
}

@SpringBootApplication
@ConfigurationPropertiesScan
public class LibraryApplication {
    // ...
}

@Configuration
public class PaymentConfig {

    @Bean
    @Profile("dev")
    public PaymentGateway fakePaymentGateway() {
        return new FakePaymentGateway(); // always approves, no real money
    }

    @Bean
    @Profile("prod")
    public PaymentGateway stripePaymentGateway(StripeProperties properties) {
        return new StripePaymentGateway(properties);
    }
}

@Service
@ConditionalOnProperty(name = "library.recommendations.enabled", havingValue = "true")
public class RecommendationService {
    // exists only when library.recommendations.enabled=true
}

@RestController
@RequestMapping("/api/books")
public class BookController {

    private final BookService bookService;

    public BookController(BookService bookService) {
        this.bookService = bookService;
    }

    @GetMapping
    public List<Book> search(@RequestParam(defaultValue = "") String title,
                             @RequestParam(defaultValue = "0") int page) {
        return bookService.search(title, page);
    }

    @GetMapping("/{id}")
    public Book getById(@PathVariable Long id) {
        return bookService.findById(id);
    }

    @PostMapping
    @ResponseStatus(HttpStatus.CREATED)
    public Book create(@RequestBody BookRequest request) {
        return bookService.create(request);
    }

    @PutMapping("/{id}")
    public Book update(@PathVariable Long id, @RequestBody BookRequest request) {
        return bookService.update(id, request);
    }

    @DeleteMapping("/{id}")
    @ResponseStatus(HttpStatus.NO_CONTENT)
    public void delete(@PathVariable Long id) {
        bookService.delete(id);
    }
}

@GetMapping("/greeting")
public String greeting(@RequestHeader(name = "Accept-Language", defaultValue = "en") String language) {
    return language.startsWith("fr") ? "Bonjour" : "Hello";
}

@Controller
public class HealthController {

    @GetMapping("/ping")
    @ResponseBody
    public String ping() {
        return "pong"; // sent as text, not treated as a template name
    }
}

@CrossOrigin(origins = "https://library-ui.example.com")
@RestController
@RequestMapping("/api/books")
public class BookController {
    // ...
}

public class BookNotFoundException extends RuntimeException {

    public BookNotFoundException(Long id) {
        super("Book " + id + " was not found");
    }
}

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(BookNotFoundException.class)
    public ProblemDetail handleNotFound(BookNotFoundException ex) {
        ProblemDetail problem = ProblemDetail.forStatusAndDetail(HttpStatus.NOT_FOUND, ex.getMessage());
        problem.setTitle("Book not found");
        return problem;
    }
}

{
  "type": "about:blank",
  "title": "Book not found",
  "status": 404,
  "detail": "Book 42 was not found",
  "instance": "/api/books/42"
}

@Entity
@Table(name = "books")
public class Book {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(nullable = false, length = 200)
    private String title;

    @Column(unique = true, length = 13)
    private String isbn;

    @ManyToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "author_id")
    private Author author;

    @Enumerated(EnumType.STRING)
    private BookStatus status;

    // constructors, getters and setters
}

@Entity
@Table(name = "authors")
public class Author {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String name;

    @OneToMany(mappedBy = "author")
    private List<Book> books = new ArrayList<>();

    // constructors, getters and setters
}

@Service
public class LoanService {

    private final BookRepository bookRepository;
    private final LoanRepository loanRepository;

    public LoanService(BookRepository bookRepository, LoanRepository loanRepository) {
        this.bookRepository = bookRepository;
        this.loanRepository = loanRepository;
    }

    @Transactional
    public Loan borrow(Long bookId, Long memberId) {
        Book book = bookRepository.findById(bookId).orElseThrow();
        book.markAsBorrowed();                                  // update 1
        return loanRepository.save(new Loan(book, memberId));   // update 2
        // both updates are saved together, or neither is
    }

    @Transactional(readOnly = true)
    public List<Loan> activeLoans(Long memberId) {
        return loanRepository.findByMemberIdAndReturnedFalse(memberId);
    }
}

@Aspect
@Component
public class TimingAspect {

    private static final Logger log = LoggerFactory.getLogger(TimingAspect.class);

    @Around("within(@org.springframework.stereotype.Service *)")
    public Object logDuration(ProceedingJoinPoint joinPoint) throws Throwable {
        long start = System.currentTimeMillis();
        try {
            return joinPoint.proceed();
        } finally {
            long took = System.currentTimeMillis() - start;
            log.info("{} took {} ms", joinPoint.getSignature().toShortString(), took);
        }
    }
}

public record BookRequest(

        @NotBlank(message = "Title is required")
        @Size(max = 200)
        String title,

        @Pattern(regexp = "\\d{13}", message = "ISBN must have 13 digits")
        String isbn,

        @NotNull
        @Positive
        Long authorId
) {
}

@PostMapping
@ResponseStatus(HttpStatus.CREATED)
public Book create(@Valid @RequestBody BookRequest request) {
    return bookService.create(request);
}

@Configuration
@EnableScheduling
public class SchedulingConfig {
}

@Component
public class OverdueLoanJob {

    private final LoanService loanService;

    public OverdueLoanJob(LoanService loanService) {
        this.loanService = loanService;
    }

    // Every weekday at 08:00
    @Scheduled(cron = "0 0 8 * * MON-FRI")
    public void sendOverdueReminders() {
        loanService.remindOverdueMembers();
    }

    // Every 10 minutes, counted from the end of the previous run
    @Scheduled(fixedDelay = 10, timeUnit = TimeUnit.MINUTES)
    public void refreshAvailability() {
        loanService.refreshAvailability();
    }
}

@Configuration
@EnableAsync
public class AsyncConfig {
}

@Service
public class EmailService {

    @Async
    public void sendWelcomeEmail(String address) {
        // runs in a separate thread; the caller continues immediately
    }

    @Async
    public CompletableFuture<Integer> sendNewsletter(List<String> addresses) {
        int sent = 0;
        // ... send each email and count it
        return CompletableFuture.completedFuture(sent);
    }
}

@Configuration
@EnableCaching
public class CacheConfig {
}

@Service
public class BookCatalogService {

    @Cacheable("books")
    public Book findByIsbn(String isbn) {
        // slow call to a database or remote API; runs only on a cache miss
        return loadFromCatalog(isbn);
    }

    @CachePut(value = "books", key = "#book.isbn")
    public Book update(Book book) {
        return saveToCatalog(book); // refreshes the cached copy
    }

    @CacheEvict(value = "books", key = "#isbn")
    public void delete(String isbn) {
        removeFromCatalog(isbn); // removes the cached copy
    }
}

@Component
public class CatalogLoader {

    private final Map<String, String> genres = new HashMap<>();

    @PostConstruct
    public void loadGenres() {
        genres.put("FIC", "Fiction");
        genres.put("SCI", "Science");
        // dependencies are already injected here
    }

    @PreDestroy
    public void cleanUp() {
        genres.clear();
        // close files, connections or thread pools here
    }
}

public record BookReturnedEvent(Long bookId, Long memberId) {
}

@Service
public class ReturnService {

    private final ApplicationEventPublisher events;

    public ReturnService(ApplicationEventPublisher events) {
        this.events = events;
    }

    public void returnBook(Long bookId, Long memberId) {
        // ... update the loan
        events.publishEvent(new BookReturnedEvent(bookId, memberId));
    }
}

@Component
public class WaitingListNotifier {

    @EventListener
    public void onBookReturned(BookReturnedEvent event) {
        // tell the next member on the waiting list that the book is available
    }

    @EventListener(ApplicationReadyEvent.class)
    public void onStartup() {
        // runs once the application is fully started
    }
}

@SpringBootTest
class LoanServiceIntegrationTest {

    @Autowired
    private LoanService loanService;

    @Test
    void borrowingABookCreatesALoan() {
        Loan loan = loanService.borrow(1L, 100L);

        assertThat(loan.getId()).isNotNull();
    }
}

@WebMvcTest(BookController.class)
class BookControllerTest {

    @Autowired
    private MockMvc mockMvc;

    @MockitoBean
    private BookService bookService;

    @Test
    void returnsBookAsJson() throws Exception {
        when(bookService.findById(7L)).thenReturn(new Book(7L, "Clean Code", "9780132350884"));

        mockMvc.perform(get("/api/books/7"))
                .andExpect(status().isOk())
                .andExpect(jsonPath("$.title").value("Clean Code"));
    }
}

@DataJpaTest
class BookRepositoryTest {

    @Autowired
    private BookRepository bookRepository;

    @Test
    void findsBookByIsbn() {
        bookRepository.save(new Book(null, "Refactoring", "9780134757599"));

        assertThat(bookRepository.findByIsbn("9780134757599")).isPresent();
    }
}