"The Catalog" — Spring Boot 4.1, JPA and REST in Kotlin

// Fragment of story/DataClassEntities.kt (test sources)
// Kabir's first attempt: entities as data classes, the way he'd model a DTO.
@Entity
@Table(name = "naive_suppliers")
data class NaiveSupplier(
    @Id @GeneratedValue var id: Long? = null,
    val code: String,
    @OneToMany(mappedBy = "supplier") val products: MutableList<NaiveProduct> = mutableListOf(),
)

@Entity
@Table(name = "naive_products")
data class NaiveProduct(
    @Id @GeneratedValue var id: Long? = null,
    val sku: String,
    var pricePaise: Long,
    @ManyToOne(fetch = FetchType.LAZY) val supplier: NaiveSupplier,
)

// Fragment of product/Product.kt
enum class Category { PASTA_AND_GRAINS, DAIRY, BEVERAGES, SNACKS, BREAKFAST, PERSONAL_CARE, SMALL_APPLIANCES }

// A plain class, not a data class: an entity has an identity, a lifecycle and lazy associations.
// plugin.jpa makes it open (for Hibernate's proxies) and gives it a no-arg constructor.
@Entity
@Table(name = "products")
class Product(
    @Column(nullable = false, unique = true, updatable = false)
    val sku: String,
    var name: String,
    var description: String,
    @Enumerated(EnumType.STRING)
    var category: Category,
    var pricePaise: Long,
    @ManyToOne(fetch = FetchType.LAZY, optional = false)
    @JoinColumn(name = "supplier_id")
    var supplier: Supplier,
    @ElementCollection
    @CollectionTable(name = "product_dietary_tags")
    @Column(name = "tag")
    var dietaryTags: MutableSet<String> = mutableSetOf(),
    val createdAt: Instant,
) {
    @Id
    @GeneratedValue
    @UuidGenerator(style = UuidGenerator.Style.VERSION_7)
    var id: UUID? = null
        protected set // assigned by Hibernate on persist; nobody else should write it

    @Version
    var version: Long = 0
        protected set

    override fun equals(other: Any?) = this === other || (other is Product && sku == other.sku)

    override fun hashCode() = sku.hashCode()

    // Never touch lazy associations here: toString runs in log lines, debuggers and test failures.
    override fun toString() = "Product(sku=$sku, name=$name)"
}

// javap -p com.shelfwise.catalog.product.Product, trimmed
public class Product {                                  // not final: all-open's JPA preset (Kotlin 2.3.20+)
  private final String sku;
  private UUID id;
  public String getSku();                               // not final either, so the proxy can intercept it
  public UUID getId();
  protected void setId(UUID);                           // protected set
  public Product(String, String, String, Category, long, Supplier, Set<String>, Instant);
  public Product();                                     // no-arg: hidden from Kotlin, used by Hibernate
}

// Fragment of product/Repositories.kt
interface ProductRepository : JpaRepository<Product, UUID> {
    // A nullable return type is enough: Spring Data returns null instead of throwing or wrapping in Optional.
    @EntityGraph(attributePaths = ["supplier", "dietaryTags"])
    fun findBySku(sku: String): Product?

    @EntityGraph(attributePaths = ["supplier", "dietaryTags"])
    fun findByCategoryAndPricePaiseLessThanEqualOrderByPricePaise(category: Category, maxPricePaise: Long): List<Product>

    fun existsBySku(sku: String): Boolean
}

interface SupplierRepository : JpaRepository<Supplier, UUID> {
    fun findByCode(code: String): Supplier?
}

// Fragment of product/ProductService.kt
@Service
@Transactional(readOnly = true)
class ProductService(
    private val products: ProductRepository,
    private val suppliers: SupplierRepository,
    private val clock: Clock,
) {
    fun bySku(sku: String): Product = products.findBySku(sku) ?: throw ProductNotFound(sku)

    fun search(category: Category, maxPricePaise: Long): List<Product> =
        products.findByCategoryAndPricePaiseLessThanEqualOrderByPricePaise(category, maxPricePaise)

    @Transactional
    fun create(new: NewProduct): Product {
        if (products.existsBySku(new.sku)) throw DuplicateSku(new.sku)
        val supplier = suppliers.findByCode(new.supplierCode) ?: throw UnknownSupplier(new.supplierCode)
        return products.save(
            Product(
                sku = new.sku,
                name = new.name,
                description = new.description,
                category = new.category,
                pricePaise = new.pricePaise,
                supplier = supplier,
                dietaryTags = new.dietaryTags.toMutableSet(),
                createdAt = clock.instant(),
            ),
        )
    }

    @Transactional
    fun reprice(sku: String, pricePaise: Long): Product = bySku(sku).apply { this.pricePaise = pricePaise }

    // Applies a supplier's "SKU,pricePaise" price list. If reading fails halfway with an IOException, a
    // checked exception, the lines already applied must be undone: RollbackOn.ALL_EXCEPTIONS makes it so.
    @Transactional
    fun importPriceList(priceList: Reader): Int = priceList.buffered().useLines { lines ->
        lines.map { it.split(',') }.onEach { (sku, paise) -> reprice(sku.trim(), paise.trim().toLong()) }.count()
    }
}

import org.springframework.beans.factory.BeanRegistrarDsl
import org.springframework.context.annotation.Configuration
import org.springframework.context.annotation.Import
import org.springframework.transaction.annotation.EnableTransactionManagement
import org.springframework.transaction.annotation.RollbackOn
import java.time.Clock

// Spring rolls back on unchecked exceptions only. Kotlin has no checked exceptions, so a Kotlin
// function can throw IOException without anyone noticing, and the transaction would commit (Part 9).
@Configuration(proxyBeanMethods = false)
@EnableTransactionManagement(rollbackOn = RollbackOn.ALL_EXCEPTIONS)
@Import(CatalogBeans::class)
class CatalogConfiguration

// Programmatic bean registration with Spring Framework 7's Kotlin DSL.
class CatalogBeans : BeanRegistrarDsl({
    registerBean<Clock> { Clock.systemUTC() }
})

// Fragment of web/ProductDtos.kt
// Constraint annotations without a use-site target: under Kotlin 2.4's defaults they land on the
// constructor parameter and the field, and Bean Validation reads the field (Part 9).
data class CreateProductRequest(
    @Pattern(regexp = "SHW-\\d{4}", message = "must look like SHW-1234")
    val sku: String,
    @NotBlank @Size(max = 200)
    val name: String,
    val description: String = "",
    val category: Category,
    @Positive
    val pricePaise: Long,
    @NotBlank
    val supplierCode: String,
    val dietaryTags: Set<String> = emptySet(),
)

data class RepriceRequest(
    @Positive val pricePaise: Long,
)

data class ProductResponse(
    val sku: String,
    val name: String,
    val description: String,
    val category: Category,
    val pricePaise: Long,
    val price: String,
    val supplier: String,
    val dietaryTags: List<String>,
)

// Mapping as extension functions: the entity knows nothing about the web layer, and no mapper library.
fun CreateProductRequest.toNewProduct() =
    NewProduct(sku, name.trim(), description, category, pricePaise, supplierCode, dietaryTags)

fun Product.toResponse() = ProductResponse(
    sku = sku,
    name = name,
    description = description,
    category = category,
    pricePaise = pricePaise,
    price = "₹%d.%02d".format(pricePaise / 100, pricePaise % 100),
    supplier = supplier.name,
    dietaryTags = dietaryTags.sorted(),
)

// Fragment of web/ProductController.kt
    // A nullable parameter is an optional request parameter: Spring reads Kotlin's nullability.
    @GetMapping
    fun search(@RequestParam category: Category, @RequestParam maxPricePaise: Long?): List<ProductResponse> =
        catalog.search(category, maxPricePaise ?: Long.MAX_VALUE).map { it.toResponse() }

    @PostMapping
    fun create(@Valid @RequestBody request: CreateProductRequest): ResponseEntity<ProductResponse> {
        val product = catalog.create(request.toNewProduct())
        return ResponseEntity.created(URI.create("/api/products/${product.sku}")).body(product.toResponse())
    }

// Fragment of web/ProblemHandling.kt

// RFC 9457 problem details for every error. The base class already covers Spring MVC's own exceptions
// (unreadable JSON, missing parameters, wrong types); this adds the catalog's and the field errors.
@RestControllerAdvice
class ProblemHandling : ResponseEntityExceptionHandler() {
    @ExceptionHandler
    fun catalogFailure(e: CatalogException): ProblemDetail = when (e) { // exhaustive: no else branch
        is ProductNotFound -> problem(HttpStatus.NOT_FOUND, "Product not found", e).apply { setProperty("sku", e.sku) }
        is DuplicateSku -> problem(HttpStatus.CONFLICT, "Duplicate SKU", e).apply { setProperty("sku", e.sku) }
        is UnknownSupplier -> problem(HttpStatus.BAD_REQUEST, "Unknown supplier", e).apply { setProperty("supplierCode", e.code) }
    }

    // Two requests changed the same product; @Version detected it, and the later one loses.
    @ExceptionHandler
    fun concurrentUpdate(e: ObjectOptimisticLockingFailureException): ProblemDetail =
        problem(HttpStatus.CONFLICT, "Concurrent update", e).apply { detail = "The product changed while this request ran; retry it." }

    // A database constraint caught what the code didn't, such as two concurrent creates of one SKU.
    @ExceptionHandler
    fun constraintViolation(e: DataIntegrityViolationException): ProblemDetail =
        ProblemDetail.forStatusAndDetail(HttpStatus.CONFLICT, "The change conflicts with existing data.").apply {
            title = "Constraint violated" // no SQL in the response
        }

    override fun handleMethodArgumentNotValid(
        ex: MethodArgumentNotValidException,
        headers: HttpHeaders,
        status: HttpStatusCode,
        request: WebRequest,
    ): ResponseEntity<Any>? {
        val body = ex.body.apply {
            setProperty("errors", ex.bindingResult.fieldErrors.associate { it.field to it.defaultMessage })
        }
        return handleExceptionInternal(ex, body, headers, status, request)
    }

    private fun problem(status: HttpStatus, title: String, e: Exception) =
        ProblemDetail.forStatusAndDetail(status, e.message).apply { this.title = title }
}

import org.junit.jupiter.api.Test
import tools.jackson.databind.DatabindException
import tools.jackson.module.kotlin.jacksonObjectMapper
import tools.jackson.module.kotlin.readValue
import kotlin.test.assertEquals
import kotlin.test.assertFailsWith
import kotlin.test.assertTrue

// Part 4's promise: what happens to a validating value class when a framework builds it.
@JvmInline
value class Sku(val value: String) {
    init {
        require(value.matches(Regex("SHW-\\d{4}"))) { "bad SKU: $value" }
    }
}

data class SkuRequest(val sku: Sku)

class ValueClassBoundaryTest {
    @Test
    fun `jackson-module-kotlin runs init`() {
        val mapper = jacksonObjectMapper()

        assertEquals(Sku("SHW-1001"), mapper.readValue<SkuRequest>("""{"sku":"SHW-1001"}""").sku)
        val failure = assertFailsWith<DatabindException> { mapper.readValue<SkuRequest>("""{"sku":"not a sku"}""") }
        assertTrue(failure.message!!.startsWith("bad SKU: not a sku"))
    }

    @Test
    fun `plain reflection through box-impl does not`() {
        // box-impl wraps an already-validated value; frameworks that find it by reflection skip init.
        val boxImpl = Sku::class.java.getDeclaredMethod("box-impl", String::class.java)

        val sku = boxImpl.invoke(null, "not a sku") as Sku

        assertEquals("not a sku", sku.value)
    }

    @Test
    fun `neither does the private JVM constructor`() {
        // init lives only in the static constructor-impl; the JVM constructor just stores the value.
        val constructor = Sku::class.java.getDeclaredConstructor(String::class.java).apply { isAccessible = true }

        assertEquals("nope", constructor.newInstance("nope").value)
    }
}

// Fragment of build-logic/src/main/kotlin/kfs.spring-service.gradle.kts
// Convention: a Spring Boot 4.1 service in Kotlin. It is what start.spring.io generates for Kotlin,
// minus what Kotlin 2.4.20 made redundant. Plugin versions come from build-logic's dependencies.
import org.gradle.api.artifacts.VersionCatalogsExtension

plugins {
    id("org.jetbrains.kotlin.jvm")
    id("org.jetbrains.kotlin.plugin.spring")
    id("org.springframework.boot")
    id("io.spring.dependency-management")
}

val libs = the<VersionCatalogsExtension>().named("libs")

// Boot 4.1.1's BOM manages Kotlin 2.3.21, but the Boot plugin aligns its kotlin.version with the Kotlin
// plugin applied (2.4.20) and adds -java-parameters. kotlinx.coroutines gets no such help: the BOM pins
// 1.10.2, so the property moves it to the version the series uses.
extra["kotlin-coroutines.version"] = libs.findVersion("kotlinx-coroutines").get().requiredVersion

kotlin {
    jvmToolchain(libs.findVersion("jdk").get().requiredVersion.toInt())
}

import org.springframework.boot.test.context.TestConfiguration
import org.springframework.boot.testcontainers.service.connection.ServiceConnection
import org.springframework.context.annotation.Bean
import org.testcontainers.postgresql.PostgreSQLContainer

// One PostgreSQL container for the test context. @ServiceConnection hands its URL and credentials
// to Spring Boot, so there are no datasource properties to keep in sync.
@TestConfiguration(proxyBeanMethods = false)
class TestcontainersConfiguration {
    @Bean
    @ServiceConnection
    fun postgres() = PostgreSQLContainer("postgres:18-alpine")
}

// Fragment of ProductApiTest.kt
    @Test
    fun `a missing non-null property is a 400, not a null in the object`() {
        client.post().uri("/api/products").contentType(MediaType.APPLICATION_JSON)
            .body("""{"sku":"SHW-1102","name":"Masala Oats","pricePaise":9000,"supplierCode":"SUP-002"}""")
            .exchange()
            .expectStatus().isBadRequest
            .expectBody()
            .jsonPath("$.detail").isEqualTo("Failed to read request")
    }

// Fragment of ProductApiTest.kt
    @Test
    fun `requests run on virtual threads`() {
        client.get().uri("/test/thread").exchange()
            .expectStatus().isOk
            .expectBody<String>().isEqualTo("virtual=true")
    }

    @RestController
    class ThreadProbe {
        @GetMapping("/test/thread")
        fun thread() = "virtual=${Thread.currentThread().isVirtual}"
    }

// Fragment of story/DataClassEntityTest.kt
    @Test
    fun `toString walks the bidirectional association until the stack runs out`() {
        val product = em.find(NaiveProduct::class.java, saveOne())

        // product -> supplier (initialised by the proxy) -> products -> product -> ...
        val failure = assertFailsWith<StackOverflowError> { product.toString() }
        assertTrue(failure.stackTrace.size > 1_000) // thousands of toString frames
    }

    @Test
    @Transactional(propagation = Propagation.NOT_SUPPORTED)
    fun `outside the transaction, toString touches a proxy with no session`() {
        val tx = TransactionTemplate(transactions)
        val id = tx.execute { saveOne() } // Spring 7 (JSpecify): a non-null T for a non-null lambda, no !!
        val product = tx.execute { em.find(NaiveProduct::class.java, id) }!! // Jakarta API: a platform type, so !! here

        val failure = assertFailsWith<LazyInitializationException> { product.toString() }
        assertTrue(failure.message!!.startsWith("Could not initialize proxy [com.shelfwise.story.NaiveSupplier#"))
        assertTrue(failure.message!!.endsWith("] - no session"))
    }

    @Test
    fun `hashCode changes when the id is assigned`() {
        val supplier = NaiveSupplier(code = "SUP-002")
        em.persist(supplier)
        val product = NaiveProduct(sku = "SHW-2002", pricePaise = 9_000, supplier = supplier)
        val inCart = hashSetOf(product)

        em.persist(product) // assigns id, which is part of equals and hashCode

        assertFalse(product in inCart)
    }

// Fragment of story/DataClassEntities.kt
// Not a data class, and still a trap: Hibernate creates entities through the no-arg constructor,
// which doesn't run property initialisers unless noArg { invokeInitializers = true }.
@Entity
@Table(name = "naive_labels")
class ShelfLabel(
    @Id val sku: String,
    var text: String,
) {
    @Transient
    val printedBy: String = "label-service" // not a column, so nothing fills it in after loading
}