Intermediate

// pom.xml
<dependency>
// => Code line
  <groupId>org.springframework.boot</groupId>
  // => Code line
  <artifactId>spring-boot-starter-data-jpa</artifactId>
  // => Code line
</dependency>
// => Code line
 
// Domain model
@Entity
// => Annotation applied
public class BankAccount {
    // => Begins block
  @Id @GeneratedValue
  // => Annotation applied
  private Long id;
  // => Declares id field of type Long
  private String owner;
  // => Declares owner field of type String
  private BigDecimal balance;
  // => Declares balance field of type BigDecimal
  // constructors, getters, setters
}
// => Block delimiter
 
@Entity
// => Annotation applied
public class TransferLog {
    // => Begins block
  @Id @GeneratedValue
  // => Annotation applied
  private Long id;
  // => Declares id field of type Long
  private Long fromAccount;
  // => Declares fromAccount field of type Long
  private Long toAccount;
  // => Declares toAccount field of type Long
  private BigDecimal amount;
  // => Declares amount field of type BigDecimal
  private LocalDateTime timestamp;
  // => Declares timestamp field of type LocalDateTime
  // constructors, getters, setters
}
// => Block delimiter
 
// Repository
public interface AccountRepository extends JpaRepository<BankAccount, Long> {}
    // => Begins block
public interface TransferLogRepository extends JpaRepository<TransferLog, Long> {}
    // => Begins block
 
// Service with transactions
@Service
// => Annotation applied
public class TransferService {
    // => Begins block
  @Autowired private AccountRepository accountRepo;
  // => Injected repository for BankAccount CRUD operations
  @Autowired private TransferLogRepository logRepo;
  // => Injected repository for TransferLog audit trail
 
  @Transactional // Default: REQUIRED propagation, rollback on RuntimeException
  // => Annotation applied
  public void transfer(Long fromId, Long toId, BigDecimal amount) {
    // => Begins block
    BankAccount from = accountRepo.findById(fromId)
      // => Retrieves source account, throws IllegalArgumentException if not found
      .orElseThrow(() -> new IllegalArgumentException("Source not found"));
    // => Executes method
    BankAccount to = accountRepo.findById(toId)
      // => Retrieves destination account for credit operation
      .orElseThrow(() -> new IllegalArgumentException("Destination not found"));
    // => Executes method
 
    if (from.getBalance().compareTo(amount) < 0) {
    // => Executes method
      throw new IllegalStateException("Insufficient funds"); // => Rollback entire transaction
      // => Assigns > Rollback entire transaction to //
    }
    // => Block delimiter
 
    from.setBalance(from.getBalance().subtract(amount));
    // => Executes method
    // => Debits source account (new balance = old balance - amount)
    to.setBalance(to.getBalance().add(amount));
    // => Executes method
    // => Credits destination account (new balance = old balance + amount)
    accountRepo.save(from);
    // => Executes method
    // => Persists updated source account to database
    accountRepo.save(to);
    // => Executes method
    // => Persists updated destination account to database
 
    // Log the transfer
    TransferLog log = new TransferLog();
    // => Creates new instance
    log.setFromAccount(fromId);
    // => Executes method
    log.setToAccount(toId);
    // => Executes method
    log.setAmount(amount);
    // => Executes method
    log.setTimestamp(LocalDateTime.now());
    // => Executes method
    // => Records exact time of transfer for audit trail
    logRepo.save(log);
    // => Executes method
    // => Persists transfer log entry (all-or-nothing with account updates)
 
    // If exception occurs here, ALL changes (both accounts + log) rollback
  }
  // => Block delimiter
}
// => Block delimiter
 
// Controller
@RestController
// => Annotation applied
@RequestMapping("/api/transfers")
    // => Executes method
public class TransferController {
    // => Begins block
  @Autowired private TransferService transferService;
  // => Annotation applied
 
  @PostMapping
  // => Annotation applied
  public ResponseEntity<String> transfer(
    @RequestParam Long fromId,
    @RequestParam Long toId,
    @RequestParam BigDecimal amount
  ) {
    // => Begins block
    try {
    // => Begins block
      transferService.transfer(fromId, toId, amount);
    // => Executes method
      return ResponseEntity.ok("Transfer successful");
    // => Returns value to caller
    } catch (Exception e) {
    // => Executes method
      return ResponseEntity.badRequest().body(e.getMessage());
    // => Returns value to caller
    }
  }
}

// build.gradle.kts
dependencies {
// => Block begins
    implementation("org.springframework.boot:spring-boot-starter-data-jpa")
}
 
// Domain model using Kotlin data classes with JPA annotations
@Entity
// => JPA entity mapped to database table
@Table(name = "bank_accounts")
// => Specifies database table name
open class BankAccount(
// => Class declaration
    @Id
    // => Primary key field
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    // => Auto-generated primary key strategy
    var id: Long? = null,
    // => Mutable variable
 
    var owner: String = "",
    // => Mutable variable
 
    var balance: BigDecimal = BigDecimal.ZERO
    // => Mutable variable
    // BigDecimal for precise financial calculations (no floating-point errors)
) {
// => Block begins
    // Must be 'open' class for JPA lazy loading proxies
    // Default values provide no-arg constructor for JPA
}
 
@Entity
// => JPA entity mapped to database table
@Table(name = "transfer_logs")
// => Specifies database table name
open class TransferLog(
// => Class declaration
    @Id
    // => Primary key field
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    // => Auto-generated primary key strategy
    var id: Long? = null,
    // => Mutable variable
 
    var fromAccount: Long? = null,
    // => Mutable variable
    var toAccount: Long? = null,
    // => Mutable variable
    var amount: BigDecimal = BigDecimal.ZERO,
    // => Mutable variable
    var timestamp: LocalDateTime = LocalDateTime.now()
    // => Mutable variable
)
 
// Repository interfaces - Kotlin syntax
interface AccountRepository : JpaRepository<BankAccount, Long>
// => Interface definition
interface TransferLogRepository : JpaRepository<TransferLog, Long>
// => Interface definition
 
// Service with transactions using primary constructor injection
@Service
// => Business logic layer Spring component
class TransferService(
// => Class declaration
    private val accountRepo: AccountRepository,
    // => Private class member
    // => Constructor injection - no @Autowired needed in Kotlin
    private val logRepo: TransferLogRepository
    // => Private class member
    // => Both repositories injected automatically by Spring
) {
// => Block begins
 
    @Transactional // Default: REQUIRED propagation, rollback on RuntimeException
    // => Wraps method in database transaction
    fun transfer(fromId: Long, toId: Long, amount: BigDecimal) {
    // => Function declaration
        val from = accountRepo.findById(fromId)
        // => Immutable binding (read-only reference)
            // => Retrieves source account, throws if not found
            .orElseThrow { IllegalArgumentException("Source not found") }
        // Lambda syntax for exception supplier
 
        val to = accountRepo.findById(toId)
        // => Immutable binding (read-only reference)
            // => Retrieves destination account for credit operation
            .orElseThrow { IllegalArgumentException("Destination not found") }
 
        if (from.balance < amount) {
        // => Block begins
            // Kotlin operator overloading for BigDecimal comparison
            throw IllegalStateException("Insufficient funds")
            // => Exception thrown, method execution terminates
            // => Rollback entire transaction
        }
 
        from.balance = from.balance - amount
        // => Assignment
        // => Kotlin operator overloading: subtract() method
        // Debits source account (new balance = old balance - amount)
 
        to.balance = to.balance + amount
        // => Assignment
        // => Kotlin operator overloading: add() method
        // Credits destination account (new balance = old balance + amount)
 
        accountRepo.save(from)
        // => Persists updated source account to database
        accountRepo.save(to)
        // => Persists updated destination account to database
 
        // Log the transfer
        val log = TransferLog(
        // => Immutable binding (read-only reference)
            fromAccount = fromId,
            // => Assignment
            toAccount = toId,
            // => Assignment
            amount = amount,
            // => Assignment
            timestamp = LocalDateTime.now()
            // => Assignment
        )
        // => Named parameters make construction clearer
        // Records exact time of transfer for audit trail
 
        logRepo.save(log)
        // => Persists transfer log entry (all-or-nothing with account updates)
 
        // If exception occurs here, ALL changes (both accounts + log) rollback
    }
}
 
// Controller using primary constructor injection
@RestController
// => Combines @Controller and @ResponseBody
@RequestMapping("/api/transfers")
// => HTTP endpoint mapping
class TransferController(
// => Class declaration
    private val transferService: TransferService
    // => Private class member
) {
// => Block begins
 
    @PostMapping
    // => HTTP endpoint mapping
    fun transfer(
    // => Function declaration
        @RequestParam fromId: Long,
        // => Annotation applied
        @RequestParam toId: Long,
        // => Annotation applied
        @RequestParam amount: BigDecimal
        // => Annotation applied
    ): ResponseEntity<String> {
    // => Block begins
        return try {
        // => Returns value to caller
            transferService.transfer(fromId, toId, amount)
            ResponseEntity.ok("Transfer successful")
        } catch (e: Exception) {
        // => Block begins
            ResponseEntity.badRequest().body(e.message)
            // e.message is nullable in Kotlin, handled by Jackson
        }
    }
 
    // Alternative idiomatic Kotlin using runCatching:
    // fun transfer(...) = runCatching {
    //     transferService.transfer(fromId, toId, amount)
    //     ResponseEntity.ok("Transfer successful")
    // }.getOrElse {
    //     ResponseEntity.badRequest().body(it.message)
    // }
    // Result-based error handling, more functional
}

@Service
// => Annotation applied
public class InventoryService {
    // => Begins block
  @Autowired private ProductRepository productRepo;
  // => Annotation applied
 
  // READ_COMMITTED: Prevents dirty reads
  @Transactional(isolation = Isolation.READ_COMMITTED)
  // => Annotation applied
  public int getStock(Long productId) {
    // => Begins block
    Product p = productRepo.findById(productId).orElseThrow();
    // => Fetches product from database within transaction boundary
    return p.getStock(); // => Sees only committed data from other transactions
    // => Assigns > Sees only committed data from other transactions to //
  }
  // => Block delimiter
 
  // REPEATABLE_READ: Prevents non-repeatable reads
  @Transactional(isolation = Isolation.REPEATABLE_READ)
  // => Annotation applied
  public void processOrder(Long productId, int quantity) {
    // => Begins block
    Product p = productRepo.findById(productId).orElseThrow();
    // => Fetches product from database within transaction boundary
    int initialStock = p.getStock(); // => 100
    // => Captures initial stock value (locks this value for entire transaction)
 
    // Simulate delay
    Thread.sleep(1000);
    // => Executes method
 
    // Even if another transaction updates stock, this transaction still sees 100
    int currentStock = productRepo.findById(productId).get().getStock(); // => Still 100
    // => Result stored in currentStock
 
    if (currentStock >= quantity) {
    // => Executes method
      p.setStock(currentStock - quantity);
    // => Executes method
      productRepo.save(p);
    // => Executes method
    }
    // => Block delimiter
  }
 
  // SERIALIZABLE: Strictest isolation (rarely needed)
  @Transactional(isolation = Isolation.SERIALIZABLE)
  public void criticalOperation(Long productId) {
    // => Begins block
    // Locks prevent concurrent access—transactions execute serially
  }
}

@Service
class InventoryService(
    private val productRepo: ProductRepository
    // Constructor injection - no @Autowired needed
) {
 
    // READ_COMMITTED: Prevents dirty reads
    // Kotlin requires explicit Isolation import
    @Transactional(isolation = Isolation.READ_COMMITTED)
    fun getStock(productId: Long): Int {
        val p = productRepo.findById(productId).orElseThrow()
        // => Fetches product from database within transaction boundary
        return p.stock // => Sees only committed data from other transactions
        // Kotlin property access (no getStock() method call)
    }
 
    // REPEATABLE_READ: Prevents non-repeatable reads
    @Transactional(isolation = Isolation.REPEATABLE_READ)
    fun processOrder(productId: Long, quantity: Int) {
        val p = productRepo.findById(productId).orElseThrow()
        // => Fetches product from database within transaction boundary
        val initialStock = p.stock // => 100
        // => Captures initial stock value (locks this value for entire transaction)
 
        // Simulate delay
        Thread.sleep(1000)
        // Kotlin doesn't require try-catch for InterruptedException
        // Unless you specifically need to handle it
 
        // Even if another transaction updates stock, this transaction still sees 100
        val currentStock = productRepo.findById(productId).get().stock // => Still 100
        // REPEATABLE_READ ensures consistent read within transaction
 
        if (currentStock >= quantity) {
            p.stock = currentStock - quantity
            productRepo.save(p)
        }
    }
 
    // SERIALIZABLE: Strictest isolation (rarely needed)
    @Transactional(isolation = Isolation.SERIALIZABLE)
    fun criticalOperation(productId: Long) {
        // Locks prevent concurrent access—transactions execute serially
        // Use only when absolute consistency required (inventory allocation, payment processing)
    }
 
    // Kotlin-specific: Suspend function for coroutines
    // @Transactional works with suspend functions in Spring 6+
    // @Transactional
    // suspend fun processOrderAsync(productId: Long, quantity: Int) {
    //     val p = productRepo.findById(productId).orElseThrow()
    //     delay(1000) // Non-blocking delay in coroutine
    //     p.stock -= quantity
    //     productRepo.save(p)
    // }
    // Coroutines enable non-blocking transaction processing
}

@Entity
public class Product {
    // => Begins block
  @Id @GeneratedValue
  private Long id;
  // => Primary key auto-generated by database
  private String name;
  // => Product name (e.g., "Laptop", "Mouse")
  private int stock;
  // => Current inventory quantity
 
  @Version // Optimistic locking version field
  private Long version;
  // => JPA automatically increments this on every update
  // => Used in WHERE clause: UPDATE ... WHERE id=? AND version=?
  // => Throws OptimisticLockException if version changed since read
 
  // constructors, getters, setters
}
 
@Service
public class StockService {
    // => Begins block
  @Autowired private ProductRepository productRepo;
  // => Injected JPA repository for Product CRUD operations
 
  @Transactional
  public void decreaseStock(Long productId, int quantity) {
    // => Begins block
    Product product = productRepo.findById(productId).orElseThrow();
    // => Fetches product with current version (e.g., version=1)
    // => Throws exception if product not found
 
    product.setStock(product.getStock() - quantity);
    // => Executes method
    // => Decreases stock: new stock = old stock - quantity
    // => Example: 100 - 5 = 95 (not yet persisted)
    productRepo.save(product);
    // => Executes method
    // => SQL: UPDATE product SET stock=95, version=2 WHERE id=? AND version=1
    // => If version still 1 → success, version becomes 2
    // => If version changed to 2 by another transaction → OptimisticLockException
    // => Prevents lost updates in concurrent modifications
 
    // If another transaction updated product (version=2), this fails with OptimisticLockException
  }
 
  // Retry logic for conflicts
  @Transactional
  public void decreaseStockWithRetry(Long productId, int quantity) {
    // => Begins block
    int maxRetries = 3;
    // => Assigns value to variable
    // => Allow up to 3 attempts to handle concurrent updates gracefully
    for (int i = 0; i < maxRetries; i++) {
    // => Executes method
      // => Attempt counter: i=0, i=1, i=2
      try {
    // => Begins block
        Product product = productRepo.findById(productId).orElseThrow();
        // => Fetches latest version from database
        product.setStock(product.getStock() - quantity);
    // => Executes method
        // => Calculates new stock quantity
        productRepo.save(product);
    // => Executes method
        // => Attempts save with version check
        return; // Success
        // => Exit method if save succeeds (no exception thrown)
      } catch (OptimisticLockException e) {
    // => Executes method
        // => Another transaction modified product since we read it
        if (i == maxRetries - 1) throw e; // Retries exhausted
    // => Executes method
        // => On final retry (i=2), re-throw exception to caller
        // Retry with fresh data
        // => Loop continues, fetches updated version, tries again
      }
    }
  }
}

@Entity
// => JPA entity - maps to database table
// => JPA entity mapped to database table
@Table(name = "products")
// => Specifies database table name
// => Specifies database table name
open class Product(
// => Class declaration
// => Class declaration
    @Id
    // => JPA primary key field
    // => Primary key field
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    // => Auto-generate primary key value
    // => Auto-generated primary key strategy
    var id: Long? = null,
    // => Mutable property
    // => Mutable variable
 
    var name: String = "",
    // => Mutable property
    // => Mutable variable
    var stock: Int = 0,
    // => Mutable property
    // => Mutable variable
 
    @Version // Optimistic locking version field
    // => Annotation applied
    // => Annotation applied
    var version: Long? = null
    // => Mutable property
    // => Mutable variable
    // => JPA automatically increments on each update
    // Null initially, set by JPA after first persist
) {
// => Block begins
    // Must be 'open' for JPA proxies
}
 
@Service
// => Business logic service bean
// => Business logic layer Spring component
class StockService(
// => Class declaration
// => Class declaration
    private val productRepo: ProductRepository
    // => Immutable property
    // => Private class member
) {
// => Block begins
 
    @Transactional
    // => Wrap in database transaction
    // => Wraps method in database transaction
    fun decreaseStock(productId: Long, quantity: Int) {
    // => Function definition
    // => Function declaration
        val product = productRepo.findById(productId).orElseThrow()
        // => Immutable property
        // => Immutable binding (read-only reference)
        // version = 1 (current version from database)
 
        product.stock -= quantity
        // => Assignment
        // => Assignment
        // Kotlin operator overloading for subtraction
        productRepo.save(product)
        // SQL: UPDATE product SET stock=?, version=2 WHERE id=? AND version=1
        // => Version automatically incremented to 2
 
        // If another transaction updated product (version=2), this fails with OptimisticLockException
        // Exception rollbacks current transaction
    }
 
    // Retry logic for conflicts using Kotlin repeat
    @Transactional
    // => Wrap in database transaction
    // => Wraps method in database transaction
    fun decreaseStockWithRetry(productId: Long, quantity: Int) {
    // => Function definition
    // => Function declaration
        val maxRetries = 3
        // => Immutable property
        // => Immutable binding (read-only reference)
        repeat(maxRetries) { attempt ->
            try {
            // => Exception handling begins
                val product = productRepo.findById(productId).orElseThrow()
                // => Immutable property
                // => Immutable binding (read-only reference)
                product.stock -= quantity
                // => Assignment
                // => Assignment
                productRepo.save(product)
                return // Success - exit function
                // => Returns to caller
                // => Returns value to caller
            } catch (e: OptimisticLockException) {
            // => Block begins
                if (attempt == maxRetries - 1) throw e // Retries exhausted
                // => Assignment
                // Retry with fresh data (next iteration)
            }
        }
    }
 
    // Alternative using Kotlin retry utility (more functional)
    @Transactional
    // => Wrap in database transaction
    // => Wraps method in database transaction
    fun decreaseStockFunctional(productId: Long, quantity: Int) {
    // => Function definition
    // => Function declaration
        var lastException: OptimisticLockException? = null
        // => Mutable property
        // => Mutable variable
 
        repeat(3) {
        // => Block begins
            try {
            // => Exception handling begins
                val product = productRepo.findById(productId).orElseThrow()
                // => Immutable property
                // => Immutable binding (read-only reference)
                product.stock -= quantity
                // => Assignment
                // => Assignment
                productRepo.save(product)
                return // Success
                // => Returns to caller
                // => Returns value to caller
            } catch (e: OptimisticLockException) {
            // => Block begins
                lastException = e
                // => Assignment
                // => Assignment
            }
        }
 
        throw lastException!! // All retries failed
        // => Throws exception
        // => Exception thrown, method execution terminates
    }
}

// application.properties
spring.jpa.properties.hibernate.jdbc.batch_size=50
// => Groups SQL statements into batches of 50 (reduces network roundtrips)
spring.jpa.properties.hibernate.order_inserts=true
// => Groups INSERTs by entity type for efficient batching
spring.jpa.properties.hibernate.order_updates=true
// => Groups UPDATEs by entity type for efficient batching
 
@Service
public class BulkImportService {
    // => Begins block
  @Autowired private ProductRepository productRepo;
  // => Injected JPA repository for Product operations
  @Autowired private EntityManager entityManager;
  // => Direct JPA EntityManager for manual flush/clear control
 
  // Inefficient: N+1 queries
  @Transactional
  public void importProductsSlow(List<Product> products) {
    // => Begins block
    // => Example: 1000 products
    for (Product p : products) {
    // => Executes method
      productRepo.save(p); // => 1000 products = 1000 INSERT statements
      // => Each save triggers immediate database roundtrip
      // => Total: 1000 network calls (very slow)
    }
    // => Performance: ~10 seconds for 1000 products
  }
 
  // Better: Batch inserts
  @Transactional
  public void importProductsFast(List<Product> products) {
    // => Begins block
    productRepo.saveAll(products); // => Batches 1000 products into 20 INSERTs (50 per batch)
    // => Hibernate groups inserts: batch_size=50
    // => Total: 20 network calls instead of 1000
    // => Performance: ~2 seconds for 1000 products (5x faster)
  }
 
  // Best: Manual batch flushing for large datasets
  @Transactional
  public void importProductsOptimal(List<Product> products) {
    // => Begins block
    int batchSize = 50;
    // => Assigns value to variable
    // => Process 50 entities at a time
    for (int i = 0; i < products.size(); i++) {
    // => Executes method
      // => Iterate through all products
      entityManager.persist(products.get(i));
    // => Executes method
      // => Queues entity for insert (not yet executed)
      if (i % batchSize == 0 && i > 0) {
    // => Executes method
        // => Every 50 products: i=50, i=100, i=150...
        entityManager.flush(); // Force batch execution
    // => Executes method
        // => Executes accumulated INSERTs: INSERT INTO product VALUES (...), (...), ...
        entityManager.clear(); // Free memory
    // => Executes method
        // => Detaches entities from persistence context (prevents OutOfMemoryError)
        // => Crucial for processing 100,000+ entities
      }
    }
    // => Final flush happens automatically at transaction commit
    // => Performance: ~1.5 seconds for 1000 products (memory-efficient)
  }
 
  // Bulk update with JPQL
  @Transactional
  public void discountAllProducts(BigDecimal discountPercent) {
    // => Begins block
    // => Example: discountPercent = 0.10 (10% discount)
    int updated = entityManager.createQuery(
    // => Assigns value to variable
      "UPDATE Product p SET p.price = p.price * :factor"
      // => JPQL query: updates ALL products in single SQL statement
    ).setParameter("factor", BigDecimal.ONE.subtract(discountPercent))
      // => factor = 1.0 - 0.10 = 0.90 (multiply price by 0.90 for 10% off)
     .executeUpdate(); // => Single UPDATE statement for all rows
     // => SQL: UPDATE product SET price = price * 0.90
     // => Updates 10,000 products in ~100ms (vs 10 seconds with individual saves)
     // => Returns number of updated rows
 
    System.out.println("Updated " + updated + " products");
    // => Output: Updated 10000 products
  }
}

# application.properties - same for Kotlin
spring.jpa.properties.hibernate.jdbc.batch_size=50
spring.jpa.properties.hibernate.order_inserts=true
spring.jpa.properties.hibernate.order_updates=true

@Service
// => Business logic service bean
// => Business logic layer Spring component
class ProductImportService(
// => Class declaration
// => Class declaration
    private val productRepo: ProductRepository,
    // => Immutable property
    // => Private class member
    private val entityManager: EntityManager
    // => Immutable property
    // => Private class member
    // EntityManager injection for manual flush/clear
) {
// => Block begins
 
    @Transactional
    // => Wrap in database transaction
    // => Wraps method in database transaction
    fun importProducts(csvFile: String) {
    // => Function definition
    // => Function declaration
        val products = parseCsv(csvFile)
        // => Immutable property
        // => Immutable binding (read-only reference)
        // => Returns List<Product> from CSV parsing
 
        // Small batch: Use saveAll() - simple and effective
        productRepo.saveAll(products)
        // => Hibernate batches inserts based on batch_size property (50)
        // Executes: INSERT INTO product ... (50 values per batch)
    }
 
    @Transactional
    // => Wrap in database transaction
    // => Wraps method in database transaction
    fun importLargeDataset(csvFile: String) {
    // => Function definition
    // => Function declaration
        val products = parseCsv(csvFile)
        // => Immutable property
        // => Immutable binding (read-only reference)
        // => Could be 100,000+ products
 
        products.chunked(50).forEach { batch ->
            // Kotlin chunked() splits list into batches of 50
            productRepo.saveAll(batch)
            // => Saves batch of 50 products
 
            entityManager.flush()
            // => Forces Hibernate to execute SQL immediately
            entityManager.clear()
            // => Clears persistence context (prevents memory leak)
            // Critical for large datasets - releases processed entities from memory
        }
 
        println("Imported ${products.size} products")
        // => Output: see string template value above
        // String template instead of concatenation
    }
 
    @Transactional
    // => Wrap in database transaction
    // => Wraps method in database transaction
    fun bulkPriceUpdate(category: String, discount: Double) {
    // => Function definition
    // => Function declaration
        // JPQL bulk update - most efficient for mass updates
        val updated = entityManager.createQuery(
        // => Immutable property
        // => Immutable binding (read-only reference)
            "UPDATE Product p SET p.price = p.price * :discount WHERE p.category = :category"
            // => Assignment
            // => Assignment
        )
            .setParameter("discount", discount)
            .setParameter("category", category)
            .executeUpdate()
        // => Executes single SQL: UPDATE product SET price = price * ? WHERE category = ?
        // Updates all matching rows without loading entities into memory
 
        println("Updated $updated products")
        // => Output: see string template value above
        // String template for logging
    }
 
    private fun parseCsv(file: String): List<Product> {
    // => Function definition
    // => Function declaration
        // CSV parsing implementation
        return emptyList() // Placeholder
        // => Returns to caller
        // => Returns value to caller
    }
}
 
// Alternative using Kotlin sequence for streaming large files
@Service
// => Business logic service bean
// => Business logic layer Spring component
class StreamingImportService(
// => Class declaration
// => Class declaration
    private val productRepo: ProductRepository,
    // => Immutable property
    // => Private class member
    private val entityManager: EntityManager
    // => Immutable property
    // => Private class member
) {
// => Block begins
 
    @Transactional
    // => Wrap in database transaction
    // => Wraps method in database transaction
    fun importProductsStreaming(csvFile: String) {
    // => Function definition
    // => Function declaration
        File(csvFile).useLines { lines ->
            // useLines automatically closes file - Kotlin resource management
            lines
                .drop(1) // Skip header row
                .chunked(50) // Process in batches of 50
                .forEach { batch ->
                    val products = batch.map { parseLine(it) }
                    // => Immutable property
                    // => Immutable binding (read-only reference)
                    productRepo.saveAll(products)
                    entityManager.flush()
                    entityManager.clear()
                }
        }
        // File automatically closed after useLines block
        // Memory efficient - processes file line by line
    }
 
    private fun parseLine(line: String): Product {
    // => Function definition
    // => Function declaration
        // Parse single CSV line to Product
        return Product() // Placeholder
        // => Returns to caller
        // => Returns value to caller
    }
}

// pom.xml
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-security</artifactId>
  // => Adding this dependency triggers Spring Security auto-configuration
  // => No additional code needed for basic authentication
</dependency>
 
// With just the dependency, Spring Boot:
// 1. Generates random password on startup (console log)
//    => Password changes every restart (check console output)
// 2. Secures all endpoints with HTTP Basic Auth
//    => Requires username + password in Authorization header
// 3. Default username: "user"
//    => Configurable via spring.security.user.name property
// 4. CSRF protection enabled
//    => Prevents cross-site request forgery attacks
// 5. Session management configured
//    => HTTP sessions created for authenticated users
 
@RestController
public class SecuredController {
    // => Begins block
  @GetMapping("/public")
    // => Executes method
  public String publicEndpoint() {
    // => Begins block
    return "Accessible without auth"; // => Still requires login by default!
    // => Spring Security secures ALL endpoints unless explicitly permitted
    // => Returns 401 Unauthorized if no credentials provided
  }
 
  @GetMapping("/api/data")
    // => Executes method
  public String securedEndpoint() {
    // => Begins block
    return "Protected data"; // => Requires authentication
    // => HTTP Basic authentication required
    // => Returns data only if valid username/password provided
  }
}
 
// Run the app and see console:
// Using generated security password: a1b2c3d4-e5f6-7890-abcd-ef1234567890
// => Copy this password from console output (changes every restart)
 
// curl http://localhost:8080/api/data => 401 Unauthorized
// => No credentials provided → request rejected
 
// curl -u user:a1b2c3d4-e5f6-7890-abcd-ef1234567890 http://localhost:8080/api/data => "Protected data"
// => -u flag provides username:password
// => Authorization header: Basic dXNlcjphMWIyYzNkNC4uLg== (base64 encoded)
// => Authentication succeeds → data returned

// build.gradle.kts
dependencies {
// => Block begins
    implementation("org.springframework.boot:spring-boot-starter-security")
}
 
// With just the dependency, Spring Boot:
// 1. Generates random password on startup (console log)
// 2. Secures all endpoints with HTTP Basic Auth
// 3. Default username: "user"
// 4. CSRF protection enabled
// 5. Session management configured
 
@RestController
// => Combines @Controller and @ResponseBody
class SecuredController {
// => Class declaration
 
    @GetMapping("/public")
    // => HTTP endpoint mapping
    fun publicEndpoint(): String {
    // => Function declaration
        return "Accessible without auth" // => Still requires login by default!
        // Spring Security secures ALL endpoints unless explicitly permitted
    }
 
    @GetMapping("/api/data")
    // => HTTP endpoint mapping
    fun securedEndpoint(): String {
    // => Function declaration
        return "Protected data" // => Requires authentication
        // Returns data only if authenticated via HTTP Basic
    }
}
 
// Run the app and see console:
// Using generated security password: a1b2c3d4-e5f6-7890-abcd-ef1234567890
// curl http://localhost:8080/api/data => 401 Unauthorized
// curl -u user:a1b2c3d4-e5f6-7890-abcd-ef1234567890 http://localhost:8080/api/data => "Protected data"
 
// Kotlin tip: Access authenticated user in controller
@RestController
// => Combines @Controller and @ResponseBody
class AuthenticatedController {
// => Class declaration
 
    @GetMapping("/me")
    // => HTTP endpoint mapping
    fun currentUser(@AuthenticationPrincipal user: UserDetails): String {
    // => Function declaration
        // @AuthenticationPrincipal injects authenticated user
        return "Hello, ${user.username}"
        // => Returns value to caller
        // String template for user greeting
    }
 
    // Alternative using SecurityContextHolder (less idiomatic)
    @GetMapping("/me-manual")
    // => HTTP endpoint mapping
    fun currentUserManual(): String {
    // => Function declaration
        val auth = SecurityContextHolder.getContext().authentication
        // => Immutable binding (read-only reference)
        return "Hello, ${auth.name}"
        // => Returns value to caller
    }
}

@Configuration
// => Configuration class - contains @Bean methods
// => Spring configuration class - defines bean factory methods
// => Annotation applied
@EnableWebSecurity
// => Enables Spring Security configuration
// => Enables Spring Security web/method security
// => Annotation applied
public class SecurityConfig {
// => Class declaration
// => Class definition begins
    // => Begins block
 
  @Bean
  // => Defines a Spring-managed bean
  // => Declares a Spring-managed bean
  // => Annotation applied
  public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
  // => Method definition
  // => Method definition
    // => Begins block
    http // => Configure HTTP security chain
      .authorizeHttpRequests(auth -> auth // => Define authorization rules
        .requestMatchers("/public/**").permitAll() // => Public endpoints (no auth required)
        .requestMatchers("/admin/**").hasRole("ADMIN") // => Admin endpoints (requires ADMIN role)
        .anyRequest().authenticated() // => All other endpoints require authentication
        // => Executes method call
      )
      .formLogin(form -> form // => Configure form-based login
        .loginPage("/login") // => Custom login page URL
        // => Executes method call
        .permitAll()
    // => Executes method
      )
      .logout(logout -> logout.permitAll()); // => Enable logout endpoint
      // => Assigns > Enable logout endpoint to //
 
    return http.build(); // => Build SecurityFilterChain bean
    // => Assigns > Build SecurityFilterChain bean to //
  }
  // => Block delimiter
 
  @Bean
  // => Defines a Spring-managed bean
  // => Declares a Spring-managed bean
  // => Annotation applied
  public UserDetailsService userDetailsService() {
  // => Method definition
  // => Method definition
    // => Begins block
    // => In-memory users (for demo—use database/LDAP in production)
    UserDetails user = User.builder() // => Create user with builder pattern
      .username("user") // => Username for authentication
      .password(passwordEncoder().encode("password123")) // => BCrypt-hashed password
      .roles("USER") // => Granted authority: ROLE_USER
      .build(); // => Immutable UserDetails object
      // => Assigns > Immutable UserDetails object to //
 
    UserDetails admin = User.builder() // => Create admin user
      .username("admin") // => Admin username
      .password(passwordEncoder().encode("admin123")) // => BCrypt-hashed admin password
      .roles("ADMIN", "USER") // => Multiple roles: ROLE_ADMIN + ROLE_USER
      .build(); // => Admin has both USER and ADMIN privileges
      // => Assigns > Admin has both USER and ADMIN privileges to //
 
    return new InMemoryUserDetailsManager(user, admin); // => Store users in memory (non-persistent)
    // => Assigns > Store users in memory (non-persistent) to //
  }
 
  @Bean
  // => Defines a Spring-managed bean
  // => Declares a Spring-managed bean
  public PasswordEncoder passwordEncoder() {
  // => Method definition
  // => Method definition
    // => Begins block
    return new BCryptPasswordEncoder(); // => BCrypt with automatic salt generation (industry standard)
    // => Assigns > BCrypt with automatic salt generation (industry standard) to //
  }
}
 
// Controller
@RestController
// => REST controller - returns JSON directly
// => REST controller - combines @Controller + @ResponseBody
public class ApiController {
// => Class declaration
// => Class definition begins
    // => Begins block
  @GetMapping("/public/hello")
  // => HTTP GET endpoint
  // => HTTP endpoint mapping
    // => Executes method
  public String publicHello() {
  // => Method definition
  // => Method definition
    // => Begins block
    return "Public endpoint"; // => Accessible without login
    // => Assigns > Accessible without login to //
  }
 
  @GetMapping("/api/user-data")
  // => HTTP GET endpoint
  // => HTTP endpoint mapping
    // => Executes method
  public String userData() {
  // => Method definition
  // => Method definition
    // => Begins block
    return "User data"; // => Requires USER or ADMIN role
    // => Assigns > Requires USER or ADMIN role to //
  }
 
  @GetMapping("/admin/dashboard")
  // => HTTP GET endpoint
  // => HTTP endpoint mapping
    // => Executes method
  public String adminDashboard() {
  // => Method definition
  // => Method definition
    // => Begins block
    return "Admin dashboard"; // => Requires ADMIN role only
    // => Assigns > Requires ADMIN role only to //
  }
}

@Configuration
// => Configuration class - contains @Bean methods
// => Marks class as Spring configuration (bean factory)
@EnableWebSecurity
// => Enables Spring Security configuration
// => Annotation applied
open class SecurityConfig {
// => Class declaration
// => Class declaration
 
    @Bean
    // => Defines a Spring-managed bean
    // => Declares a Spring-managed bean
    open fun filterChain(http: HttpSecurity): SecurityFilterChain {
    // => Function definition
    // => Function declaration
        // Kotlin DSL for Spring Security configuration
        http {
        // => Block begins
            // Lambda-based configuration (Kotlin DSL)
            authorizeHttpRequests {
            // => Block begins
                authorize("/public/**", permitAll) // => Public endpoints (no auth required)
                authorize("/admin/**", hasRole("ADMIN")) // => Admin endpoints (requires ADMIN role)
                authorize(anyRequest, authenticated) // => All other endpoints require authentication
            }
            formLogin {
            // => Block begins
                loginPage = "/login" // => Custom login page URL
                permitAll()
            }
            logout {
            // => Block begins
                permitAll()
            }
        }
        return http.build() // => Build SecurityFilterChain bean
    }
 
    @Bean
    // => Defines a Spring-managed bean
    // => Declares a Spring-managed bean
    open fun userDetailsService(): UserDetailsService {
    // => Function definition
    // => Function declaration
        // In-memory users (for demo—use database/LDAP in production)
        val user = User.builder() // => Create user with builder pattern
            .username("user") // => Username for authentication
            .password(passwordEncoder().encode("password123")) // => BCrypt-hashed password
            .roles("USER") // => Granted authority: ROLE_USER
            .build() // => Immutable UserDetails object
 
        val admin = User.builder() // => Create admin user
            .username("admin") // => Admin username
            .password(passwordEncoder().encode("admin123")) // => BCrypt-hashed admin password
            .roles("ADMIN", "USER") // => Multiple roles: ROLE_ADMIN + ROLE_USER
            .build() // => Admin has both USER and ADMIN privileges
 
        return InMemoryUserDetailsManager(user, admin)
        // => Returns to caller
        // => Returns value to caller
        // => Store users in memory (non-persistent)
        // Kotlin allows direct constructor call without 'new'
    }
 
    @Bean
    // => Defines a Spring-managed bean
    // => Declares a Spring-managed bean
    open fun passwordEncoder(): PasswordEncoder {
    // => Function definition
    // => Function declaration
        return BCryptPasswordEncoder()
        // => Returns to caller
        // => Returns value to caller
        // => BCrypt with automatic salt generation (industry standard)
    }
}
 
// Controller using Kotlin
@RestController
// => REST controller - returns JSON directly
// => Combines @Controller and @ResponseBody
class ApiController {
// => Class declaration
// => Class declaration
 
    @GetMapping("/public/hello")
    // => HTTP GET endpoint
    // => HTTP endpoint mapping
    fun publicHello() = "Public endpoint"
    // => Function definition
    // => Function declaration
    // Expression body - concise for simple returns
    // => Accessible without login
 
    @GetMapping("/api/user-data")
    // => HTTP GET endpoint
    // => HTTP endpoint mapping
    fun userData() = "User data"
    // => Function definition
    // => Function declaration
    // => Requires USER or ADMIN role
 
    @GetMapping("/admin/dashboard")
    // => HTTP GET endpoint
    // => HTTP endpoint mapping
    fun adminDashboard() = "Admin dashboard"
    // => Function definition
    // => Function declaration
    // => Requires ADMIN role only
 
    // Access authenticated user details
    @GetMapping("/api/profile")
    // => HTTP GET endpoint
    // => HTTP endpoint mapping
    fun userProfile(@AuthenticationPrincipal user: UserDetails): Map<String, Any> {
    // => Function definition
    // => Function declaration
        return mapOf(
        // => Returns to caller
        // => Returns value to caller
            "username" to user.username,
            // => Statement
            "authorities" to user.authorities.map { it.authority }
        )
        // => Returns {"username":"user","authorities":["ROLE_USER"]}
        // mapOf creates immutable map, to is infix function for Pair
    }
}

@Configuration
// => Spring configuration class - defines bean factory methods
// => Annotation applied
@EnableMethodSecurity // Enable method security annotations
// => Enables Spring Security web/method security
// => Annotation applied
public class MethodSecurityConfig {}
// => Class definition begins
    // => Begins block
 
@Service
// => Business logic layer Spring component
// => Annotation applied
public class OrderService {
// => Class definition begins
    // => Begins block
  @Autowired private OrderRepository orderRepo;
  // => Spring injects dependency automatically
  // => Annotation applied
 
  @PreAuthorize("hasRole('USER')") // => Check role BEFORE method execution
  public List<Order> getMyOrders(String username) { // => username parameter from authenticated user
    return orderRepo.findByUsername(username); // => Query orders filtered by username
    // => Assigns > Query orders filtered by username to //
  }
  // => Block delimiter
 
  @PreAuthorize("hasRole('ADMIN')") // => ADMIN role required (throws AccessDeniedException if missing)
  public List<Order> getAllOrders() { // => Admin-only endpoint
    return orderRepo.findAll(); // => Returns ALL orders (no filtering)
    // => Assigns > Returns ALL orders (no filtering) to //
  }
  // => Block delimiter
 
  @PreAuthorize("#username == authentication.name") // => SpEL expression: method param matches authenticated username
  // => Annotation applied
  public Order getOrder(String username, Long orderId) {
  // => Method definition
    // => Begins block
    return orderRepo.findByIdAndUsername(orderId, username) // => Query with composite key
      .orElseThrow(() -> new AccessDeniedException("Not authorized")); // => Explicit access denial
      // => Assigns > Explicit access denial to //
  }
  // => Block delimiter
 
  @PreAuthorize("hasRole('ADMIN') or #order.username == authentication.name") // => Admin OR resource owner can update
  // => Annotation applied
  public Order updateOrder(Order order) {
  // => Method definition
    // => Begins block
    return orderRepo.save(order); // => Persist updated order (authorization already checked)
    // => Assigns > Persist updated order (authorization already checked) to //
  }
 
  @PostAuthorize("returnObject.username == authentication.name") // => Check AFTER execution (compare returned order's owner)
  public Order loadOrder(Long orderId) {
  // => Method definition
    // => Begins block
    return orderRepo.findById(orderId).orElseThrow(); // => Fetch order first
    // => THEN Spring verifies returnObject.username matches authentication.name
  }
}
 
// Controller
@RestController
// => REST controller - combines @Controller + @ResponseBody
@RequestMapping("/api/orders")
// => Annotation applied
    // => Executes method
public class OrderController {
// => Class definition begins
    // => Begins block
  @Autowired private OrderService orderService;
  // => Spring injects dependency automatically
 
  @GetMapping("/my-orders") // => Endpoint: GET /api/orders/my-orders
  public List<Order> getMyOrders(@AuthenticationPrincipal UserDetails user) { // => Inject authenticated user
    return orderService.getMyOrders(user.getUsername()); // => Pass authenticated username to service layer
    // => Assigns > Pass authenticated username to service layer to //
  }
 
  @GetMapping("/all")
  // => HTTP endpoint mapping
    // => Executes method
  public List<Order> getAllOrders() {
  // => Method definition
    // => Begins block
    return orderService.getAllOrders(); // => Service method checks @PreAuthorize("hasRole('ADMIN')")
    // => Sets // to string literal
  }
}

@Configuration
// => Marks class as Spring configuration (bean factory)
@EnableMethodSecurity // Enable method security annotations in Kotlin
// => Annotation applied
open class MethodSecurityConfig
// => Class declaration
 
@Service
// => Business logic layer Spring component
class OrderService(
// => Class declaration
    private val orderRepo: OrderRepository
    // => Private class member
) {
// => Block begins
 
    @PreAuthorize("hasRole('USER')") // => Check role BEFORE method execution
    fun getMyOrders(username: String): List<Order> {
    // => Function declaration
        // username parameter from authenticated user
        return orderRepo.findByUsername(username)
        // => Returns value to caller
        // => Query orders filtered by username
    }
 
    @PreAuthorize("hasRole('ADMIN')")
    // => Annotation applied
    // => ADMIN role required (throws AccessDeniedException if missing)
    fun getAllOrders(): List<Order> {
    // => Function declaration
        return orderRepo.findAll() // => Returns ALL orders (no filtering)
    }
 
    @PreAuthorize("#username == authentication.name")
    // => Annotation applied
    // => SpEL expression: method param matches authenticated username
    // #username refers to method parameter, authentication is Spring Security context
    fun getOrder(username: String, orderId: Long): Order {
    // => Function declaration
        return orderRepo.findByIdAndUsername(orderId, username)
        // => Returns value to caller
            .orElseThrow { AccessDeniedException("Not authorized") }
        // => Kotlin lambda for exception supplier
    }
 
    @PreAuthorize("hasRole('ADMIN') or #order.username == authentication.name")
    // => Annotation applied
    // => Admin OR resource owner can update
    // SpEL expression with 'or' operator and property access
    fun updateOrder(order: Order): Order {
    // => Function declaration
        return orderRepo.save(order)
        // => Returns value to caller
        // => Persist updated order (authorization already checked)
    }
 
    @PostAuthorize("returnObject.username == authentication.name")
    // => Annotation applied
    // => Check AFTER execution (compare returned order's owner)
    // returnObject is SpEL variable for method return value
    fun loadOrder(orderId: Long): Order {
    // => Function declaration
        return orderRepo.findById(orderId).orElseThrow()
        // => Returns value to caller
        // => Fetch order first
        // => THEN Spring verifies returnObject.username matches authentication.name
    }
}
 
// Controller using Kotlin
@RestController
// => Combines @Controller and @ResponseBody
@RequestMapping("/api/orders")
// => HTTP endpoint mapping
class OrderController(
// => Class declaration
    private val orderService: OrderService
    // => Private class member
) {
// => Block begins
 
    @GetMapping("/my-orders")
    // => HTTP endpoint mapping
    // => Endpoint: GET /api/orders/my-orders
    fun getMyOrders(@AuthenticationPrincipal user: UserDetails): List<Order> {
    // => Function declaration
        // => Inject authenticated user details
        return orderService.getMyOrders(user.username)
        // => Returns value to caller
        // => Pass authenticated username to service layer
        // Kotlin property access (no getUsername() call)
    }
 
    @GetMapping("/all")
    // => HTTP endpoint mapping
    fun getAllOrders(): List<Order> {
    // => Function declaration
        return orderService.getAllOrders()
        // => Returns value to caller
        // => Service method checks @PreAuthorize("hasRole('ADMIN')")
    }
 
    // Kotlin-specific: Extension function for SpEL expressions
    @GetMapping("/{id}")
    // => HTTP endpoint mapping
    fun getOrder(
    // => Function declaration
        @PathVariable id: Long,
        // => Annotation applied
        @AuthenticationPrincipal user: UserDetails
        // => Annotation applied
    ): Order {
    // => Block begins
        return orderService.getOrder(user.username, id)
        // => Returns value to caller
        // Method-level security validates access
    }
}

// pom.xml
<dependency>
// => Executes
// => Code line
// => Code line
  <groupId>io.jsonwebtoken</groupId>
  // => Code line
  // => Code line
  <artifactId>jjwt-api</artifactId>
  // => Code line
  // => Code line
  <version>0.12.3</version>
  // => Code line
  // => Code line
</dependency>
// => Code line
// => Code line
<dependency>
// => Code line
// => Code line
  <groupId>io.jsonwebtoken</groupId>
  // => Code line
  // => Code line
  <artifactId>jjwt-impl</artifactId>
  // => Code line
  // => Code line
  <version>0.12.3</version>
  // => Code line
  // => Code line
</dependency>
// => Code line
// => Code line
 
// JWT utility class
@Component
// => @Component annotation applied
// => Spring component - detected by component scan
// => Spring-managed component
// => Annotation applied
public class JwtUtil {
// => Class definition begins
// => Class declaration
// => Class definition begins
    // => Begins block
  private String secret = "mySecretKey1234567890123456789012"; // 256-bit key
  // => Assigns value
  // => Private field
    // => Assigns value to variable
  private long expiration = 86400000; // 24 hours
  // => Assigns value
  // => Private field
  // => Sets expiration to 86400000
 
  public String generateToken(String username) { // => Create JWT token for authenticated user
    return Jwts.builder() // => Start JWT builder
      .subject(username) // => Set "sub" claim (token owner)
      .issuedAt(new Date()) // => Set "iat" claim (issued at timestamp)
      .expiration(new Date(System.currentTimeMillis() + expiration)) // => Set "exp" claim (24h from now)
      .signWith(Keys.hmacShaKeyFor(secret.getBytes())) // => Sign with HS256 algorithm
      .compact(); // => Serialize to Base64-encoded string
    // => Result format: header.payload.signature (JWT standard)
  }
  // => Block delimiter
 
  public String extractUsername(String token) { // => Parse JWT and extract username
    return Jwts.parser() // => Create JWT parser
      .verifyWith(Keys.hmacShaKeyFor(secret.getBytes())) // => Verify signature with same secret key
      .build() // => Build parser instance
      .parseSignedClaims(token) // => Parse and validate JWT (throws if invalid/expired)
      .getPayload() // => Extract claims (payload section)
      .getSubject(); // => Get "sub" claim (username)
      // => Sets // to string literal
  }
  // => Block delimiter
 
  public boolean isTokenValid(String token, String username) { // => Comprehensive token validation
  // => Executes method call
    try {
    // => Code line
    // => Block begins
    // => Begins block
      String extractedUser = extractUsername(token); // => Parse token (throws if tampered/invalid)
      return extractedUser.equals(username) && !isTokenExpired(token); // => Check username match + expiration
    } catch (Exception e) { // => Catch signature verification failures, malformed tokens
      return false; // => Invalid token
      // => Assigns > Invalid token to //
    }
    // => Block delimiter
  }
  // => Block delimiter
 
  private boolean isTokenExpired(String token) { // => Check if token has expired
    Date expiration = Jwts.parser() // => Create parser
      .verifyWith(Keys.hmacShaKeyFor(secret.getBytes())) // => Verify signature
      .build() // => Build parser
      .parseSignedClaims(token) // => Parse JWT
      .getPayload() // => Extract claims
      .getExpiration(); // => Get "exp" claim (expiration timestamp)
    return expiration.before(new Date()); // => Compare exp with current time
    // => Assigns > Compare exp with current time to //
  }
  // => Block delimiter
}
// => Block delimiter
 
// JWT authentication filter
@Component
// => Spring component - detected by component scan
// => Spring-managed component
// => Annotation applied
public class JwtAuthFilter extends OncePerRequestFilter {
// => Class declaration
// => Class definition begins
    // => Begins block
  @Autowired private JwtUtil jwtUtil; // => Inject JWT utility for token operations
  @Autowired private UserDetailsService userDetailsService; // => Inject user details service
  // => Annotation applied
 
  @Override
  // => Overrides parent method
  // => Overrides inherited method from parent class/interface
  // => Annotation applied
  protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain chain)
    // => Executes method
    throws ServletException, IOException {
    // => Block begins
    // => Begins block
 
    String header = request.getHeader("Authorization"); // => Extract Authorization header
    if (header != null && header.startsWith("Bearer ")) { // => Check for Bearer token format
      String token = header.substring(7); // => Remove "Bearer " prefix (7 chars)
      String username = jwtUtil.extractUsername(token); // => Parse JWT to extract username
      // => Result stored in username
 
      if (username != null && SecurityContextHolder.getContext().getAuthentication() == null) { // => Valid username + not already authenticated
        UserDetails user = userDetailsService.loadUserByUsername(username); // => Load user from database/cache
        if (jwtUtil.isTokenValid(token, username)) { // => Verify signature + expiration + username match
          UsernamePasswordAuthenticationToken auth = new UsernamePasswordAuthenticationToken( // => Create Spring Security auth token
            user, null, user.getAuthorities() // => principal, credentials (null for JWT), authorities
            // => Retrieves data
          );
          SecurityContextHolder.getContext().setAuthentication(auth); // => Set authentication in security context
          // => Assigns > Set authentication in security context to //
        }
        // => Block delimiter
      }
      // => Block delimiter
    }
    chain.doFilter(request, response); // => Continue filter chain (with or without authentication)
    // => Assigns > Continue filter chain (with or without authentication) to //
  }
  // => Block delimiter
}
 
// Security config
@Configuration
// => Configuration class - contains @Bean methods
// => Spring configuration class - defines bean factory methods
@EnableWebSecurity
// => Enables Spring Security configuration
// => Enables Spring Security web/method security
public class JwtSecurityConfig {
// => Class declaration
// => Class definition begins
    // => Begins block
  @Autowired private JwtAuthFilter jwtAuthFilter;
  // => Spring injects matching bean by type
  // => Spring injects dependency automatically
 
  @Bean
  // => Defines a Spring-managed bean
  // => Declares a Spring-managed bean
  public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
  // => Method definition
  // => Method definition
    // => Begins block
    http
      .csrf(csrf -> csrf.disable()) // => Disable CSRF (not needed for stateless JWT APIs)
      .authorizeHttpRequests(auth -> auth // => Configure authorization
        .requestMatchers("/auth/**").permitAll() // => Public auth endpoints (login, register)
        .anyRequest().authenticated() // => All other endpoints require JWT
        // => Executes method call
      )
      .sessionManagement(session -> session // => Configure session management
        .sessionCreationPolicy(SessionCreationPolicy.STATELESS) // => No HTTP sessions (JWT is stateless)
        // => Executes method call
      )
      .addFilterBefore(jwtAuthFilter, UsernamePasswordAuthenticationFilter.class); // => Insert JWT filter before default auth filter
      // => Assigns > Insert JWT filter before default auth filter to //
 
    return http.build(); // => Build SecurityFilterChain bean
    // => Assigns > Build SecurityFilterChain bean to //
  }
}
 
// Auth controller
@RestController
// => REST controller - returns JSON directly
// => REST controller - combines @Controller + @ResponseBody
@RequestMapping("/auth")
// => Base URL path for all endpoints in class
// => Annotation applied
    // => Executes method
public class AuthController {
// => Class declaration
// => Class definition begins
    // => Begins block
  @Autowired private AuthenticationManager authManager; // => Spring Security authentication manager
  @Autowired private JwtUtil jwtUtil; // => Inject JWT utility
 
  @PostMapping("/login") // => Endpoint: POST /auth/login
  public ResponseEntity<String> login(@RequestBody LoginRequest request) { // => Accept JSON login request
    authManager.authenticate( // => Validate username + password (throws if invalid)
      new UsernamePasswordAuthenticationToken(request.getUsername(), request.getPassword()) // => Create auth token
    ); // => If authentication fails, throws BadCredentialsException
    String token = jwtUtil.generateToken(request.getUsername()); // => Generate JWT for authenticated user
    return ResponseEntity.ok(token); // => Return JWT to client
    // => Assigns > Return JWT to client to //
  }
}
 
// Usage:
// POST /auth/login {"username":"user1","password":"pass123"}
// Response: "eyJhbGciOiJIUzI1NiJ9..."
// GET /api/data with Header: Authorization: Bearer eyJhbGciOiJIUzI1NiJ9...

// build.gradle.kts
dependencies {
// => Block begins
    implementation("io.jsonwebtoken:jjwt-api:0.12.3")
    runtimeOnly("io.jsonwebtoken:jjwt-impl:0.12.3")
    runtimeOnly("io.jsonwebtoken:jjwt-jackson:0.12.3")
}
 
// JWT utility class in Kotlin
@Component
// => Spring component - detected by component scan
// => Spring-managed component bean
class JwtUtil {
// => Class declaration
// => Class declaration
    private val secret = "mySecretKey1234567890123456789012" // 256-bit key
    // => Immutable property
    // => Private class member
    private val expiration = 86400000L // 24 hours (Long type)
    // => Immutable property
    // => Private class member
 
    fun generateToken(username: String): String {
    // => Function definition
    // => Function declaration
        return Jwts.builder()
        // => Returns to caller
        // => Returns value to caller
            .subject(username) // => Set "sub" claim (token owner)
            .issuedAt(Date()) // => Set "iat" claim (issued at timestamp)
            .expiration(Date(System.currentTimeMillis() + expiration))
            .signWith(Keys.hmacShaKeyFor(secret.toByteArray()))
            .compact() // => Serialize to Base64-encoded string
        // => Result format: header.payload.signature (JWT standard)
    }
 
    fun extractUsername(token: String): String {
    // => Function definition
    // => Function declaration
        return Jwts.parser()
        // => Returns to caller
        // => Returns value to caller
            .verifyWith(Keys.hmacShaKeyFor(secret.toByteArray()))
            .build()
            .parseSignedClaims(token)
            .payload
            .subject // Kotlin property access
    }
 
    fun isTokenValid(token: String, username: String): Boolean {
    // => Function definition
    // => Function declaration
        return try {
        // => Returns to caller
        // => Returns value to caller
            val extractedUser = extractUsername(token)
            // => Immutable property
            // => Immutable binding (read-only reference)
            extractedUser == username && !isTokenExpired(token)
            // => Assignment
        } catch (e: Exception) {
        // => Block begins
            false // Invalid token
        }
    }
 
    private fun isTokenExpired(token: String): Boolean {
    // => Function definition
    // => Function declaration
        val expiration = Jwts.parser()
        // => Immutable property
        // => Immutable binding (read-only reference)
            .verifyWith(Keys.hmacShaKeyFor(secret.toByteArray()))
            .build()
            .parseSignedClaims(token)
            .payload
            .expiration
        return expiration.before(Date())
        // => Returns to caller
        // => Returns value to caller
    }
}
 
// JWT filter extending OncePerRequestFilter
@Component
// => Spring component - detected by component scan
// => Spring-managed component bean
class JwtAuthFilter(
// => Class declaration
// => Class declaration
    private val jwtUtil: JwtUtil,
    // => Immutable property
    // => Private class member
    private val userDetailsService: UserDetailsService
    // => Immutable property
    // => Private class member
) : OncePerRequestFilter() {
// => Block begins
 
    override fun doFilterInternal(
    // => Function definition
    // => Overrides parent class/interface method
        request: HttpServletRequest,
        // => Statement
        response: HttpServletResponse,
        // => Statement
        filterChain: FilterChain
    ) {
    // => Block begins
        val header = request.getHeader("Authorization")
        // => Immutable property
        // => Immutable binding (read-only reference)
        if (header != null && header.startsWith("Bearer ")) {
        // => Assignment
        // => Block begins
            val token = header.substring(7)
            // => Immutable property
            // => Immutable binding (read-only reference)
            val username = jwtUtil.extractUsername(token)
            // => Immutable property
            // => Immutable binding (read-only reference)
 
            if (username != null && SecurityContextHolder.getContext().authentication == null) {
            // => Block begins
                val user = userDetailsService.loadUserByUsername(username)
                // => Immutable property
                // => Immutable binding (read-only reference)
                if (jwtUtil.isTokenValid(token, username)) {
                // => Block begins
                    val auth = UsernamePasswordAuthenticationToken(
                    // => Immutable property
                    // => Immutable binding (read-only reference)
                        user, null, user.authorities
                    )
                    SecurityContextHolder.getContext().authentication = auth
                    // => Assignment
                    // => Assignment
                }
            }
        }
        filterChain.doFilter(request, response)
    }
}
 
// Security config with JWT
@Configuration
// => Configuration class - contains @Bean methods
// => Marks class as Spring configuration (bean factory)
@EnableWebSecurity
// => Enables Spring Security configuration
// => Annotation applied
open class JwtSecurityConfig(
// => Class declaration
// => Class declaration
    private val jwtAuthFilter: JwtAuthFilter
    // => Immutable property
    // => Private class member
) {
// => Block begins
 
    @Bean
    // => Defines a Spring-managed bean
    // => Declares a Spring-managed bean
    open fun filterChain(http: HttpSecurity): SecurityFilterChain {
    // => Function definition
    // => Function declaration
        http {
        // => Block begins
            csrf { disable() }
            authorizeHttpRequests {
            // => Block begins
                authorize("/auth/**", permitAll)
                authorize(anyRequest, authenticated)
            }
            sessionManagement {
            // => Block begins
                sessionCreationPolicy = SessionCreationPolicy.STATELESS
                // => Assignment
                // => Assignment
            }
            addFilterBefore<UsernamePasswordAuthenticationFilter>(jwtAuthFilter)
        }
        return http.build()
        // => Returns to caller
        // => Returns value to caller
    }
}
 
// Login request DTO
data class LoginRequest(
// => Data class: auto-generates equals/hashCode/toString/copy
// => Data class: auto-generates equals/hashCode/toString/copy/componentN
    val username: String,
    // => Immutable property
    val password: String
    // => Immutable property
)
 
// Auth controller
@RestController
// => REST controller - returns JSON directly
// => Combines @Controller and @ResponseBody
@RequestMapping("/auth")
// => Base URL path for all endpoints in class
// => HTTP endpoint mapping
class AuthController(
// => Class declaration
// => Class declaration
    private val authManager: AuthenticationManager,
    // => Immutable property
    // => Private class member
    private val jwtUtil: JwtUtil
    // => Immutable property
    // => Private class member
) {
// => Block begins
 
    @PostMapping("/login")
    // => HTTP POST endpoint
    // => HTTP endpoint mapping
    fun login(@RequestBody request: LoginRequest): ResponseEntity<String> {
    // => Function definition
    // => Function declaration
        authManager.authenticate(
            UsernamePasswordAuthenticationToken(request.username, request.password)
        )
        val token = jwtUtil.generateToken(request.username)
        // => Immutable property
        // => Immutable binding (read-only reference)
        return ResponseEntity.ok(token)
        // => Returns to caller
        // => Returns value to caller
    }
}
 
// Usage:
// POST /auth/login {"username":"user1","password":"pass123"}
// Response: "eyJhbGciOiJIUzI1NiJ9..."
// GET /api/data with Header: Authorization: Bearer eyJhbGciOiJIUzI1NiJ9...

// pom.xml
<dependency>
// => Executes
// => Code execution
  <groupId>org.springframework.boot</groupId>
  // => Code execution
  <artifactId>spring-boot-starter-oauth2-client</artifactId>
  // => Code execution
</dependency>
// => Code execution
 
// application.yml
spring:
// => Code execution
  security:
  // => Code execution
    oauth2:
    // => Code execution
      client:
      // => Code execution
        registration:
        // => Code execution
          google:
          // => Code execution
            client-id: YOUR_GOOGLE_CLIENT_ID
            // => Code execution
            client-secret: YOUR_GOOGLE_CLIENT_SECRET
            // => Code execution
            scope:
            // => Code line
              - email
              // => Code line
              - profile
              // => Code line
          github:
          // => Code line
            client-id: YOUR_GITHUB_CLIENT_ID
            // => Code line
            client-secret: YOUR_GITHUB_CLIENT_SECRET
            // => Code line
            scope:
            // => Code line
              - user:email
              // => Code line
              - read:user
              // => Code line
 
// Security config
@Configuration
// => Annotation applied
@EnableWebSecurity
// => Annotation applied
public class OAuth2Config {
    // => Begins block
  @Bean
  // => Annotation applied
  public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
    // => Begins block
    http
      .authorizeHttpRequests(auth -> auth // => Configure URL authorization
        .requestMatchers("/", "/login", "/error").permitAll() // => Public pages
        .anyRequest().authenticated() // => All others require OAuth2 login
        // => Executes method call
      )
      .oauth2Login(oauth2 -> oauth2 // => Configure OAuth2 login
        .loginPage("/login") // => Custom login page (links to Google/GitHub)
        .defaultSuccessUrl("/dashboard") // => Redirect after successful OAuth2 authentication
        // => Executes method call
      );
      // => Executes statement
 
    return http.build(); // => Build SecurityFilterChain bean
    // => Assigns > Build SecurityFilterChain bean to //
  }
  // => Block delimiter
}
 
// Controller
@RestController
public class ProfileController {
    // => Begins block
  @GetMapping("/dashboard") // => Protected endpoint
  public String dashboard(@AuthenticationPrincipal OAuth2User principal) { // => Inject OAuth2 authenticated user
    String name = principal.getAttribute("name"); // => Extract "name" claim from provider
    String email = principal.getAttribute("email"); // => Extract "email" claim
    // => Result stored in email
    return "Welcome, " + name + " (" + email + ")";
    // => Returns value to caller
    // => Extracts user info from OAuth2 provider
  }
 
  @GetMapping("/user-info")
    // => Executes method
  public Map<String, Object> userInfo(@AuthenticationPrincipal OAuth2User principal) {
    // => Begins block
    return principal.getAttributes(); // => Complete OAuth2 profile (name, email, picture, etc.)
    // => Result stored in //
  }
}
 
// Flow:
// 1. User clicks "Login with Google"
// 2. Redirects to Google's login page
// 3. User authenticates with Google
// 4. Google redirects back with authorization code
// 5. Spring exchanges code for access token
// 6. Spring fetches user info from Google
// 7. User logged in, redirected to /dashboard

// application.properties
spring.security.oauth2.client.registration.google.client-id=YOUR_CLIENT_ID
// => Assignment
spring.security.oauth2.client.registration.google.client-secret=YOUR_SECRET
// => Assignment
spring.security.oauth2.client.registration.google.scope=profile,email
// => Assignment
 
// Security configuration
@Configuration
// => Marks class as Spring configuration (bean factory)
@EnableWebSecurity
// => Annotation applied
open class OAuth2SecurityConfig {
// => Class declaration
  @Bean
  // => Declares a Spring-managed bean
  open fun filterChain(http: HttpSecurity): SecurityFilterChain {
  // => Function declaration
    http {
    // => Block begins
      authorizeHttpRequests {
      // => Block begins
        authorize("/", permitAll)
        authorize("/login/**", permitAll)  // OAuth2 login endpoints
        authorize(anyRequest, authenticated)
      }
      oauth2Login {
      // => Block begins
        defaultSuccessUrl("/dashboard", true)  // Redirect after successful login
      }
      // => Enables OAuth2 login flow with Google
    }
    return http.build()
    // => Returns value to caller
  }
}
 
// Controller handling OAuth2 user
@RestController
// => Combines @Controller and @ResponseBody
class OAuth2Controller {
// => Class declaration
  @GetMapping("/dashboard")
  // => HTTP endpoint mapping
  fun dashboard(@AuthenticationPrincipal principal: OAuth2User): String {
  // => Function declaration
    val name = principal.getAttribute<String>("name") ?: "User"
    // => Immutable binding (read-only reference)
    return "Welcome, $name!"  // String template with null safety
    // => Returns value to caller
    // => Extracts user info from OAuth2 provider
  }
 
  @GetMapping("/user-info")
  // => HTTP endpoint mapping
  fun userInfo(@AuthenticationPrincipal principal: OAuth2User): Map<String, Any> {
  // => Function declaration
    return principal.attributes  // Complete OAuth2 profile (name, email, picture, etc.)
    // => Returns value to caller
  }
}
 
// Flow:
// 1. User clicks "Login with Google"
// 2. Redirects to Google's login page
// 3. User authenticates with Google
// 4. Google redirects back with authorization code
// 5. Spring exchanges code for access token
// 6. Spring fetches user info from Google
// 7. User logged in, redirected to /dashboard
 
// Kotlin-specific: Use getAttribute<T> with type parameter for type-safe extraction
// Alternative with scope functions:
// val name = principal.getAttribute<String>("name")?.also { println("User $it logged in") } ?: "User"

// Test class
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
// => Starts full Spring application context with embedded server on random port
// => RANDOM_PORT avoids port conflicts when running parallel tests
// => Loads all beans: controllers, services, repositories, configurations
public class ProductControllerIntegrationTest {
  @Autowired private TestRestTemplate restTemplate; // HTTP client for testing
  // => Injected HTTP client configured for random port
  // => Automatically includes correct base URL (http://localhost:random-port)
  @Autowired private ProductRepository productRepo;
  // => Injected repository for database operations in tests
 
  @BeforeEach
  void setup() {
    productRepo.deleteAll(); // Clean database before each test
    // => Ensures test isolation (each test starts with empty database)
    // => Prevents test interdependencies and flakiness
  }
 
  @Test
  void testCreateAndRetrieveProduct() {
    // Create product
    Product product = new Product("Laptop", 999.99);
    // => Creates entity object (not yet persisted)
    ResponseEntity<Product> createResponse = restTemplate.postForEntity(
      "/api/products", product, Product.class
      // => HTTP POST to /api/products with product as JSON body
      // => Server deserializes JSON → Product object → save to DB
    );
    assertEquals(HttpStatus.CREATED, createResponse.getStatusCode());
    // => Verifies controller returns 201 Created status
    Long productId = createResponse.getBody().getId();
    // => Extracts auto-generated ID from response body
    // => Example: productId = 1 (database sequence)
 
    // Retrieve product
    ResponseEntity<Product> getResponse = restTemplate.getForEntity(
      "/api/products/" + productId, Product.class
      // => HTTP GET to /api/products/1
      // => Server queries database and returns JSON
    );
    assertEquals(HttpStatus.OK, getResponse.getStatusCode());
    // => Verifies controller returns 200 OK status
    assertEquals("Laptop", getResponse.getBody().getName());
    // => Verifies retrieved product has correct name
    // => Full end-to-end test: controller → service → repository → database
    // => Tests complete request-response cycle including JSON serialization
  }
 
  @Test
  void testDeleteProduct() {
    Product product = productRepo.save(new Product("Mouse", 25.00));
    // => Directly persists product to database (bypasses controller)
    // => Returns saved entity with generated ID (e.g., id=2)
 
    restTemplate.delete("/api/products/" + product.getId());
    // => HTTP DELETE to /api/products/2
    // => Triggers controller → service → repository.deleteById(2)
 
    assertFalse(productRepo.existsById(product.getId()));
    // => Verifies deletion through full stack
    // => Queries database to confirm product no longer exists
    // => False means product successfully deleted
  }
}
 
// Mocking external dependencies
@SpringBootTest
// => Loads full application context (no web server needed for this test)
public class OrderServiceTest {
  @Autowired private OrderService orderService;
  // => Injected real OrderService bean (tests real service logic)
 
  @MockBean // Replace real bean with mock
  private PaymentGateway paymentGateway;
  // => Replaces real PaymentGateway bean with Mockito mock
  // => Prevents real payment API calls during tests
  // => Mock behavior defined in test methods
 
  @Test
  void testProcessOrder() {
    // Stub mock behavior
    when(paymentGateway.charge(any(), any())).thenReturn(true);
    // => Configures mock: when charge() called with ANY arguments → return true
    // => Simulates successful payment without calling real gateway
    // => any() = Mockito matcher for any argument value
 
    Order order = new Order("user1", 100.00);
    // => Creates test order object (username="user1", amount=100.00)
    orderService.processOrder(order);
    // => Calls real service method (which calls mocked gateway)
    // => Service logic executes normally, but gateway.charge() uses mock
 
    verify(paymentGateway, times(1)).charge(eq("user1"), eq(100.00));
    // => Verifies mock was called exactly once with specific arguments
    // => eq("user1") = Mockito matcher for exact value match
    // => Ensures service passed correct parameters to gateway
    // => Tests order processing without calling real payment gateway
    // => Avoids network calls, payment charges, and external dependencies
  }
}

// Test class
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
// => Annotation applied
// => Annotation applied
class ProductControllerIntegrationTest {
// => Class declaration
// => Class declaration
  @Autowired private lateinit var restTemplate: TestRestTemplate  // HTTP client for testing
  // => Spring injects matching bean by type
  // => Injects Spring-managed dependency
  @Autowired private lateinit var productRepo: ProductRepository
  // => Spring injects matching bean by type
  // => Injects Spring-managed dependency
 
  @BeforeEach
  // => Annotation applied
  // => Annotation applied
  fun setup() {
  // => Function definition
  // => Function declaration
    productRepo.deleteAll()  // Clean database before each test
  }
 
  @Test
  // => Annotation applied
  // => Annotation applied
  fun testCreateAndRetrieveProduct() {
  // => Function definition
  // => Function declaration
    // Create product
    val product = Product("Laptop", 999.99)
    // => Immutable property
    // => Immutable binding (read-only reference)
    val createResponse = restTemplate.postForEntity(
    // => Immutable property
    // => Immutable binding (read-only reference)
      "/api/products", product, Product::class.java
    )
    assertEquals(HttpStatus.CREATED, createResponse.statusCode)
    val productId = createResponse.body!!.id  // Non-null assertion (test environment controlled)
    // => Immutable property
    // => Immutable binding (read-only reference)
 
    // Retrieve product
    val getResponse = restTemplate.getForEntity(
    // => Immutable property
    // => Immutable binding (read-only reference)
      "/api/products/$productId", Product::class.java  // String template
    )
    assertEquals(HttpStatus.OK, getResponse.statusCode)
    assertEquals("Laptop", getResponse.body!!.name)
    // => Full end-to-end test: controller → service → repository → database
  }
 
  @Test
  // => Annotation applied
  // => Annotation applied
  fun testDeleteProduct() {
  // => Function definition
  // => Function declaration
    val product = productRepo.save(Product("Mouse", 25.00))
    // => Immutable property
    // => Immutable binding (read-only reference)
 
    restTemplate.delete("/api/products/${product.id}")  // String template for URL
 
    assertFalse(productRepo.existsById(product.id!!))
    // => Verifies deletion through full stack
  }
}
 
// Mocking external dependencies
@SpringBootTest
// => Annotation applied
// => Annotation applied
class OrderServiceTest {
// => Class declaration
// => Class declaration
  @Autowired private lateinit var orderService: OrderService
  // => Spring injects matching bean by type
  // => Injects Spring-managed dependency
 
  @MockBean  // Replace real bean with mock
  // => Annotation applied
  // => Annotation applied
  private lateinit var paymentGateway: PaymentGateway
 
  @Test
  // => Annotation applied
  // => Annotation applied
  fun testProcessOrder() {
  // => Function definition
  // => Function declaration
    // Stub mock behavior
    `when`(paymentGateway.charge(any(), any())).thenReturn(true)  // Backticks escape Kotlin keyword
 
    val order = Order("user1", 100.00)
    // => Immutable property
    // => Immutable binding (read-only reference)
    orderService.processOrder(order)
 
    verify(paymentGateway, times(1)).charge(eq("user1"), eq(100.00))
    // => Tests order processing without calling real payment gateway
  }
}
 
// Kotlin-specific: Use backticks to escape 'when' keyword when calling Mockito's when() method
// Alternative with MockK (Kotlin mocking library):
// every { paymentGateway.charge(any(), any()) } returns true
// verify(exactly = 1) { paymentGateway.charge("user1", 100.00) }

@WebMvcTest(ProductController.class) // Only load ProductController
    // => Executes method
public class ProductControllerUnitTest {
    // => Begins block
  @Autowired private MockMvc mockMvc; // Simulates HTTP requests
  // => Annotation applied
 
  @MockBean // Mock the service layer
  // => Annotation applied
  private ProductService productService;
  // => Declares productService field of type ProductService
 
  @Test
  // => Annotation applied
  void testGetProduct() throws Exception {
    // => Executes method
    // Arrange
    Product product = new Product(1L, "Laptop", 999.99);
    // => Creates new instance
    when(productService.findById(1L)).thenReturn(Optional.of(product));
    // => Executes method
 
    // Act & Assert
    mockMvc.perform(get("/api/products/1"))
    // => Executes method
      .andExpect(status().isOk())
    // => Executes method
      .andExpect(jsonPath("$.name").value("Laptop"))
    // => Executes method
      .andExpect(jsonPath("$.price").value(999.99));
    // => Executes method
    // => Tests controller logic without starting full app
  }
  // => Block delimiter
 
  @Test
  // => Annotation applied
  void testCreateProduct() throws Exception {
    // => Executes method
    Product product = new Product("Mouse", 25.00);
    // => Creates new instance
    when(productService.save(any(Product.class))).thenReturn(product);
    // => Executes method
 
    mockMvc.perform(post("/api/products")
    // => Executes method
        .contentType(MediaType.APPLICATION_JSON)
    // => Executes method
        .content("{\"name\":\"Mouse\",\"price\":25.00}"))
    // => Executes method
      .andExpect(status().isCreated())
    // => Executes method
      .andExpect(jsonPath("$.name").value("Mouse"));
    // => Executes method
  }
  // => Block delimiter
 
  @Test
  // => Annotation applied
  void testGetProductNotFound() throws Exception {
    // => Executes method
    when(productService.findById(999L)).thenReturn(Optional.empty());
    // => Executes method
 
    mockMvc.perform(get("/api/products/999"))
    // => Executes method
      .andExpect(status().isNotFound());
    // => Executes method
    // => Tests error handling
  }
  // => Block delimiter
}

@WebMvcTest(ProductController::class)  // Only load ProductController
// => Annotation applied
// => Annotation applied
class ProductControllerUnitTest {
// => Class declaration
// => Class declaration
  @Autowired private lateinit var mockMvc: MockMvc  // Simulates HTTP requests
  // => Spring injects matching bean by type
  // => Injects Spring-managed dependency
 
  @MockBean  // Mock the service layer
  // => Annotation applied
  // => Annotation applied
  private lateinit var productService: ProductService
 
  @Test
  // => Annotation applied
  // => Annotation applied
  fun testGetProduct() {
  // => Function definition
  // => Function declaration
    // Arrange
    val product = Product(1L, "Laptop", 999.99)
    // => Immutable property
    // => Immutable binding (read-only reference)
    `when`(productService.findById(1L)).thenReturn(Optional.of(product))
 
    // Act & Assert
    mockMvc.perform(get("/api/products/1"))
      .andExpect(status().isOk)
      .andExpect(jsonPath("$.name").value("Laptop"))
      .andExpect(jsonPath("$.price").value(999.99))
    // => Tests controller logic without starting full app
  }
 
  @Test
  // => Annotation applied
  // => Annotation applied
  fun testCreateProduct() {
  // => Function definition
  // => Function declaration
    val product = Product("Mouse", 25.00)
    // => Immutable property
    // => Immutable binding (read-only reference)
    `when`(productService.save(any(Product::class.java))).thenReturn(product)
 
    mockMvc.perform(post("/api/products")
        .contentType(MediaType.APPLICATION_JSON)
        .content("""{"name":"Mouse","price":25.00}"""))  // Triple-quoted string
      .andExpect(status().isCreated)
      .andExpect(jsonPath("$.name").value("Mouse"))
  }
 
  @Test
  // => Annotation applied
  // => Annotation applied
  fun testGetProductNotFound() {
  // => Function definition
  // => Function declaration
    `when`(productService.findById(999L)).thenReturn(Optional.empty())
 
    mockMvc.perform(get("/api/products/999"))
      .andExpect(status().isNotFound)
    // => Tests error handling
  }
}
 
// Kotlin-specific: Use triple-quoted strings for JSON payloads to avoid escaping
// Alternative idiomatic approach with companion object for test data:
// companion object {
//   private val SAMPLE_PRODUCT = Product(1L, "Laptop", 999.99)
// }