"Errors Without Checked Exceptions" — Failure Modelling, Annotations and Reflection

// Fragment of story/FileBackedRepository.kt
class FileBackedRepository(private val path: Path) {
    // Throws NoSuchFileException (an IOException) when the export is missing. Nothing in the signature says so.
    fun load(): List<String> = Files.readAllLines(path)

// Fragment of story/FileBackedRepository.kt
    // The same function, with the exception declared for Java's compiler.
    @Throws(IOException::class)
    fun loadChecked(): List<String> = Files.readAllLines(path)
}

fun main() {
    val repo = FileBackedRepository(Path.of("missing-export.csv"))
    try {
        repo.load()
    } catch (e: IOException) {
        println("Kotlin caught ${e::class.simpleName}") // -> Kotlin caught NoSuchFileException
    }
}

public final class PricingTeam {
    public static void main(String[] args) {
        FileBackedRepository repo = new FileBackedRepository(Path.of("missing-export.csv"));

        // try { repo.load(); } catch (IOException e) { }
        //   error: exception IOException is never thrown in body of corresponding try statement

        try {
            repo.loadChecked(); // @Throws puts 'throws IOException' in the bytecode, so javac allows the catch
        } catch (IOException e) {
            System.out.println("Java caught " + e.getClass().getSimpleName()); // -> Java caught NoSuchFileException
        }
    }
}

// javap -p -v FileBackedRepository (excerpt)
public final java.util.List<java.lang.String> load();
public final java.util.List<java.lang.String> loadChecked() throws java.io.IOException;
  Exceptions:
    throws java.io.IOException

import java.io.StringReader

// try is an expression: the value of the try block or of the catch block.
fun parsePaise(text: String): Long? =
    try {
        text.trim().toLong()
    } catch (e: NumberFormatException) {
        null
    }

class PriceList(private val prices: MutableMap<String, Long>) {
    var frozen = false

    fun priceOf(sku: String): Long {
        require(sku.startsWith("SHW-")) { "not a Shelfwise SKU: $sku" } // caller's fault: IllegalArgumentException
        return prices[sku] ?: error("no price for $sku") // error() throws IllegalStateException, type Nothing
    }

    fun update(sku: String, paise: Long) {
        check(!frozen) { "price list is frozen" } // object's state is wrong: IllegalStateException
        prices[sku] = paise
    }
}

// Runs a block and prints the exception it throws, if any.
fun attempt(block: () -> Unit) {
    try {
        block()
    } catch (e: RuntimeException) {
        println("${e::class.simpleName}: ${e.message}")
    }
}

fun main() {
    println(parsePaise(" 16500 ")) // -> 16500
    println(parsePaise("16,500")) // -> null

    val list = PriceList(mutableMapOf("SHW-1001" to 16_500))
    attempt { list.priceOf("1001") } // -> IllegalArgumentException: not a Shelfwise SKU: 1001
    attempt { list.priceOf("SHW-2040") } // -> IllegalStateException: no price for SHW-2040
    attempt { list.frozen = true; list.update("SHW-1001", 1) } // -> IllegalStateException: price list is frozen

    // requireNotNull throws IllegalArgumentException, not the NullPointerException of Objects.requireNonNull.
    val supplierCode: String? = null
    attempt { requireNotNull(supplierCode) { "supplier code missing" } } // -> IllegalArgumentException: supplier code missing

    // use: try-with-resources as an extension on Closeable/AutoCloseable.
    val lines = StringReader("SHW-1001,16500\nSHW-2040,72000").buffered().use { it.readLines() }
    println(lines.size) // -> 2
}

import java.io.IOException
import kotlin.coroutines.cancellation.CancellationException

fun supplierPrice(sku: String): Long = when (sku) {
    "SHW-1001" -> 15_900
    "SHW-9999" -> throw IOException("supplier timeout")
    else -> throw IllegalArgumentException("unknown SKU $sku")
}

fun main() {
    // runCatching turns an exception into a value: Result<T> is either Success or Failure.
    val ok = runCatching { supplierPrice("SHW-1001") }
    val timeout = runCatching { supplierPrice("SHW-9999") }
    println(ok) // -> Success(15900)
    println(timeout) // -> Failure(java.io.IOException: supplier timeout)

    println(ok.map { it / 100 }.getOrThrow()) // -> 159
    println(timeout.getOrElse { 0L }) // -> 0
    println(timeout.fold(onSuccess = { "price $it" }, onFailure = { "failed: ${it.message}" })) // -> failed: supplier timeout

    // Recover only what you expect. recoverCatching keeps a rethrown exception inside the Result;
    // plain recover would let it escape to the caller.
    val recovered = runCatching { supplierPrice("SHW-0000") }
        .recoverCatching { if (it is IOException) -1L else throw it }
    println(recovered.exceptionOrNull()?.message) // -> unknown SKU SHW-0000

    // The trap: runCatching catches Throwable. Cancellation and Errors become ordinary failures.
    println(runCatching { throw CancellationException("job cancelled") }.isFailure) // -> true
    println(runCatching { throw StackOverflowError() }.isFailure) // -> true

    // A narrow catch isn't automatically safe: CancellationException IS an IllegalStateException.
    try {
        throw CancellationException("job cancelled")
    } catch (e: IllegalStateException) {
        println("caught as IllegalStateException: ${e.message}") // -> caught as IllegalStateException: job cancelled
    }
}

// A generic outcome type. Nothing (Part 2) and 'out' (Part 8) make Ok and Err fit any Outcome<T, E>.
sealed interface Outcome<out T, out E> {
    data class Ok<out T>(val value: T) : Outcome<T, Nothing>
    data class Err<out E>(val error: E) : Outcome<Nothing, E>
}

// The errors a price lookup can produce, as a closed set the caller must handle.
sealed interface LookupError {
    data class UnknownSku(val sku: String) : LookupError
    data class Suspended(val sku: String, val reason: String) : LookupError
}

fun lookupPrice(sku: String): Outcome<Long, LookupError> = when (sku) {
    "SHW-1001" -> Outcome.Ok(16_500)
    "SHW-2040" -> Outcome.Err(LookupError.Suspended(sku, "supplier recall"))
    else -> Outcome.Err(LookupError.UnknownSku(sku))
}

fun shelfLabel(sku: String): String = when (val outcome = lookupPrice(sku)) {
    is Outcome.Ok -> "$sku ₹${outcome.value / 100}"
    is Outcome.Err -> when (val error = outcome.error) {
        is LookupError.UnknownSku -> "$sku NOT FOUND"
        is LookupError.Suspended -> "$sku UNAVAILABLE (${error.reason})"
    }
}

fun main() {
    listOf("SHW-1001", "SHW-2040", "SHW-0000").forEach { println(shelfLabel(it)) }
    // -> SHW-1001 ₹165
    // -> SHW-2040 UNAVAILABLE (supplier recall)
    // -> SHW-0000 NOT FOUND
}

// Experimental in 2.4.20 — requires -Xreturn-value-checker=check (set in this module's build.gradle.kts).
// Every function in a @MustUseReturnValues class must have its result used.
@MustUseReturnValues
class PriceCalculator {
    fun discounted(pricePaise: Long, percent: Int): Long = pricePaise * (100 - percent) / 100

    // Opt a function back out: callers may ignore the result.
    @IgnorableReturnValue
    fun record(pricePaise: Long): Boolean = pricePaise > 0
}

fun main() {
    val calculator = PriceCalculator()
    var price = 16_500L
    calculator.discounted(price, 10) // warning: unused return value of 'discounted'.
    println(price) // -> 16500

    price = calculator.discounted(price, 10)
    println(price) // -> 14850

    calculator.record(price) // fine: @IgnorableReturnValue
    val _ = calculator.discounted(price, 5) // an explicit "I mean to ignore this"
}

// Shaped like a Bean Validation annotation: it may target parameters, fields and getters, but not Kotlin properties.
@Target(AnnotationTarget.VALUE_PARAMETER, AnnotationTarget.FIELD, AnnotationTarget.PROPERTY_GETTER)
@Retention(AnnotationRetention.RUNTIME)
annotation class MinPaise(val value: Long)

class PriceUpdate(
    @MinPaise(100) val defaulted: Long, // 2.4.0 default: the parameter, and the field
    @field:MinPaise(100) val onField: Long, // only the field
    @get:MinPaise(100) val onGetter: Long, // only the getter
    @all:MinPaise(100) val everywhere: Long, // @all (Stable since 2.4.0): parameter, field and getter
)

fun main() {
    val type = PriceUpdate::class.java
    val names = listOf("defaulted", "onField", "onGetter", "everywhere")
    val parameters = type.constructors.single().parameters
    for ((index, name) in names.withIndex()) {
        val getter = "get" + name.replaceFirstChar { it.uppercase() }
        val places = buildList {
            if (parameters[index].isAnnotationPresent(MinPaise::class.java)) add("parameter")
            if (type.getDeclaredField(name).isAnnotationPresent(MinPaise::class.java)) add("field")
            if (type.getMethod(getter).isAnnotationPresent(MinPaise::class.java)) add("getter")
        }
        println("$name: $places")
    }
    // -> defaulted: [parameter, field]
    // -> onField: [field]
    // -> onGetter: [getter]
    // -> everywhere: [parameter, field, getter]
}

import kotlin.reflect.KProperty1
import kotlin.reflect.full.memberProperties

data class Product(val sku: String, val name: String, val pricePaise: Long)

fun main() {
    val product = Product("SHW-1001", "Toor Dal 1kg", 16_500)

    // Without kotlin-reflect: class references, names, and property references you can call.
    val type = Product::class
    println(type.simpleName) // -> Product
    println(type.java.name) // -> com.shelfwise.part09.reflection.Product
    val nameProperty: KProperty1<Product, String> = Product::name
    println("${nameProperty.name} = ${nameProperty.get(product)}") // -> name = Toor Dal 1kg

    // With kotlin-reflect on the classpath: full introspection of Kotlin declarations.
    val properties = type.memberProperties.sortedBy { it.name }.map { "${it.name}: ${it.returnType}" }
    println(properties) // -> [name: kotlin.String, pricePaise: kotlin.Long, sku: kotlin.String]
    println(type.isData) // -> true
}

// Fragment of importer/PriceImport.kt
// Step 1: what a supplier line can become. Expected problems are data, not exceptions.
data class PriceUpdate(val sku: String, val newPaise: Long)

sealed interface Rejection {
    val line: Int

    data class Malformed(override val line: Int, val text: String) : Rejection
    data class UnknownSku(override val line: Int, val sku: String) : Rejection
    data class PriceJump(override val line: Int, val sku: String, val fromPaise: Long, val toPaise: Long) : Rejection
}

// Fragment of importer/PriceImport.kt
// Step 2: validation is a pure function that returns an Outcome (from domain/DomainErrors.kt).
fun validate(line: Int, text: String, current: Map<String, Long>): Outcome<PriceUpdate, Rejection> {
    val parts = text.split(",")
    val paise = parts.getOrNull(1)?.trim()?.toLongOrNull()
    if (parts.size != 2 || paise == null) return Outcome.Err(Rejection.Malformed(line, text))
    val sku = parts[0].trim()
    val old = current[sku] ?: return Outcome.Err(Rejection.UnknownSku(line, sku))
    if (paise > old * 3 / 2) return Outcome.Err(Rejection.PriceJump(line, sku, old, paise))
    return Outcome.Ok(PriceUpdate(sku, paise))
}

data class ImportReport(val accepted: List<PriceUpdate>, val rejected: List<Rejection>)

// Fragment of importer/PriceImport.kt
// Step 3: reading stays exception-based: an I/O failure is not a property of one line.
// @Throws tells Java callers (and javac) about it.
@Throws(IOException::class)
fun importPrices(source: Reader, current: Map<String, Long>): ImportReport {
    val accepted = mutableListOf<PriceUpdate>()
    val rejected = mutableListOf<Rejection>()
    source.buffered().useLines { lines ->
        lines.forEachIndexed { index, text ->
            when (val outcome = validate(index + 1, text, current)) {
                is Outcome.Ok -> accepted += outcome.value
                is Outcome.Err -> rejected += outcome.error
            }
        }
    }
    return ImportReport(accepted, rejected)
}

// Fragment of importer/PriceImport.kt
// Step 4: a boundary that turns I/O failures into a Result, and lets everything else through:
// cancellation, Errors and bugs keep propagating, unlike with runCatching.
inline fun <T> catchingIo(block: () -> T): Result<T> =
    try {
        Result.success(block())
    } catch (e: IOException) {
        Result.failure(e)
    }

fun describe(rejection: Rejection): String = when (rejection) {
    is Rejection.Malformed -> "line ${rejection.line}: can't read '${rejection.text}'"
    is Rejection.UnknownSku -> "line ${rejection.line}: unknown SKU ${rejection.sku}"
    is Rejection.PriceJump -> "line ${rejection.line}: ${rejection.sku} jumps ${rejection.fromPaise} -> ${rejection.toPaise}, needs review"
}

// Fragment of importer/PriceImport.kt
// Step 5: run it on a good file and a broken connection.
fun main() {
    val current = mapOf("SHW-1001" to 16_500L, "SHW-2040" to 72_000L)
    val supplierFile = "SHW-1001,15900\nSHW-2040,180000\nSHW-7777,500\nnot a price line"

    val report = importPrices(StringReader(supplierFile), current) // a StringReader can't fail
    println(report.accepted) // -> [PriceUpdate(sku=SHW-1001, newPaise=15900)]
    report.rejected.forEach { println(describe(it)) }
    // -> line 2: SHW-2040 jumps 72000 -> 180000, needs review
    // -> line 3: unknown SKU SHW-7777
    // -> line 4: can't read 'not a price line'

    val brokenConnection = object : Reader() {
        override fun read(buffer: CharArray, offset: Int, length: Int): Int = throw IOException("connection reset")

        override fun close() {}
    }
    val failed = catchingIo { importPrices(brokenConnection, current) }
    println("import failed: ${failed.exceptionOrNull()?.message}") // -> import failed: connection reset
}

import java.io.IOException
import java.lang.reflect.InvocationTargetException
import java.lang.reflect.Proxy
import java.lang.reflect.UndeclaredThrowableException

interface PriceSource {
    fun load(): List<String> // no @Throws: Java sees no 'throws IOException'
}

interface CheckedPriceSource {
    @Throws(IOException::class)
    fun load(): List<String> // Java implementations may declare 'throws IOException'
}

class SupplierFeed : PriceSource {
    override fun load(): List<String> = throw IOException("feed offline")
}

fun main() {
    // A JDK dynamic proxy (what Spring AOP uses for interfaces) may only rethrow exceptions
    // the interface method declares. An undeclared checked exception gets wrapped.
    val target = SupplierFeed()
    val proxy = Proxy.newProxyInstance(PriceSource::class.java.classLoader, arrayOf(PriceSource::class.java)) { _, method, args ->
        try {
            method.invoke(target, *(args ?: emptyArray()))
        } catch (e: InvocationTargetException) {
            throw e.targetException
        }
    } as PriceSource
    try {
        proxy.load()
    } catch (e: UndeclaredThrowableException) {
        println("${e::class.simpleName} caused by ${e.cause}") // -> UndeclaredThrowableException caused by java.io.IOException: feed offline
    }

    // A Java class implements CheckedPriceSource with 'throws IOException' (see JavaFeed.java).
    try {
        com.shelfwise.part09.javacaller.JavaFeed().load()
    } catch (e: IOException) {
        println("Java implementation threw: ${e.message}") // -> Java implementation threw: export locked
    }
}

// Implementing a Kotlin interface from Java. Against PriceSource (no @Throws), this fails:
//   error: load() in JavaFeed cannot implement load() in PriceSource
//     overridden method does not throw IOException
public final class JavaFeed implements CheckedPriceSource {
    @Override
    public List<String> load() throws IOException {
        throw new IOException("export locked");
    }
}