Spring Boot Introduction: Why It Exists and How to Build Your First App

package io.thecodeforge.bookstore;

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

/**
 * io.thecodeforge: The entry point for the Bookstore API.
 *
 * @SpringBootApplication is a composed annotation — three annotations in one:
 *
 *   @SpringBootConfiguration   (specialization of @Configuration)
 *   -> Marks this class as a source of @Bean definitions
 *   -> This class can declare beans directly if needed
 *
 *   @EnableAutoConfiguration
 *   -> Triggers auto-configuration by reading AutoConfiguration.imports
 *      from every JAR on the classpath
 *   -> Each listed config class is evaluated against @ConditionalOn guards
 *   -> Only classes where all conditions pass are activated
 *
 *   @ComponentScan
 *   -> Scans this package (io.thecodeforge.bookstore) and ALL sub-packages
 *   -> Finds @Component, @Service, @Repository, @Controller, @RestController
 *   -> Registers discovered classes as beans in the ApplicationContext
 *
 * Package placement rule: this class MUST be in the root package.
 * Controllers in io.thecodeforge.bookstore.controller -> found.
 * Controllers in com.other.controller -> NOT found. 404 on every endpoint.
 */
@SpringBootApplication
public class BookstoreApplication {

    public static void main(String[] args) {
        // SpringApplication.run:
        // 1. Creates the ApplicationContext (the Spring IoC container)
        // 2. Registers all auto-configured beans
        // 3. Scans for @Component classes and registers them
        // 4. Starts the embedded Tomcat server on port 8080
        SpringApplication.run(BookstoreApplication.class, args);
    }
}

package io.thecodeforge.bookstore.controller;

import io.thecodeforge.bookstore.model.Book;
import io.thecodeforge.bookstore.service.BookService;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

import java.util.List;

/**
 * io.thecodeforge: REST controller for book operations.
 *
 * Auto-configuration that made this controller work without any manual setup:
 *   - @RestController is found by @ComponentScan (part of @SpringBootApplication)
 *   - Spring MVC DispatcherServlet was auto-configured by WebMvcAutoConfiguration
 *     because spring-boot-starter-web is on the classpath
 *   - Jackson ObjectMapper was auto-configured by JacksonAutoConfiguration
 *     — Book objects are serialized to JSON automatically
 *   - Embedded Tomcat was started by EmbeddedWebServerFactoryCustomizerAutoConfiguration
 *
 * None of these required manual bean definitions. The classpath told Spring Boot
 * what to configure and the @ConditionalOn guards made it happen.
 */
@RestController
@RequestMapping("/api/books")
public class BookController {

    // Constructor injection: the correct pattern in production Spring Boot code.
    // Dependencies are final — immutable after construction.
    // Class is testable without a Spring context — new BookController(mockService).
    // Missing dependencies cause a compile-time error, not a runtime NullPointerException.
    private final BookService bookService;

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

    @GetMapping
    public ResponseEntity<List<Book>> getAllBooks() {
        return ResponseEntity.ok(bookService.findAllBooks());
    }

    @PostMapping
    @ResponseStatus(HttpStatus.CREATED)
    public Book createBook(@RequestBody Book newBook) {
        return bookService.saveBook(newBook);
    }

    @GetMapping("/{bookId}")
    public ResponseEntity<Book> getBookById(@PathVariable Long bookId) {
        // Optional.map avoids a null check — if the book exists, return 200 with it.
        // If it does not exist, return 404 with an empty body.
        // orElse(ResponseEntity.notFound().build()) handles the absent case cleanly.
        return bookService.findBookById(bookId)
                .map(ResponseEntity::ok)
                .orElse(ResponseEntity.notFound().build());
    }

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

// ── Model ────────────────────────────────────────────────────────────────────
package io.thecodeforge.bookstore.model;

import jakarta.persistence.*;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.Positive;

/**
 * io.thecodeforge: JPA entity — maps to the 'books' table.
 *
 * @Entity tells Hibernate this class represents a database table.
 * @Table(name = "books") overrides the default table name (would be 'book').
 * @Id marks the primary key field.
 * @GeneratedValue delegates key generation to the database.
 */
@Entity
@Table(name = "books")
public class Book {

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

    @NotBlank(message = "Title is required")
    @Column(nullable = false)
    private String title;

    @NotBlank(message = "Author is required")
    private String author;

    @Positive(message = "Price must be a positive number")
    private double price;

    // JPA requires a no-argument constructor — Hibernate uses it when
    // reconstructing objects from database rows
    public Book() {}

    public Book(String title, String author, double price) {
        this.title = title;
        this.author = author;
        this.price = price;
    }

    public Long getId() { return id; }
    public String getTitle() { return title; }
    public void setTitle(String title) { this.title = title; }
    public String getAuthor() { return author; }
    public void setAuthor(String author) { this.author = author; }
    public double getPrice() { return price; }
    public void setPrice(double price) { this.price = price; }
}

// ── Repository ───────────────────────────────────────────────────────────────
package io.thecodeforge.bookstore.repository;

import io.thecodeforge.bookstore.model.Book;
import org.springframework.data.jpa.repository.JpaRepository;

/**
 * JpaRepository<Book, Long> provides:
 *   findAll(), findById(), save(), delete(), count() — all auto-implemented.
 * Spring Data JPA generates the implementation at startup — no SQL, no boilerplate.
 * Add custom query methods by naming convention: findByAuthor(String author)
 * or by @Query annotation for complex queries.
 */
public interface BookRepository extends JpaRepository<Book, Long> {
    // Custom finder — Spring Data JPA generates: SELECT * FROM books WHERE author = ?
    java.util.List<Book> findByAuthor(String author);
}

// ── Service ──────────────────────────────────────────────────────────────────
package io.thecodeforge.bookstore.service;

import io.thecodeforge.bookstore.model.Book;
import io.thecodeforge.bookstore.repository.BookRepository;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
import java.util.List;
import java.util.Optional;

@Service
public class BookService {

    private final BookRepository bookRepository;

    // Constructor injection — final field, explicitly documented dependency
    public BookService(BookRepository bookRepository) {
        this.bookRepository = bookRepository;
    }

    // readOnly = true: signals Hibernate to skip dirty checking — performance optimization
    // for queries that do not modify data
    @Transactional(readOnly = true)
    public List<Book> findAllBooks() {
        return bookRepository.findAll();
    }

    @Transactional(readOnly = true)
    public Optional<Book> findBookById(Long id) {
        return bookRepository.findById(id);
    }

    @Transactional
    public Book saveBook(Book book) {
        return bookRepository.save(book);
    }

    @Transactional
    public void deleteBook(Long id) {
        bookRepository.deleteById(id);
    }
}

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
         https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <!--
      spring-boot-starter-parent provides:
        1. spring-boot-dependencies BOM — version management for 150+ libraries
        2. Default Maven plugin configurations (compiler at Java 17+, test runner)
        3. Resource filtering for application.properties placeholder resolution
      Without this parent, you would need to specify library versions individually
      and verify their compatibility manually.
    -->
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.3.0</version>
        <relativePath/>
    </parent>

    <groupId>io.thecodeforge</groupId>
    <artifactId>bookstore-api</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>bookstore-api</name>
    <description>Bookstore REST API — io.thecodeforge demonstration project</description>

    <properties>
        <!-- Java 21 LTS — the current long-term support version as of 2026 -->
        <java.version>21</java.version>
    </properties>

    <dependencies>
        <!--
          spring-boot-starter-web pulls in:
            spring-web, spring-webmvc, embedded Tomcat, Jackson JSON serialization.
          Without this: no HTTP server, no @RestController processing, no JSON output.
        -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <!--
          spring-boot-starter-data-jpa pulls in:
            Hibernate, Spring Data JPA, JDBC, HikariCP connection pool.
          Without this: no @Entity processing, no JpaRepository, no @Transactional.
        -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-data-jpa</artifactId>
        </dependency>

        <!--
          spring-boot-starter-validation pulls in:
            Hibernate Validator (JSR-303 implementation).
          Without this: @NotBlank, @Email, @Size annotations on DTOs are ignored.
        -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-validation</artifactId>
        </dependency>

        <!--
          spring-boot-starter-actuator adds:
            /actuator/health, /actuator/metrics, /actuator/info endpoints.
          Used for Kubernetes liveness/readiness probes and monitoring integration.
        -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-actuator</artifactId>
        </dependency>

        <!--
          H2 in-memory database — runtime scope means it is available at runtime
          but not included in the final production JAR.
          For development and testing only — replace with PostgreSQL driver in production.
        -->
        <dependency>
            <groupId>com.h2database</groupId>
            <artifactId>h2</artifactId>
            <scope>runtime</scope>
        </dependency>

        <!--
          spring-boot-starter-test pulls in:
            JUnit 5, Mockito, AssertJ, Spring Test, MockMvc, Testcontainers support.
          test scope — never included in the production JAR.
        -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <!--
              spring-boot-maven-plugin creates the executable Fat JAR.
              Without this plugin, mvn package produces a standard JAR that cannot
              run standalone — it lacks the Spring Boot launcher and embedded server.
              repackage goal wraps the standard JAR inside a Fat JAR with BOOT-INF layout.
            -->
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>