Spring Boot @Transactional - Private Method Costs $12k

package io.thecodeforge.annotations;

import org.springframework.web.bind.annotation.*;
import org.springframework.stereotype.*;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.http.ResponseEntity;
import org.springframework.dao.DataAccessException;

/**
 * io.thecodeforge: Stereotype annotations in a standard three-layer architecture.
 *
 * @RestController → web layer, handles HTTP
 * @Service        → business layer, contains logic
 * @Repository     → data layer, adds exception translation
 */
@RestController
@RequestMapping("/api/v1/forge")
public class ForgeController {

    private final ForgeService service;

    // Constructor injection: preferred over @Autowired on fields.
    // Dependencies are explicit, final, and testable without Spring context.
    public ForgeController(ForgeService service) {
        this.service = service;
    }

    @PostMapping("/process/{id}")
    public ResponseEntity<String> executeJob(
            @PathVariable("id") Long id,
            @RequestBody JobRequest request) {
        String result = service.process(id, request.getPayload());
        return ResponseEntity.ok(result);
    }
}

@Service
class ForgeService {

    // @Value injects property values from application.yml or environment variables.
    // The :production part is the default if the property is not defined.
    @Value("${forge.environment:production}")
    private String env;

    private final ForgeRepository repository;

    public ForgeService(ForgeRepository repository) {
        this.repository = repository;
    }

    public String process(Long id, String data) {
        try {
            repository.save(id, data);
            return String.format("Env: %s | Job %d processed: %s", env, id, data);
        } catch (DataAccessException ex) {
            // @Repository's exception translation means we catch DataAccessException
            // here regardless of whether the underlying store is JDBC, JPA, or MongoDB.
            // Without @Repository on ForgeRepository, this catch block gets SQLException instead.
            throw new RuntimeException("Failed to persist job " + id, ex);
        }
    }
}

// @Repository adds exception translation — SQLExceptions become DataAccessExceptions.
// Without this annotation, raw persistence exceptions leak into the service layer.
@Repository
class ForgeRepository {
    public void save(Long id, String data) {
        // JDBC or JPA persistence logic here
    }
}

class JobRequest {
    private String payload;
    public String getPayload() { return payload; }
    public void setPayload(String payload) { this.payload = payload; }
}

package io.thecodeforge.annotations.web;

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
import jakarta.validation.Valid;
import java.util.Map;

/**
 * io.thecodeforge: Web annotation reference — every annotation you use in a REST controller.
 */
@RestController  // = @Controller + @ResponseBody on every method
@RequestMapping("/api/v1/orders")
public class OrderController {

    // @GetMapping is shorthand for @RequestMapping(method = RequestMethod.GET)
    // Use shortcuts — they communicate intent faster than the verbose form.
    @GetMapping("/{orderId}")
    public ResponseEntity<OrderDto> getOrder(
            // @PathVariable: extracts {orderId} from the URI template
            @PathVariable Long orderId,
            // @RequestHeader: extracts a specific HTTP header — useful for correlation IDs
            @RequestHeader(value = "X-Correlation-Id", required = false) String correlationId) {

        // In real code: return orderService.findById(orderId)
        return ResponseEntity.ok(new OrderDto(orderId, "PENDING"));
    }

    @GetMapping
    public ResponseEntity<Object> searchOrders(
            // @RequestParam: extracts query string parameters
            // /api/v1/orders?status=PENDING&page=0
            @RequestParam(value = "status", required = false, defaultValue = "ALL") String status,
            @RequestParam(value = "page", defaultValue = "0") int page) {

        return ResponseEntity.ok(Map.of("status", status, "page", page));
    }

    // @ResponseStatus sets the default HTTP response code for this method.
    // Without it, POST endpoints return 200 OK — semantically wrong for a creation.
    @PostMapping
    @ResponseStatus(HttpStatus.CREATED)  // Returns 201 Created on success
    public OrderDto createOrder(
            // @RequestBody: deserializes JSON request body into OrderDto via Jackson
            // @Valid: triggers Bean Validation on the deserialized object
            @Valid @RequestBody OrderDto dto) {
        return dto;
    }

    @DeleteMapping("/{orderId}")
    @ResponseStatus(HttpStatus.NO_CONTENT)  // 204 No Content — no response body
    public void cancelOrder(@PathVariable Long orderId) {
        // orderService.cancel(orderId)
    }
}

// Record DTO — clean, immutable, no boilerplate
record OrderDto(Long id, String status) {}

// --- Global Exception Handler ---
// @RestControllerAdvice = @ControllerAdvice + @ResponseBody
// Applies to all @Controller and @RestController classes in the application.
// This is the right place for error handling — not try-catch in every controller.
@RestControllerAdvice
class GlobalExceptionHandler {

    // @ExceptionHandler intercepts this exception type thrown anywhere in any controller.
    // Spring matches the most specific handler — IllegalArgumentException before RuntimeException.
    @ExceptionHandler(IllegalArgumentException.class)
    @ResponseStatus(HttpStatus.BAD_REQUEST)
    public Map<String, String> handleBadRequest(IllegalArgumentException ex) {
        return Map.of(
            "error", "Bad Request",
            "message", ex.getMessage()
        );
    }

    // Catch-all for unhandled exceptions — always have this to prevent stack traces reaching clients
    @ExceptionHandler(Exception.class)
    @ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR)
    public Map<String, String> handleGenericError(Exception ex) {
        // Log ex here — do not return stack trace to client
        return Map.of("error", "Internal Server Error");
    }
}

package io.thecodeforge.annotations.data;

import jakarta.persistence.*;
import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.data.jpa.repository.Query;
import org.springframework.data.jpa.repository.Modifying;
import org.springframework.data.repository.query.Param;
import org.springframework.stereotype.Repository;
import org.springframework.transaction.annotation.Transactional;

import java.math.BigDecimal;
import java.time.LocalDateTime;
import java.util.List;
import java.util.Optional;

/**
 * io.thecodeforge: JPA entity with relationship modeling.
 * Every annotation here maps to a specific SQL behavior — comments explain what.
 */
@Entity
@Table(name = "orders",
       indexes = @Index(name = "idx_orders_customer_id", columnList = "customer_id"),
       uniqueConstraints = @UniqueConstraint(columnNames = {"reference_number"}))
public class Order {

    // IDENTITY: database auto-increments; never set this field manually.
    // Use SEQUENCE for PostgreSQL high-throughput scenarios — IDENTITY locks the row on insert.
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    // Explicit column mapping: non-null, max length enforced at JPA layer.
    // JPA enforcement catches violations before a database round trip.
    @Column(name = "reference_number", nullable = false, length = 50, unique = true)
    private String referenceNumber;

    @Column(name = "customer_id", nullable = false)
    private Long customerId;

    // Precision and scale are critical for monetary values.
    // Without them, JPA defaults vary by database — never leave money columns to defaults.
    @Column(name = "total_amount", nullable = false, precision = 19, scale = 4)
    private BigDecimal totalAmount;

    @Enumerated(EnumType.STRING)  // Store 'PENDING' not '0' — readable in DB, survives enum reordering
    @Column(name = "status", nullable = false)
    private OrderStatus status;

    @Column(name = "created_at", nullable = false, updatable = false)
    private LocalDateTime createdAt;

    // @OneToMany with mappedBy: this side does not own the relationship.
    // The OrderItem side owns it via @ManyToOne @JoinColumn.
    // Without mappedBy, JPA creates a separate join table — not what you want.
    // CascadeType.ALL: persist/remove items when order is persisted/removed.
    // orphanRemoval: delete items from DB when removed from this collection.
    @OneToMany(mappedBy = "order", cascade = CascadeType.ALL, orphanRemoval = true)
    private List<OrderItem> items;

    @PrePersist  // Lifecycle callback: runs before first save, not on updates
    protected void onCreate() {
        this.createdAt = LocalDateTime.now();
    }

    // Constructors, getters, setters omitted for brevity
    public Long getId() { return id; }
    public String getReferenceNumber() { return referenceNumber; }
    public OrderStatus getStatus() { return status; }
    public void setStatus(OrderStatus status) { this.status = status; }
}

@Entity
@Table(name = "order_items")
class OrderItem {

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

    // @ManyToOne is the owning side — this entity's table has the FK column.
    // @JoinColumn(name = "order_id") names the foreign key column explicitly.
    @ManyToOne(fetch = FetchType.LAZY)  // LAZY: do not load Order unless accessed
    @JoinColumn(name = "order_id", nullable = false)
    private Order order;

    @Column(name = "product_id", nullable = false)
    private Long productId;

    @Column(name = "quantity", nullable = false)
    private int quantity;

    public Order getOrder() { return order; }
    public void setOrder(Order order) { this.order = order; }
}

enum OrderStatus { PENDING, CONFIRMED, SHIPPED, CANCELLED }

// --- Spring Data JPA Repository ---
@Repository
public interface OrderRepository extends JpaRepository<Order, Long> {

    // Derived query: Spring generates the SQL from the method name.
    // Readable for simple cases — use @Query when the method name becomes a sentence.
    List<Order> findByCustomerIdAndStatus(Long customerId, OrderStatus status);

    // @Query with JPQL: use entity names and field names, not table/column names.
    // This is more readable than a 60-character method name.
    @Query("SELECT o FROM Order o WHERE o.customerId = :customerId "
         + "AND o.totalAmount >= :minAmount "
         + "AND o.createdAt >= :since "
         + "ORDER BY o.createdAt DESC")
    List<Order> findHighValueOrdersSince(
            @Param("customerId") Long customerId,
            @Param("minAmount") BigDecimal minAmount,
            @Param("since") LocalDateTime since);

    // @Modifying + @Transactional: required for UPDATE and DELETE queries.
    // Without @Modifying, Spring throws an exception.
    // Without @Transactional, the update executes but may not commit.
    // clearAutomatically=true: clears the persistence context after execution
    // to prevent stale cached entities being returned in the same transaction.
    @Modifying(clearAutomatically = true)
    @Transactional
    @Query("UPDATE Order o SET o.status = :status WHERE o.id = :id")
    int updateStatus(@Param("id") Long id, @Param("status") OrderStatus status);

    // Native SQL query: use when JPQL cannot express the query (window functions,
    // database-specific functions, complex subqueries).
    // nativeQuery=true: Spring passes the SQL directly to the database.
    @Query(value = "SELECT * FROM orders WHERE EXTRACT(MONTH FROM created_at) = :month",
           nativeQuery = true)
    List<Order> findOrdersForMonth(@Param("month") int month);

    Optional<Order> findByReferenceNumber(String referenceNumber);
}

package io.thecodeforge.annotations.data;

import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Isolation;
import org.springframework.transaction.annotation.Propagation;
import org.springframework.transaction.annotation.Transactional;

import java.math.BigDecimal;

/**
 * io.thecodeforge: @Transactional propagation and isolation reference.
 * This single class demonstrates every propagation scenario that matters in production.
 */
@Service
public class PaymentService {

    private final AuditService auditService;

    public PaymentService(AuditService auditService) {
        this.auditService = auditService;
    }

    /**
     * REQUIRED (default): joins existing transaction or starts a new one.
     * This is correct for most service methods.
     *
     * rollbackFor = Exception.class: rolls back on ALL exceptions,
     * not just RuntimeException. Use this when your method can throw
     * checked exceptions that should also trigger rollback.
     */
    @Transactional(rollbackFor = Exception.class)
    public void processPayment(Long orderId, BigDecimal amount) throws Exception {
        // 1. Debit account
        // 2. Update order status
        // 3. Send to payment gateway

        // auditService.logPayment() runs in its OWN transaction (REQUIRES_NEW).
        // If processPayment() rolls back, the audit log is NOT rolled back.
        // This is intentional — you always want an audit trail, even for failures.
        auditService.logPayment(orderId, amount, "INITIATED");

        // Simulate a failure after audit has been written
        if (amount.compareTo(BigDecimal.ZERO) <= 0) {
            throw new IllegalArgumentException("Amount must be positive");
            // Transaction rolls back. auditService.logPayment() does NOT roll back
            // because it ran in REQUIRES_NEW — its transaction already committed.
        }
    }

    /**
     * REQUIRES_NEW: always starts a fresh transaction.
     * Suspends any calling transaction.
     * Use for: audit logging, retry-safe operations, independent operations
     * that should not roll back with the caller.
     *
     * WARNING: REQUIRES_NEW acquires a new connection from the pool.
     * Nested REQUIRES_NEW calls under heavy load can exhaust the connection pool.
     */
    @Transactional(propagation = Propagation.REQUIRES_NEW)
    public void processPaymentIndependently(Long orderId, BigDecimal amount) {
        // Commits independently — caller's rollback does not affect this.
    }

    /**
     * READ_COMMITTED isolation: prevents dirty reads (seeing uncommitted data
     * from other transactions). Allows non-repeatable reads — the same query
     * run twice in the same transaction can return different results.
     *
     * Use READ_COMMITTED for most read operations where perfect consistency
     * is not required and throughput matters.
     */
    @Transactional(readOnly = true, isolation = Isolation.READ_COMMITTED)
    public BigDecimal getAccountBalance(Long accountId) {
        // readOnly=true: hint to JPA to skip dirty checking on entities
        // — meaningful performance improvement in read-heavy paths.
        // Does NOT prevent writes at the JDBC level — use for read-only methods.
        return BigDecimal.ZERO; // In real code: accountRepository.findBalance(accountId)
    }

    /**
     * NEVER: throws an exception if there IS an active transaction.
     * MANDATORY: throws an exception if there is NO active transaction.
     * SUPPORTS: joins existing transaction if present, runs non-transactionally if not.
     * NOT_SUPPORTED: always runs non-transactionally, suspends existing transaction.
     *
     * These four are rare — document why you are using them when you do.
     */
    @Transactional(propagation = Propagation.MANDATORY)
    public void mustRunInTransaction(Long orderId) {
        // Throws IllegalTransactionStateException if called without an active transaction.
        // Use when a method only makes sense inside a transaction boundary.
    }
}

@Service
class AuditService {

    /**
     * REQUIRES_NEW: this method always runs in its own independent transaction.
     * Even if the calling transaction (processPayment) rolls back,
     * this audit log entry is committed.
     */
    @Transactional(propagation = Propagation.REQUIRES_NEW)
    public void logPayment(Long orderId, BigDecimal amount, String status) {
        // Persists audit record in its own committed transaction
    }
}

package io.thecodeforge.annotations.data;

import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Propagation;
import org.springframework.transaction.annotation.Transactional;

@Service
public class OrderService {

    @Transactional
    public void placeOrder(Order order) {
        // REQUIRED (default) — joins any calling transaction
        orderRepository.save(order);
        inventoryService.deduct(order);  // same transaction
        auditService.logOrder(order);    // REQUIRES_NEW — separate transaction
    }

    @Transactional(propagation = Propagation.MANDATORY)
    public void validateOrder(Order order) {
        // throws IllegalTransactionStateException if no active transaction
    }

    @Transactional(propagation = Propagation.NEVER)
    public void sendNotification(Order order) {
        // throws IllegalTransactionStateException if called within a transaction
    }
}

package io.thecodeforge.annotations.scheduling;

import org.springframework.scheduling.annotation.EnableScheduling;
import org.springframework.scheduling.annotation.Scheduled;
import org.springframework.stereotype.Component;
import org.springframework.beans.factory.annotation.Value;

@Component
@EnableScheduling  // required — without it, all @Scheduled annotations are ignored
public class ScheduledTasks {

    // Every 5 minutes: "0 */5 * * * *"
    @Scheduled(cron = "0 */5 * * * *")
    public void cleanupExpiredSessions() {
        // runs on a single thread by default; use custom TaskScheduler for concurrency
        System.out.println("Session cleanup at " + System.currentTimeMillis());
    }

    // 8 AM every weekday: "0 0 8 * * MON-FRI"
    @Scheduled(cron = "0 0 8 * * MON-FRI")
    public void generateDailyReport() {
        // generate and send report
    }

    // Fixed rate: start a new execution every 10 seconds (does not wait for completion)
    @Scheduled(fixedRate = 10000)
    public void checkHealth() {
        // runs every 10 seconds, even if previous invocation is still running
    }

    // Fixed delay: wait 5 seconds after previous execution finishes
    @Scheduled(fixedDelay = 5000, initialDelay = 1000)
    public void processQueue() {
        // runs 1 second after startup, then 5 seconds after each completion
    }
}

package io.thecodeforge.annotations.practice;

// Problem 1 Solution
// application-dev.yml: spring.profiles.active: dev
// application-prod.yml: spring.profiles.active: prod, cloud
@Configuration
public class PaymentConfig {
    @Bean @Profile({"dev","test"})
    public PaymentGateway mockPayment() { return new MockPaymentGateway(); }
    @Bean @Profile({"staging","prod"})
    public PaymentGateway realPayment() { return new RealPaymentGateway(); }
    @Bean @ConditionalOnClass(name = "org.postgresql.Driver")
    public DataSource prodDataSource() { // PostgreSQL }
    @Bean @ConditionalOnClass(name = "org.h2.Driver")
    public DataSource devDataSource() { // H2 }
}

// Problem 2 Solution
@Service
public class OrderServiceFixed {
    private final InventoryService inventoryService;
    public OrderServiceFixed(InventoryService inventoryService) {
        this.inventoryService = inventoryService;
    }
    @Transactional(rollbackFor = Exception.class)
    public void processOrder(Long orderId) {
        inventoryService.updateInventory(orderId);
        throw new RuntimeException("Simulated failure");
    }
}
@Service
public class InventoryService {
    @Transactional(propagation = Propagation.REQUIRED)
    public void updateInventory(Long orderId) { /* ... */ }
}

// Problem 3 Solution
@Configuration
public class DataSourceConfig {
    @Bean @Primary @ConfigurationProperties("app.datasource.write")
    public DataSource writeDataSource() { return DataSourceBuilder.create().build(); }
    @Bean @ConfigurationProperties("app.datasource.read")
    public DataSource readDataSource() { return DataSourceBuilder.create().build(); }
    @Bean
    public JdbcTemplate writeJdbcTemplate(@Qualifier("writeDataSource") DataSource ds) {
        return new JdbcTemplate(ds);
    }
    @Bean
    public JdbcTemplate readJdbcTemplate(@Qualifier("readDataSource") DataSource ds) {
        return new JdbcTemplate(ds);
    }
}

// Problem 4 Solution
@Component @EnableScheduling
public class ReportScheduler {
    @Value("${report.email}") private String email;
    @Value("${report.subject}") private String subject;
    @PostConstruct
    public void checkProperties() {
        Assert.hasText(email, "report.email must be set");
    }
    @Scheduled(cron = "0 0 9 * * MON")
    public void generateWeeklyReport() {
        try {
            // generate report
        } catch (Exception e) {
            log.error("Report failed", e);
        }
    }
}

// Problem 5 Solution
@Service
public class UserService {
    @Lazy @Autowired private UserService self;
    @Cacheable("users")
    public User getUser(Long id) { /* slow lookup */ }
    public List<User> getUsers(List<Long> ids) {
        return ids.stream().map(self::getUser).collect(Collectors.toList());
    }
}

// io.thecodeforge — java tutorial
// Never trust the default scan path

package com.acme.inventory;

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

@SpringBootApplication  // equals: @SpringBootConfiguration + @EnableAutoConfiguration + @ComponentScan("com.acme.inventory")
public class MainApp {

    public static void main(String[] args) {
        ConfigurableApplicationContext ctx = SpringApplication.run(MainApp.class, args);

        // Print all beans to verify component scanning
        String[] beans = ctx.getBeanDefinitionNames();
        System.out.println("Beans created: " + beans.length);
        for (String bean : beans) {
            if (bean.contains("Inventory")) {
                System.out.println("  Found: " + bean);
            }
        }
    }
}

// io.thecodeforge — java tutorial
// Spring treats @Service and @Repository identically for bean creation

package com.acme.inventory.service;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Repository;
import org.springframework.stereotype.Service;

@Service
public class InventoryService {

    @Autowired
    private InventoryRepository repo;

    public void auditStock() {
        repo.findAll().forEach(System.out::println);
    }
}

@Repository
class InventoryRepository {
    // No actual database here — just a bean for the example
    public java.util.List<String> findAll() {
        return java.util.List.of("SKU-001", "SKU-002");
    }
}

// Output confirms both beans exist with the same lifecycle

// io.thecodeforge — java tutorial

@Configuration
public class DatabaseConfig {

    @Bean
    @ConditionalOnMissingBean(DataSource.class)
    public DataSource defaultDataSource() {
        return new HikariDataSource();
    }

    @Bean
    @ConditionalOnBean(DataSource.class)
    public JdbcTemplate jdbcTemplate(DataSource ds) {
        return new JdbcTemplate(ds);
    }
}

// io.thecodeforge — java tutorial

@Configuration
public class FeatureToggleConfig {

    @Bean
    @ConditionalOnProperty(
        name = "app.cache.enabled",
        havingValue = "true",
        matchIfMissing = false
    )
    public CacheManager redisCacheManager() {
        return new RedisCacheManager();
    }

    @Bean
    @ConditionalOnProperty(
        name = "app.cache.enabled",
        havingValue = "false",
        matchIfMissing = true
    )
    public CacheManager noOpCacheManager() {
        return new NoOpCacheManager();
    }
}

// io.thecodeforge — java tutorial
@SpringBootApplication
public class ExApplication {
    public static void main(String[] args) {
        SpringApplication.run(ExApplication.class, args);
    }
}
// Spring Boot evaluates all @Conditional annotations
// during refresh, before any beans are returned.

// io.thecodeforge — java tutorial
@Configuration
public class ConditionalExamples {

    @Bean
    @ConditionalOnResource(resources = "classpath:db/schema.sql")
    DataSource customDataSource() {
        return DataSourceBuilder.create().build();
    }

    @Bean
    @ConditionalOnWebApplication(type = ConditionalOnWebApplication.Type.SERVLET)
    ErrorAttributes servletErrorAttrs() {
        return new DefaultErrorAttributes();
    }

    @Bean
    @ConditionalOnExpression("'${custom.mode}' == 'advanced'")
    AdvancedService advancedService() {
        return new AdvancedService();
    }
}