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 {\n\n    private final ForgeService service;\n\n    // Constructor injection: preferred over @Autowired on fields.\n    // Dependencies are explicit, final, and testable without Spring context.\n    public ForgeController(ForgeService service) {\n        this.service = service;\n    }

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

@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) {\n        try {\n            repository.save(id, data);\n            return String.format(\"Env: %s | Job %d processed: %s\", env, id, data);\n        } catch (DataAccessException ex) {\n            // @Repository's exception translation means we catch DataAccessException\n            // here regardless of whether the underlying store is JDBC, JPA, or MongoDB.\n            // Without @Repository on ForgeRepository, this catch block gets SQLException instead.\n            throw new RuntimeException(\"Failed to persist job \" + id, ex);\n        }\n    }\n}\n\n// @Repository adds exception translation — SQLExceptions become DataAccessExceptions.\n// Without this annotation, raw persistence exceptions leak into the service layer.\n@Repository\nclass ForgeRepository {\n    public void save(Long id, String data) {\n        // JDBC or JPA persistence logic here\n    }\n}\n\nclass JobRequest {\n    private String payload;\n    public String getPayload() { return payload; }\n    public void setPayload(String payload) { this.payload = payload; }\n}",
        "output": "POST /api/v1/forge/process/99 { \"payload\": \"ForgeData\" }\nResponse: \"Env: production | Job 99 processed: ForgeData\"\n\n// If ForgeRepository throws a JDBC exception:\n// WITHOUT @Repository: throws SQLException (leaks persistence technology details)\n// WITH @Repository:    throws DataAccessException (technology-agnostic, catchable uniformly)"
      }

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) {\n\n        // In real code: return orderService.findById(orderId)\n        return ResponseEntity.ok(new OrderDto(orderId, \"PENDING\"));\n    }\n\n    @GetMapping\n    public ResponseEntity<Object> searchOrders(\n            // @RequestParam: extracts query string parameters\n            // /api/v1/orders?status=PENDING&page=0\n            @RequestParam(value = \"status\", required = false, defaultValue = \"ALL\") String status,\n            @RequestParam(value = \"page\", defaultValue = \"0\") int page) {\n\n        return ResponseEntity.ok(Map.of(\"status\", status, \"page\", page));\n    }\n\n    // @ResponseStatus sets the default HTTP response code for this method.\n    // Without it, POST endpoints return 200 OK — semantically wrong for a creation.\n    @PostMapping\n    @ResponseStatus(HttpStatus.CREATED)  // Returns 201 Created on success\n    public OrderDto createOrder(\n            // @RequestBody: deserializes JSON request body into OrderDto via Jackson\n            // @Valid: triggers Bean Validation on the deserialized object\n            @Valid @RequestBody OrderDto dto) {\n        return dto;\n    }\n\n    @DeleteMapping(\"/{orderId}\")\n    @ResponseStatus(HttpStatus.NO_CONTENT)  // 204 No Content — no response body\n    public void cancelOrder(@PathVariable Long orderId) {\n        // orderService.cancel(orderId)\n    }\n}\n\n// Record DTO — clean, immutable, no boilerplate\nrecord OrderDto(Long id, String status) {}\n\n// --- Global Exception Handler ---\n// @RestControllerAdvice = @ControllerAdvice + @ResponseBody\n// Applies to all @Controller and @RestController classes in the application.\n// This is the right place for error handling — not try-catch in every controller.\n@RestControllerAdvice\nclass GlobalExceptionHandler {\n\n    // @ExceptionHandler intercepts this exception type thrown anywhere in any controller.\n    // Spring matches the most specific handler — IllegalArgumentException before RuntimeException.\n    @ExceptionHandler(IllegalArgumentException.class)\n    @ResponseStatus(HttpStatus.BAD_REQUEST)\n    public Map<String, String> handleBadRequest(IllegalArgumentException ex) {\n        return Map.of(\n            \"error\", \"Bad Request\",\n            \"message\", ex.getMessage()\n        );\n    }\n\n    // Catch-all for unhandled exceptions — always have this to prevent stack traces reaching clients\n    @ExceptionHandler(Exception.class)\n    @ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR)\n    public Map<String, String> handleGenericError(Exception ex) {\n        // Log ex here — do not return stack trace to client\n        return Map.of(\"error\", \"Internal Server Error\");\n    }\n}",
        "output": "GET  /api/v1/orders/42\n→ 200 OK  { \"id\": 42, \"status\": \"PENDING\" }\n\nGET  /api/v1/orders?status=PENDING&page=1\n→ 200 OK  { \"status\": \"PENDING\", \"page\": 1 }\n\nPOST /api/v1/orders  { \"id\": null, \"status\": \"NEW\" }\n→ 201 Created  { \"id\": null, \"status\": \"NEW\" }\n\nDELETE /api/v1/orders/42\n→ 204 No Content\n\n// Throwing IllegalArgumentException in any controller:\n→ 400 Bad Request  { \"error\": \"Bad Request\", \"message\": \"...\" }"
      }

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\"}))\npublic class Order {\n\n    // IDENTITY: database auto-increments; never set this field manually.\n    // Use SEQUENCE for PostgreSQL high-throughput scenarios — IDENTITY locks the row on insert.\n    @Id\n    @GeneratedValue(strategy = GenerationType.IDENTITY)\n    private Long id;\n\n    // Explicit column mapping: non-null, max length enforced at JPA layer.\n    // JPA enforcement catches violations before a database round trip.\n    @Column(name = \"reference_number\", nullable = false, length = 50, unique = true)\n    private String referenceNumber;\n\n    @Column(name = \"customer_id\", nullable = false)\n    private Long customerId;\n\n    // Precision and scale are critical for monetary values.\n    // Without them, JPA defaults vary by database — never leave money columns to defaults.\n    @Column(name = \"total_amount\", nullable = false, precision = 19, scale = 4)\n    private BigDecimal totalAmount;\n\n    @Enumerated(EnumType.STRING)  // Store 'PENDING' not '0' — readable in DB, survives enum reordering\n    @Column(name = \"status\", nullable = false)\n    private OrderStatus status;\n\n    @Column(name = \"created_at\", nullable = false, updatable = false)\n    private LocalDateTime createdAt;\n\n    // @OneToMany with mappedBy: this side does not own the relationship.\n    // The OrderItem side owns it via @ManyToOne @JoinColumn.\n    // Without mappedBy, JPA creates a separate join table — not what you want.\n    // CascadeType.ALL: persist/remove items when order is persisted/removed.\n    // orphanRemoval: delete items from DB when removed from this collection.\n    @OneToMany(mappedBy = \"order\", cascade = CascadeType.ALL, orphanRemoval = true)\n    private List<OrderItem> items;\n\n    @PrePersist  // Lifecycle callback: runs before first save, not on updates\n    protected void onCreate() {\n        this.createdAt = LocalDateTime.now();\n    }\n\n    // Constructors, getters, setters omitted for brevity\n    public Long getId() { return id; }\n    public String getReferenceNumber() { return referenceNumber; }\n    public OrderStatus getStatus() { return status; }\n    public void setStatus(OrderStatus status) { this.status = status; }\n}\n\n@Entity\n@Table(name = \"order_items\")\nclass OrderItem {\n\n    @Id\n    @GeneratedValue(strategy = GenerationType.IDENTITY)\n    private Long id;\n\n    // @ManyToOne is the owning side — this entity's table has the FK column.\n    // @JoinColumn(name = \"order_id\") names the foreign key column explicitly.\n    @ManyToOne(fetch = FetchType.LAZY)  // LAZY: do not load Order unless accessed\n    @JoinColumn(name = \"order_id\", nullable = false)\n    private Order order;\n\n    @Column(name = \"product_id\", nullable = false)\n    private Long productId;\n\n    @Column(name = \"quantity\", nullable = false)\n    private int quantity;\n\n    public Order getOrder() { return order; }\n    public void setOrder(Order order) { this.order = order; }\n}\n\nenum OrderStatus { PENDING, CONFIRMED, SHIPPED, CANCELLED }\n\n// --- Spring Data JPA Repository ---\n@Repository\npublic interface OrderRepository extends JpaRepository<Order, Long> {\n\n    // Derived query: Spring generates the SQL from the method name.\n    // Readable for simple cases — use @Query when the method name becomes a sentence.\n    List<Order> findByCustomerIdAndStatus(Long customerId, OrderStatus status);\n\n    // @Query with JPQL: use entity names and field names, not table/column names.\n    // This is more readable than a 60-character method name.\n    @Query(\"SELECT o FROM Order o WHERE o.customerId = :customerId \"\n         + \"AND o.totalAmount >= :minAmount \"\n         + \"AND o.createdAt >= :since \"\n         + \"ORDER BY o.createdAt DESC\")\n    List<Order> findHighValueOrdersSince(\n            @Param(\"customerId\") Long customerId,\n            @Param(\"minAmount\") BigDecimal minAmount,\n            @Param(\"since\") LocalDateTime since);\n\n    // @Modifying + @Transactional: required for UPDATE and DELETE queries.\n    // Without @Modifying, Spring throws an exception.\n    // Without @Transactional, the update executes but may not commit.\n    // clearAutomatically=true: clears the persistence context after execution\n    // to prevent stale cached entities being returned in the same transaction.\n    @Modifying(clearAutomatically = true)\n    @Transactional\n    @Query(\"UPDATE Order o SET o.status = :status WHERE o.id = :id\")\n    int updateStatus(@Param(\"id\") Long id, @Param(\"status\") OrderStatus status);\n\n    // Native SQL query: use when JPQL cannot express the query (window functions,\n    // database-specific functions, complex subqueries).\n    // nativeQuery=true: Spring passes the SQL directly to the database.\n    @Query(value = \"SELECT * FROM orders WHERE EXTRACT(MONTH FROM created_at) = :month\",\n           nativeQuery = true)\n    List<Order> findOrdersForMonth(@Param(\"month\") int month);\n\n    Optional<Order> findByReferenceNumber(String referenceNumber);\n}",
        "output": "// findByCustomerIdAndStatus(42L, OrderStatus.PENDING) generates:\n// SELECT * FROM orders WHERE customer_id = 42 AND status = 'PENDING'\n\n// findHighValueOrdersSince(42L, BigDecimal(\"100.00\"), lastWeek) generates:\n// SELECT * FROM orders WHERE customer_id = 42\n//   AND total_amount >= 100.00\n//   AND created_at >= '2026-04-11' ORDER BY created_at DESC\n\n// updateStatus(42L, OrderStatus.CONFIRMED) generates:\n// UPDATE orders SET status = 'CONFIRMED' WHERE id = 42\n// Returns: 1 (rows affected)\n\n// @PrePersist fires on first save:\n// INSERT INTO orders (reference_number, customer_id, total_amount, status, created_at)\n// VALUES ('REF-001', 42, 99.9900, 'PENDING', '2026-04-18T10:00:00')"
      }

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 {\n        // 1. Debit account\n        // 2. Update order status\n        // 3. Send to payment gateway\n\n        // auditService.logPayment() runs in its OWN transaction (REQUIRES_NEW).\n        // If processPayment() rolls back, the audit log is NOT rolled back.\n        // This is intentional — you always want an audit trail, even for failures.\n        auditService.logPayment(orderId, amount, \"INITIATED\");\n\n        // Simulate a failure after audit has been written\n        if (amount.compareTo(BigDecimal.ZERO) <= 0) {\n            throw new IllegalArgumentException(\"Amount must be positive\");\n            // Transaction rolls back. auditService.logPayment() does NOT roll back\n            // because it ran in REQUIRES_NEW — its transaction already committed.\n        }\n    }\n\n    /**\n     * REQUIRES_NEW: always starts a fresh transaction.\n     * Suspends any calling transaction.\n     * Use for: audit logging, retry-safe operations, independent operations\n     * that should not roll back with the caller.\n     *\n     * WARNING: REQUIRES_NEW acquires a new connection from the pool.\n     * Nested REQUIRES_NEW calls under heavy load can exhaust the connection pool.\n     */\n    @Transactional(propagation = Propagation.REQUIRES_NEW)\n    public void processPaymentIndependently(Long orderId, BigDecimal amount) {\n        // Commits independently — caller's rollback does not affect this.\n    }\n\n    /**\n     * READ_COMMITTED isolation: prevents dirty reads (seeing uncommitted data\n     * from other transactions). Allows non-repeatable reads — the same query\n     * run twice in the same transaction can return different results.\n     *\n     * Use READ_COMMITTED for most read operations where perfect consistency\n     * is not required and throughput matters.\n     */\n    @Transactional(readOnly = true, isolation = Isolation.READ_COMMITTED)\n    public BigDecimal getAccountBalance(Long accountId) {\n        // readOnly=true: hint to JPA to skip dirty checking on entities\n        // — meaningful performance improvement in read-heavy paths.\n        // Does NOT prevent writes at the JDBC level — use for read-only methods.\n        return BigDecimal.ZERO; // In real code: accountRepository.findBalance(accountId)\n    }\n\n    /**\n     * NEVER: throws an exception if there IS an active transaction.\n     * MANDATORY: throws an exception if there is NO active transaction.\n     * SUPPORTS: joins existing transaction if present, runs non-transactionally if not.\n     * NOT_SUPPORTED: always runs non-transactionally, suspends existing transaction.\n     *\n     * These four are rare — document why you are using them when you do.\n     */\n    @Transactional(propagation = Propagation.MANDATORY)\n    public void mustRunInTransaction(Long orderId) {\n        // Throws IllegalTransactionStateException if called without an active transaction.\n        // Use when a method only makes sense inside a transaction boundary.\n    }\n}\n\n@Service\nclass AuditService {\n\n    /**\n     * REQUIRES_NEW: this method always runs in its own independent transaction.\n     * Even if the calling transaction (processPayment) rolls back,\n     * this audit log entry is committed.\n     */\n    @Transactional(propagation = Propagation.REQUIRES_NEW)\n    public void logPayment(Long orderId, BigDecimal amount, String status) {\n        // Persists audit record in its own committed transaction\n    }\n}",
        "output": "// Scenario: processPayment() throws exception after logPayment() runs\n//\n// Timeline:\n// T1: processPayment() starts transaction TX1\n// T2: auditService.logPayment() suspends TX1, starts TX2 (REQUIRES_NEW)\n// T3: logPayment() completes, TX2 commits audit record to DB\n// T4: TX1 resumes, exception thrown\n// T5: TX1 rolls back — payment debit, order status update rolled back\n// T6: TX2 already committed — audit log entry STAYS in the database\n//\n// Result: payment failed cleanly, but the audit trail shows what was attempted.\n// This is the correct behavior for financial systems."
      }

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 {\n\n    // Every 5 minutes: \"0 */5 * * * *\"\n    @Scheduled(cron = \"0 */5 * * * *\")\n    public void cleanupExpiredSessions() {\n        // runs on a single thread by default; use custom TaskScheduler for concurrency\n        System.out.println(\"Session cleanup at \" + System.currentTimeMillis());\n    }\n\n    // 8 AM every weekday: \"0 0 8 * * MON-FRI\"\n    @Scheduled(cron = \"0 0 8 * * MON-FRI\")\n    public void generateDailyReport() {\n        // generate and send report\n    }\n\n    // Fixed rate: start a new execution every 10 seconds (does not wait for completion)\n    @Scheduled(fixedRate = 10000)\n    public void checkHealth() {\n        // runs every 10 seconds, even if previous invocation is still running\n    }\n\n    // Fixed delay: wait 5 seconds after previous execution finishes\n    @Scheduled(fixedDelay = 5000, initialDelay = 1000)\n    public void processQueue() {\n        // runs 1 second after startup, then 5 seconds after each completion\n    }\n}",
        "output": "// Application startup log (with DEBUG level logging for scheduling):\n// Scheduled 'cleanupExpiredSessions' with cron '0 */5 * * * *'\n// Scheduled 'generateDailyReport' with cron '0 0 8 * * MON-FRI'\n// Scheduled 'checkHealth' with fixed rate 10000 ms\n// Scheduled 'processQueue' with fixed delay 5000 ms (initial delay 1000 ms)\n\n// Execution timeline:\n// t=0    : (application starts)\n// t=1s   : processQueue() runs (initialDelay)\n// t=10s  : checkHealth() runs\n// t=5min : cleanupExpiredSessions() runs\n// t=8am  : generateDailyReport() runs (if weekday)"
      }

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 {\n    @Lazy @Autowired private UserService self;\n    @Cacheable(\"users\")\n    public User getUser(Long id) { /* slow lookup */ }\n    public List<User> getUsers(List<Long> ids) {\n        return ids.stream().map(self::getUser).collect(Collectors.toList());\n    }\n}",
        "output": "// Problem 2 debugging steps:\n// 1. @Transactional on private method → move to public\n// 2. The method calls updateInventory directly (self-invocation) → extract to separate bean\n// 3. Default rollback only on RuntimeException → add rollbackFor = Exception.class\n//\n// Problem 5 key insight:\n// Using @Lazy @Autowired to inject the proxy into itself avoids self-invocation bypass.\n// This works because Spring creates the proxy first, then the lazy injection happens after.\n// Alternative: extract getUser() into a separate service bean."
      }