Beginner

package com.example.demo;

// SpringApplication - launcher utility
// @SpringBootApplication - meta-annotation combining @Configuration, @EnableAutoConfiguration, @ComponentScan
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

// @SpringBootApplication combines three annotations:
// 1. @Configuration - Declares this class as configuration source for bean definitions
// 2. @EnableAutoConfiguration - Tells Spring Boot to auto-configure based on classpath
// 3. @ComponentScan - Scans current package and sub-packages for @Component classes
@SpringBootApplication
public class DemoApplication {

    // Main method - Java application entry point
    // Spring Boot starts from here like any standard Java program
    public static void main(String[] args) {
        // SpringApplication.run() does:
        // 1. Creates ApplicationContext (Spring IoC container)
        // 2. Scans for @Component, @Service, @Repository, @Controller classes
        // 3. Auto-configures beans based on classpath dependencies
        // 4. Starts embedded Tomcat server (if spring-boot-starter-web present)
        // 5. Listens on port 8080 by default
        SpringApplication.run(DemoApplication.class, args);
        // => Console output: "Tomcat started on port(s): 8080 (http)"
        // => Application now ready to serve HTTP requests
    }
}

package com.example.demo.service;

// @Component - Marks class as Spring-managed bean for component scanning
// @Service - Specialization of @Component indicating service layer semantics
import org.springframework.stereotype.Component;
import org.springframework.stereotype.Service;

// @Component makes Spring create singleton instance during application startup
// Spring registers this bean in ApplicationContext under name "userRepository"
@Component
class UserRepository {

    // Simple finder method simulating database access
    // In real app, this would query database via JPA/JDBC
    public String findUser(Long id) {
        String result = "User" + id;
        // => For id=123, returns "User123"
        return result;
    }
}

// @Service is semantically identical to @Component
// Indicates this class contains business logic (service layer)
// Spring creates singleton and enables transaction management via AOP
@Service
public class UserService {

    // final field ensures immutability after construction
    // Cannot be reassigned after constructor completes
    private final UserRepository userRepository;

    // Constructor injection - Spring's recommended dependency injection method
    // @Autowired optional on single constructor (since Spring 4.3)
    // Spring automatically finds UserRepository bean and passes it here
    public UserService(UserRepository userRepository) {
        // Spring injects the singleton UserRepository instance
        // This assignment happens during ApplicationContext initialization
        this.userRepository = userRepository;
        // => userRepository is now non-null, guaranteed by Spring container
    }

    // Business method delegating to repository
    // This method is testable - can pass mock UserRepository in tests
    public String getUser(Long id) {
        String user = userRepository.findUser(id);
        // => For id=123, user is "User123"
        return user;
    }
}

// WRONG: Field injection anti-pattern
// @Autowired
// private UserRepository userRepository;
// Problems:
// 1. Cannot make field final (allows null state)
// 2. Harder to test (requires reflection or Spring test context)
// 3. Hides dependencies (not visible in constructor signature)
// 4. Allows circular dependencies (constructor injection fails fast)

package com.example.demo.config;

// JSR-250 annotations for lifecycle callbacks
import jakarta.annotation.PostConstruct;
import jakarta.annotation.PreDestroy;
// Bean definition and scope configuration
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Scope;
import org.springframework.stereotype.Component;

// @Component with default singleton scope
// Spring creates exactly one instance during application startup
// Same instance shared across entire application lifecycle
@Component
public class DatabaseConnection {

    // @PostConstruct called AFTER constructor and AFTER dependency injection
    // Use for initialization that requires injected dependencies
    // Called exactly once per bean instance
    @PostConstruct
    public void init() {
        // Initialization logic (connect to database, open resources)
        System.out.println("Connecting to database...");
        // => Output appears during application startup
        // => Before any HTTP requests processed
    }

    // @PreDestroy called during application shutdown
    // Spring calls this before destroying bean instance
    // Use for cleanup (close connections, flush caches, release resources)
    @PreDestroy
    public void cleanup() {
        // Cleanup logic executed during graceful shutdown
        System.out.println("Closing database connection...");
        // => Output appears when Spring context shuts down
        // => Ensures connections closed properly
    }
}

// @Configuration indicates this class contains @Bean factory methods
// Spring processes this during component scanning
@Configuration
class AppConfig {

    // @Bean method creates Spring-managed bean
    // Method name becomes bean name unless overridden
    // @Scope("prototype") creates NEW instance every time bean requested
    @Bean
    @Scope("prototype")
    public RequestProcessor processor() {
        RequestProcessor instance = new RequestProcessor();
        // => New instance created on each injection or ApplicationContext.getBean() call
        // => NOT shared across injection points
        return instance;
    }

    // @Bean without @Scope defaults to singleton
    // Spring creates exactly one instance and caches it
    // All injection points receive same shared instance
    @Bean
    public CacheManager cacheManager() {
        CacheManager singleton = new CacheManager();
        // => Single instance created during startup
        // => Cached and reused for entire application lifetime
        return singleton;
    }
}

// Placeholder classes for demonstration
class RequestProcessor {
    // In real app: processes individual requests with request-scoped state
}

class CacheManager {
    // In real app: manages application-wide cache (shared state)
}

package com.example.demo;

// Spring stereotype annotations
import org.springframework.stereotype.Component;
import org.springframework.stereotype.Repository;
import org.springframework.stereotype.Service;
import org.springframework.web.bind.annotation.RestController;

// @Component - Generic stereotype for any Spring-managed component
// Use when class doesn't fit other stereotypes (Service, Repository, Controller)
@Component
class EmailValidator {

    // Validation logic example
    // In real app: comprehensive email format validation
    public boolean isValid(String email) {
        boolean valid = email.contains("@");
        // => Returns true if email contains '@', false otherwise
        return valid;
    }
}

// @Repository - Data access layer stereotype
// Enables Spring's DataAccessException translation
// Spring converts database-specific exceptions (SQLException) to Spring exceptions
// Allows switching databases without changing exception handling code
@Repository
class UserRepository {
    // In real app: JPA/JDBC code to query database
    // Spring translates PersistenceException/SQLException to DataAccessException
}

// @Service - Business logic layer stereotype
// Indicates this class contains business rules and orchestration
// Enables transaction management via @Transactional
@Service
class UserService {
    // In real app: business logic coordinating repositories
    // Transaction boundaries typically placed here
}

// @RestController - Web layer stereotype
// Combines @Controller (request handler) + @ResponseBody (JSON serialization)
// Methods return domain objects serialized to JSON automatically
@RestController
class UserController {
    // In real app: handles HTTP requests and delegates to service layer
    // Returns JSON responses via Jackson auto-configuration
}

package com.example.demo.controller;

// Spring MVC annotations for request mapping
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;

// @RestController = @Controller + @ResponseBody on all methods
// Methods return data objects that Jackson serializes to JSON
// No view resolution - raw data returned as HTTP response body
@RestController
public class HelloController {

    // @GetMapping maps HTTP GET requests to this method
    // Equivalent to @RequestMapping(method = RequestMethod.GET)
    // Accessible at GET http://localhost:8080/hello
    @GetMapping("/hello")
    public String hello() {
        String greeting = "Hello, Spring Boot!";
        // => Returned string becomes HTTP response body
        // => Content-Type: text/plain
        return greeting;
    }

    // @GetMapping returning domain object
    // Jackson automatically serializes User to JSON
    // Spring Boot auto-configures ObjectMapper for this
    @GetMapping("/user")
    public User getUser() {
        User user = new User("Alice", 30);
        // => Jackson serializes to: {"name":"Alice","age":30}
        // => Content-Type: application/json
        return user;
    }

    // @PostMapping maps HTTP POST requests
    // @RequestBody tells Spring to deserialize JSON request body to User object
    // Jackson reads JSON from request and creates User instance
    @PostMapping("/user")
    public User createUser(@RequestBody User user) {
        // user object already populated from JSON request body
        // => POST with {"name":"Bob","age":25} creates User(name="Bob", age=25)

        // Echoing back received user (in real app: save to database)
        return user;
        // => Returns same JSON: {"name":"Bob","age":25}
    }
}

// Java 17 record - immutable data carrier
// Compiler generates constructor, getters, equals(), hashCode(), toString()
// Perfect for DTOs (Data Transfer Objects)
record User(String name, int age) {
    // => Jackson serializes fields to JSON properties
    // => name field becomes "name" JSON property
    // => age field becomes "age" JSON property
}

package com.example.demo.controller;

// Spring MVC parameter annotations
import org.springframework.web.bind.annotation.*;

// @RestController returns JSON responses
// @RequestMapping("/api/users") sets base path for all methods
@RestController
@RequestMapping("/api/users")
public class UserController {

    // @PathVariable extracts {id} from URL path
    // GET /api/users/123 maps to getUserById(123)
    @GetMapping("/{id}")
    public String getUserById(@PathVariable Long id) {
        // id extracted from URL path segment
        // => For /api/users/123, id = 123L
        String response = "User ID: " + id;
        // => Returns "User ID: 123"
        return response;
    }

    // Multiple path variables in single URL
    // GET /api/users/123/posts/456
    @GetMapping("/{userId}/posts/{postId}")
    public String getUserPost(@PathVariable Long userId, @PathVariable Long postId) {
        // Both path variables extracted and type-converted to Long
        // => For /api/users/123/posts/456:
        //    userId = 123L, postId = 456L
        String response = "User " + userId + ", Post " + postId;
        // => Returns "User 123, Post 456"
        return response;
    }

    // @RequestParam extracts query parameters from URL
    // GET /api/users?page=0&size=20
    @GetMapping
    public String getUsers(
        @RequestParam(defaultValue = "0") int page,
        @RequestParam(defaultValue = "10") int size
    ) {
        // defaultValue used when parameter not provided
        // => GET /api/users uses page=0, size=10
        // => GET /api/users?page=2&size=20 uses page=2, size=20

        String response = "Page " + page + ", Size " + size;
        // => For ?page=0&size=20, returns "Page 0, Size 20"
        return response;
    }

    // Optional query parameter with required=false
    // GET /api/users/search?name=Alice or GET /api/users/search
    @GetMapping("/search")
    public String search(@RequestParam(required = false) String name) {
        if (name == null) {
            // No name parameter provided
            String noFilter = "No filter applied";
            // => Returns when called as /api/users/search
            return noFilter;
        }

        String filtered = "Searching for: " + name;
        // => For ?name=Alice, returns "Searching for: Alice"
        return filtered;
    }
}

package com.example.demo.controller;

// HTTP response customization
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
// Spring MVC annotations
import org.springframework.web.bind.annotation.*;

// Immutable DTO for creating users
// Java record generates constructor, getters, equals, hashCode automatically
record CreateUserRequest(String username, String email) {
    // => Jackson deserializes JSON {"username":"alice","email":"alice@example.com"}
    //    to CreateUserRequest(username="alice", email="alice@example.com")
}

// Immutable DTO for user responses
// Includes ID field that's generated server-side
record UserResponse(Long id, String username, String email) {
    // => Jackson serializes to {"id":1,"username":"alice","email":"alice@example.com"}
}

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

    // POST /api/users with JSON body
    // @RequestBody deserializes JSON to CreateUserRequest
    @PostMapping
    public ResponseEntity<UserResponse> createUser(@RequestBody CreateUserRequest request) {
        // Jackson already deserialized JSON to request object
        // => request.username() and request.email() available

        // Simulate saving to database (in real app: use JPA repository)
        UserResponse user = new UserResponse(1L, request.username(), request.email());
        // => Created user with auto-generated ID=1

        // ResponseEntity builder for full HTTP response control
        ResponseEntity<UserResponse> response = ResponseEntity
            .status(HttpStatus.CREATED)                    // => 201 Created status
            .header("Location", "/api/users/1")             // => Location header for new resource
            .body(user);                                     // => Response body as JSON

        // => HTTP/1.1 201 Created
        // => Location: /api/users/1
        // => Content-Type: application/json
        // => Body: {"id":1,"username":"alice","email":"alice@example.com"}
        return response;
    }

    // GET /api/users/1
    // Returns existing user or 404
    @GetMapping("/{id}")
    public ResponseEntity<UserResponse> getUser(@PathVariable Long id) {
        // Simulate database lookup (in real app: use repository.findById())
        UserResponse user = new UserResponse(id, "alice", "alice@example.com");

        ResponseEntity<UserResponse> response = ResponseEntity.ok(user);
        // => Shorthand for .status(HttpStatus.OK).body(user)
        // => HTTP/1.1 200 OK
        // => Body: {"id":1,"username":"alice","email":"alice@example.com"}
        return response;
    }

    // DELETE /api/users/1
    // Returns 204 No Content (successful deletion with no response body)
    @DeleteMapping("/{id}")
    public ResponseEntity<Void> deleteUser(@PathVariable Long id) {
        // Simulate deletion (in real app: repository.deleteById(id))

        ResponseEntity<Void> response = ResponseEntity.noContent().build();
        // => HTTP/1.1 204 No Content
        // => No response body
        return response;
    }
}

package com.example.demo.controller;

// HTTP response handling
import org.springframework.http.ResponseEntity;
// Spring MVC annotations
import org.springframework.web.bind.annotation.*;
// URI building
import java.net.URI;
// Java collections
import java.util.*;

// Simple Product DTO
record Product(Long id, String name, double price) {}

@RestController
@RequestMapping("/api/products")
public class ProductController {

    // In-memory storage (in real app: use JPA repository)
    private final Map<Long, Product> products = new HashMap<>();
    private Long nextId = 1L;

    // POST - Create new resource
    // Returns 201 Created with Location header pointing to new resource
    @PostMapping
    public ResponseEntity<Product> create(@RequestBody Product product) {
        // Generate ID for new product
        Long assignedId = nextId++;
        // => First call: assignedId=1, nextId becomes 2

        Product created = new Product(assignedId, product.name(), product.price());
        products.put(created.id(), created);
        // => Stored in map: {1 -> Product(1, "Laptop", 999.99)}

        ResponseEntity<Product> response = ResponseEntity
            .created(URI.create("/api/products/" + created.id()))  // => Location: /api/products/1
            .body(created);                                         // => Response body with product

        // => HTTP/1.1 201 Created
        // => Location: /api/products/1
        // => Body: {"id":1,"name":"Laptop","price":999.99}
        return response;
    }

    // GET - Retrieve resource
    // Returns 200 OK if found, 404 Not Found if not found
    @GetMapping("/{id}")
    public ResponseEntity<Product> get(@PathVariable Long id) {
        Product product = products.get(id);
        // => Lookup product by ID in map

        if (product == null) {
            // Product not found - return 404
            ResponseEntity<Product> notFound = ResponseEntity.notFound().build();
            // => HTTP/1.1 404 Not Found
            // => No response body
            return notFound;
        }

        ResponseEntity<Product> found = ResponseEntity.ok(product);
        // => HTTP/1.1 200 OK
        // => Body: {"id":1,"name":"Laptop","price":999.99}
        return found;
    }

    // PUT - Update entire resource
    // Returns 200 OK with updated resource
    @PutMapping("/{id}")
    public ResponseEntity<Product> update(@PathVariable Long id, @RequestBody Product product) {
        // Create updated product with provided ID
        Product updated = new Product(id, product.name(), product.price());
        // => Replaces entire resource (PUT semantics)

        products.put(id, updated);
        // => Updates map entry

        ResponseEntity<Product> response = ResponseEntity.ok(updated);
        // => HTTP/1.1 200 OK
        // => Body: {"id":1,"name":"Gaming Laptop","price":1299.99}
        return response;
    }

    // DELETE - Remove resource
    // Returns 204 No Content (successful deletion)
    @DeleteMapping("/{id}")
    public ResponseEntity<Void> delete(@PathVariable Long id) {
        products.remove(id);
        // => Removes entry from map (returns null if not found)

        ResponseEntity<Void> response = ResponseEntity.noContent().build();
        // => HTTP/1.1 204 No Content
        // => No response body (Void type)
        return response;
    }
}

package com.example.demo.controller;

// Spring MVC annotations
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

// Book DTO
record Book(String title, String author) {}

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

    // Default content negotiation
    // Spring Boot auto-configures JSON via Jackson
    @GetMapping
    public Book getBook() {
        Book book = new Book("Spring Boot in Action", "Craig Walls");
        // => Jackson serializes to JSON by default
        // => Content-Type: application/json
        // => {"title":"Spring Boot in Action","author":"Craig Walls"}
        return book;
    }

    // Explicit JSON production
    // produces attribute restricts supported media types
    @GetMapping(value = "/json", produces = "application/json")
    public Book getBookJson() {
        Book book = new Book("Spring Boot in Action", "Craig Walls");
        // => Only responds to requests with Accept: application/json
        // => Returns 406 Not Acceptable for other Accept headers
        return book;
    }

    // Multiple content types support
    // Requires XML dependency: jackson-dataformat-xml
    // Add to pom.xml:
    // <dependency>
    //   <groupId>com.fasterxml.jackson.dataformat</groupId>
    //   <artifactId>jackson-dataformat-xml</artifactId>
    // </dependency>
    @GetMapping(value = "/multi", produces = {"application/json", "application/xml"})
    public Book getBookMulti() {
        Book book = new Book("Spring Boot in Action", "Craig Walls");

        // Client sends Accept: application/json
        // => Spring returns JSON: {"title":"Spring Boot in Action","author":"Craig Walls"}

        // Client sends Accept: application/xml
        // => Spring returns XML: <Book><title>Spring Boot in Action</title>...</Book>

        // Client sends Accept: text/html
        // => Spring returns 406 Not Acceptable (not in produces list)

        return book;
    }
}

package com.example.demo.model;

// JPA annotations for entity mapping
import jakarta.persistence.*;

// @Entity marks this class as JPA entity
// JPA will map this to database table
@Entity
@Table(name = "users")  // Maps to "users" table (optional if class name matches table)
public class User {

    // @Id marks primary key field
    // @GeneratedValue tells database to auto-generate values
    // IDENTITY strategy uses database auto-increment (MySQL, PostgreSQL)
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    // => Database generates: 1, 2, 3, ... automatically

    // @Column specifies column constraints
    // nullable=false -> NOT NULL constraint
    // unique=true -> UNIQUE constraint
    @Column(nullable = false, unique = true)
    private String email;
    // => SQL: email VARCHAR(255) NOT NULL UNIQUE

    // No @Column means defaults (nullable, non-unique)
    private String name;
    // => SQL: name VARCHAR(255)

    // JPA requires no-arg constructor (can be protected)
    protected User() {}

    // Public constructor for application code
    public User(String email, String name) {
        this.email = email;
        this.name = name;
    }

    // Getters and setters required for JPA
    public Long getId() { return id; }
    public void setId(Long id) { this.id = id; }

    public String getEmail() { return email; }
    public void setEmail(String email) { this.email = email; }

    public String getName() { return name; }
    public void setName(String name) { this.name = name; }
}

package com.example.demo.repository;

// Entity class
import com.example.demo.model.User;
// Spring Data JPA repository interface
import org.springframework.data.jpa.repository.JpaRepository;

// JpaRepository<Entity, ID> interface
// Entity = User (entity class)
// ID = Long (primary key type)
// Spring generates implementation at runtime via proxy
public interface UserRepository extends JpaRepository<User, Long> {
    // No implementation code needed!
    // Spring Data JPA generates implementation automatically

    // Inherited methods from JpaRepository:

    // save(user)
    // => INSERT if id=null, UPDATE if id exists
    // => Returns saved entity with generated ID

    // findById(id)
    // => SELECT * FROM users WHERE id = ?
    // => Returns Optional<User> (empty if not found)

    // findAll()
    // => SELECT * FROM users
    // => Returns List<User>

    // deleteById(id)
    // => DELETE FROM users WHERE id = ?

    // count()
    // => SELECT COUNT(*) FROM users
    // => Returns total number of records

    // existsById(id)
    // => SELECT COUNT(*) FROM users WHERE id = ? (optimized)
    // => Returns boolean
}

package com.example.demo.repository;

// Entity class
import com.example.demo.model.User;
// Spring Data JPA
import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.data.jpa.repository.Query;
import org.springframework.data.repository.query.Param;
// Java collections
import java.util.List;

public interface UserRepository extends JpaRepository<User, Long> {

    // Derived query method - Spring parses method name into query
    // Naming convention: findBy<Property><Operation>
    List<User> findByEmailContaining(String email);
    // => Spring generates: SELECT * FROM users WHERE email LIKE '%?%'
    // => For email="example", finds "user@example.com", "example@test.com"
    // => Returns List<User> (empty if no matches)

    // JPQL query with named parameter
    // JPQL queries use entity names (User), not table names (users)
    // :name is named parameter placeholder
    @Query("SELECT u FROM User u WHERE u.name = :name")
    List<User> findByName(@Param("name") String name);
    // => SELECT * FROM users WHERE name = ?
    // => Named parameter :name bound to method parameter name
    // => Returns List<User> matching name exactly

    // JPQL with multiple parameters and LIKE operator
    // %:domain in JPQL becomes %? in SQL
    @Query("SELECT u FROM User u WHERE u.name = :name AND u.email LIKE %:domain")
    List<User> findByNameAndEmailDomain(@Param("name") String name, @Param("domain") String domain);
    // => SELECT * FROM users WHERE name = ? AND email LIKE '%?'
    // => findByNameAndEmailDomain("Alice", "example.com") finds Alice with email ending in example.com
    // => Returns List<User>

    // Native SQL query for database-specific features
    // nativeQuery=true uses raw SQL instead of JPQL
    // ?1 is positional parameter (first method parameter)
    @Query(value = "SELECT * FROM users WHERE email = ?1", nativeQuery = true)
    User findByEmailNative(String email);
    // => Raw SQL executed directly on database
    // => Returns single User (null if not found)
    // => Use for PostgreSQL-specific syntax, MySQL functions, etc.

    // Native SQL with named parameters and database-specific syntax
    // LIMIT 1 is MySQL/PostgreSQL syntax (won't work on Oracle without modification)
    @Query(value = "SELECT * FROM users WHERE name = :name ORDER BY id DESC LIMIT 1", nativeQuery = true)
    User findLatestByName(@Param("name") String name);
    // => Finds most recently created user with given name
    // => ORDER BY id DESC sorts newest first
    // => LIMIT 1 returns only first result
    // => Returns single User (null if none found)
}

package com.example.demo.model;

// JPA relationship annotations
import jakarta.persistence.*;
// Java collections
import java.util.List;

// Parent entity in one-to-many relationship
@Entity
@Table(name = "users")
public class User {

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

    private String name;

    // One user has many orders (one-to-many)
    // mappedBy="user" means Order entity owns the relationship
    // Order.user field is the owning side (has foreign key)
    // fetch=LAZY means orders loaded only when accessed (default for @OneToMany)
    @OneToMany(mappedBy = "user", fetch = FetchType.LAZY)
    private List<Order> orders;
    // => No join table created
    // => Foreign key user_id stored in orders table
    // => orders loaded lazily: SELECT * FROM orders WHERE user_id = ?
    //    only when user.getOrders() called

    // Getters/setters
    public Long getId() { return id; }
    public void setId(Long id) { this.id = id; }

    public String getName() { return name; }
    public void setName(String name) { this.name = name; }

    public List<Order> getOrders() { return orders; }
    public void setOrders(List<Order> orders) { this.orders = orders; }
}

// Child entity in one-to-many relationship
@Entity
@Table(name = "orders")
public class Order {

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

    private String product;

    // Many orders belong to one user (many-to-one)
    // Owning side of relationship (has foreign key column)
    // fetch=LAZY means user loaded only when accessed (default for @ManyToOne is EAGER!)
    @ManyToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "user_id")  // Foreign key column in orders table
    private User user;
    // => Creates column: user_id BIGINT
    // => Foreign key constraint: FOREIGN KEY (user_id) REFERENCES users(id)
    // => user loaded lazily: SELECT * FROM users WHERE id = ?
    //    only when order.getUser() called

    // Getters/setters
    public Long getId() { return id; }
    public void setId(Long id) { this.id = id; }

    public String getProduct() { return product; }
    public void setProduct(String product) { this.product = product; }

    public User getUser() { return user; }
    public void setUser(User user) { this.user = user; }
}

// ANTI-PATTERN: EAGER fetching
// @OneToMany(mappedBy = "user", fetch = FetchType.EAGER)
// private List<Order> orders;
// Problems:
// 1. Loads ALL orders every time user fetched (even if not needed)
// 2. Cannot paginate or filter orders
// 3. Causes N+1 queries when fetching multiple users:
//    SELECT * FROM users                  -- 1 query
//    SELECT * FROM orders WHERE user_id=1 -- N queries (one per user)
//    SELECT * FROM orders WHERE user_id=2
//    ...
// Solution: Use LAZY (default) and fetch joins when needed:
// @Query("SELECT u FROM User u LEFT JOIN FETCH u.orders WHERE u.id = :id")

package com.example.demo.repository;

// Entity class
import com.example.demo.model.User;
// Spring Data pagination
import org.springframework.data.domain.Page;
import org.springframework.data.domain.Pageable;
// Spring Data JPA repository
import org.springframework.data.jpa.repository.JpaRepository;

public interface UserRepository extends JpaRepository<User, Long> {

    // Pageable parameter enables pagination and sorting
    // Spring generates query with LIMIT/OFFSET (or database equivalent)
    Page<User> findByNameContaining(String name, Pageable pageable);
    // => SELECT * FROM users WHERE name LIKE '%?%' LIMIT ? OFFSET ?
    // => Also executes: SELECT COUNT(*) FROM users WHERE name LIKE '%?%'
    //    to get total count for pagination metadata
    // => Returns Page<User> with content + metadata (totalPages, totalElements, etc.)
}

package com.example.demo.controller;

// Entity class
import com.example.demo.model.User;
// Repository
import com.example.demo.repository.UserRepository;
// Spring Data pagination classes
import org.springframework.data.domain.*;
// Spring MVC annotations
import org.springframework.web.bind.annotation.*;

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

    private final UserRepository userRepository;

    // Constructor injection
    public UserPageController(UserRepository userRepository) {
        this.userRepository = userRepository;
    }

    // GET /api/users?page=0&size=20&sort=name,asc
    // page: zero-based page number (default 0)
    // size: number of records per page (default 10)
    // sort: property,direction (default id)
    @GetMapping
    public Page<User> getUsers(
        @RequestParam(defaultValue = "0") int page,
        @RequestParam(defaultValue = "10") int size,
        @RequestParam(defaultValue = "id") String sortBy
    ) {
        // Create Pageable object for pagination and sorting
        // PageRequest combines page number, size, and sort criteria
        Pageable pageable = PageRequest.of(page, size, Sort.by(sortBy).ascending());
        // => For page=0, size=10, sortBy=name:
        //    Pageable{page=0, size=10, sort=name: ASC}

        Page<User> result = userRepository.findAll(pageable);
        // => Executes: SELECT * FROM users ORDER BY name ASC LIMIT 10 OFFSET 0
        // => Also executes: SELECT COUNT(*) FROM users

        // Page<User> contains:
        // - content: List<User> for current page
        // - totalElements: total records across all pages
        // - totalPages: number of pages (totalElements / size)
        // - number: current page number (0-based)
        // - size: records per page
        // - first: boolean (is this first page?)
        // - last: boolean (is this last page?)

        return result;
        // => JSON response:
        // {
        //   "content": [{"id":1,"name":"Alice"}, ...],
        //   "totalElements": 100,
        //   "totalPages": 10,
        //   "size": 10,
        //   "number": 0,
        //   "first": true,
        //   "last": false
        // }
    }
}

-- src/main/resources/schema.sql
-- Executed during Spring Boot startup (before application ready)
-- Creates database schema (tables, indexes, constraints)

CREATE TABLE IF NOT EXISTS users (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,  -- Auto-increment primary key
    email VARCHAR(255) NOT NULL UNIQUE,     -- Unique constraint on email
    name VARCHAR(255)                       -- Nullable name field
);
-- => Spring executes this on startup
-- => IF NOT EXISTS prevents errors on restart

-- src/main/resources/data.sql
-- Executed after schema.sql completes
-- Populates tables with initial data

INSERT INTO users (email, name) VALUES ('alice@example.com', 'Alice');
-- => Inserts first user (id auto-generated to 1)

INSERT INTO users (email, name) VALUES ('bob@example.com', 'Bob');
-- => Inserts second user (id auto-generated to 2)

-- Note: These run on every startup!
-- Use ON CONFLICT or check existence to prevent duplicates

<!-- pom.xml -->
<!-- Add Flyway dependency for versioned migrations -->
<dependency>
    <groupId>org.flywaydb</groupId>
    <artifactId>flyway-core</artifactId>
</dependency>
<!-- => Spring Boot auto-configures Flyway when dependency present -->

-- src/main/resources/db/migration/V1__Create_users_table.sql
-- Flyway migration file naming: V{version}__{description}.sql
-- Version number must be unique and incrementing (1, 2, 3, ...)
-- __ (double underscore) separates version from description

CREATE TABLE users (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    email VARCHAR(255) NOT NULL UNIQUE,
    name VARCHAR(255)
);
-- => Flyway executes this ONCE (tracks in flyway_schema_history table)
-- => Subsequent startups skip this migration
-- => New migrations add V2__, V3__, etc.

# src/main/resources/application.properties
# Flyway configuration (optional - sensible defaults)

spring.flyway.enabled=true
# => Enables Flyway (default true when dependency present)

spring.flyway.baseline-on-migrate=true
# => Create baseline for existing databases
# => Allows Flyway to work with non-empty databases

# src/main/resources/application.properties
# Application-specific properties

app.name=My Spring Boot App
# => Custom property for application name

app.version=1.0.0
# => Application version number

app.max-users=100
# => Business rule configuration

# Spring Boot auto-configuration properties
spring.datasource.url=jdbc:h2:mem:testdb
# => H2 in-memory database URL
# => Spring Boot auto-configures DataSource from this

spring.datasource.username=sa
# => Database username (H2 default)

spring.datasource.password=
# => Empty password (H2 allows this for in-memory DB)

package com.example.demo.config;

// @Value annotation for property injection
import org.springframework.beans.factory.annotation.Value;
// Spring stereotype
import org.springframework.stereotype.Component;

@Component
public class AppProperties {

    // @Value injects property value during bean creation
    // ${app.name} references property key from application.properties
    @Value("${app.name}")
    private String appName;
    // => Field populated with "My Spring Boot App" at startup
    // => Happens during dependency injection phase

    @Value("${app.version}")
    private String version;
    // => Populated with "1.0.0"

    // Default value with colon syntax: ${property:defaultValue}
    // If app.max-users not defined, uses 50
    @Value("${app.max-users:50}")
    private int maxUsers;
    // => Uses 100 from properties
    // => Falls back to 50 if property missing
    // => Type conversion happens automatically (String "100" -> int 100)

    // Public method accessing injected properties
    public String getInfo() {
        String info = appName + " v" + version + " (max users: " + maxUsers + ")";
        // => "My Spring Boot App v1.0.0 (max users: 100)"
        return info;
    }
}

package com.example.demo.config;

// Configuration and bean definition annotations
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
// Third-party libraries
import org.springframework.web.client.RestTemplate;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.SerializationFeature;

// @Configuration marks class as source of bean definitions
// Spring processes this during component scanning
@Configuration
public class AppConfig {

    // @Bean method creates Spring-managed bean
    // Method name becomes bean name ("restTemplate") unless overridden
    // Return type defines bean type for dependency injection
    @Bean
    public RestTemplate restTemplate() {
        RestTemplate client = new RestTemplate();
        // => Creates HTTP client
        // => Spring manages lifecycle (creation, destruction)
        // => Singleton by default (one instance shared)
        return client;
    }

    // Custom ObjectMapper bean
    // Replaces Spring Boot's auto-configured ObjectMapper
    @Bean
    public ObjectMapper objectMapper() {
        ObjectMapper mapper = new ObjectMapper();

        // Enable pretty-printing for JSON output
        mapper.enable(SerializationFeature.INDENT_OUTPUT);
        // => JSON responses formatted with newlines and indentation
        // => Easier to debug API responses

        // Can configure other Jackson features:
        // mapper.disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS);
        // mapper.setSerializationInclusion(Include.NON_NULL);

        return mapper;
        // => This ObjectMapper used for all JSON serialization/deserialization
    }

    // Bean that depends on another bean
    // Spring automatically injects restTemplate parameter
    @Bean
    public ApiClient apiClient(RestTemplate restTemplate) {
        // restTemplate parameter injected by Spring
        // => Spring finds RestTemplate bean defined above
        // => Passes it as constructor argument

        ApiClient client = new ApiClient(restTemplate);
        // => Creates ApiClient with injected RestTemplate
        return client;
    }
}

// Example third-party integration class
class ApiClient {
    private final RestTemplate restTemplate;

    // Constructor accepting RestTemplate dependency
    public ApiClient(RestTemplate restTemplate) {
        this.restTemplate = restTemplate;
        // => Injected RestTemplate available for HTTP calls
    }
}

# src/main/resources/application-dev.properties
# Development profile configuration
# Activated with: spring.profiles.active=dev

spring.datasource.url=jdbc:h2:mem:devdb
# => H2 in-memory database for fast dev cycles
# => Data lost on restart (acceptable for dev)

app.feature.debug=true
# => Enable debug features (detailed logging, mock data)

logging.level.root=DEBUG
# => Verbose logging for troubleshooting
# => Shows all SQL queries, HTTP requests, etc.

# src/main/resources/application-prod.properties
# Production profile configuration
# Activated with: spring.profiles.active=prod

spring.datasource.url=jdbc:postgresql://prod-server:5432/myapp
# => PostgreSQL production database
# => Persistent storage with backups

app.feature.debug=false
# => Disable debug features (no mock data, no verbose logs)

logging.level.root=WARN
# => Minimal logging for performance
# => Only warnings and errors logged

package com.example.demo.config;

// Configuration and bean annotations
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;

@Configuration
public class DataSourceConfig {

    // Bean active only when "dev" profile active
    // @Profile annotation controls bean creation based on active profiles
    @Bean
    @Profile("dev")
    public DataSource devDataSource() {
        DataSource ds = new H2DataSource();
        // => Only created when --spring.profiles.active=dev
        // => Not created in prod profile
        return ds;
    }

    // Bean active only when "prod" profile active
    @Bean
    @Profile("prod")
    public DataSource prodDataSource() {
        DataSource ds = new PostgresDataSource();
        // => Only created when --spring.profiles.active=prod
        // => Not created in dev profile
        return ds;
    }

    // Multiple profiles can be specified
    // @Profile({"dev", "staging"}) - active in dev OR staging
    // @Profile("!prod") - active when prod NOT active
}

// Placeholder classes for demonstration
class H2DataSource {}
class PostgresDataSource {}
class DataSource {}