Oracle Lock-Free Reservation with Micronaut Data JDBC

package example.micronaut.domain

import io.micronaut.data.annotation.GeneratedValue
import io.micronaut.data.annotation.Id
import io.micronaut.data.annotation.MappedEntity
import io.micronaut.data.annotation.Reservable
import io.micronaut.serde.annotation.Serdeable
import jakarta.validation.constraints.NotBlank
import jakarta.validation.constraints.PositiveOrZero

@Serdeable // 
@MappedEntity("ACCOUNT") // 
data class Account(
    @field:Id @field:GeneratedValue val id: Long? = null, // 
    @field:NotBlank val name: String, // 
    @field:Reservable @field:PositiveOrZero val balance: Long // 
)

package example.micronaut

import example.micronaut.domain.Account
import io.micronaut.data.annotation.Id
import io.micronaut.data.jdbc.annotation.JdbcRepository
import io.micronaut.data.model.query.builder.sql.Dialect
import io.micronaut.data.repository.CrudRepository

@JdbcRepository(dialect = Dialect.ORACLE) // 
interface AccountRepository : CrudRepository<Account, Long> { // 

    /**
     *
     * @param id Account unique identifier
     * @param balance balance increment
     * @return rows updated
     */
    fun reserveIncrementBalance(@Id id: Long, balance: Long): Long // 

    /**
     *
     * @param id Account unique identifier
     * @param balance balance decrement
     * @return rows updated
     */
    fun reserveDecrementBalance(@Id id: Long, balance: Long): Long // 
}

package example.micronaut

import example.micronaut.domain.Account
import io.micronaut.http.HttpStatus
import io.micronaut.http.annotation.Body
import io.micronaut.http.annotation.Controller
import io.micronaut.http.annotation.Get
import io.micronaut.http.annotation.Post
import io.micronaut.http.annotation.QueryValue
import io.micronaut.http.annotation.Status
import io.micronaut.http.exceptions.HttpStatusException
import io.micronaut.scheduling.TaskExecutors
import io.micronaut.scheduling.annotation.ExecuteOn

@ExecuteOn(TaskExecutors.BLOCKING) // 
@Controller("/accounts") // 
class AccountController(private val repository: AccountRepository) { // 

    @Post
    @Status(HttpStatus.CREATED)
    fun create(@Body account: Account): Account = repository.save(account)

    @Get
    fun findAll(): List<Account> = repository.findAll()

    @Post("/{id}/deposit")
    fun deposit(id: Long, @QueryValue amount: Long): Account {
        if (repository.reserveIncrementBalance(id, amount) == 0L) { // 
            throw HttpStatusException(HttpStatus.NOT_FOUND, "Account not found")
        }
        return repository.findById(id).orElseThrow() // 
    }

    @Post("/{id}/withdraw")
    fun withdraw(id: Long, @QueryValue amount: Long): Account {
        if (repository.reserveDecrementBalance(id, amount) == 0L) {
            throw HttpStatusException(HttpStatus.NOT_FOUND, "Account not found")
        }
        return repository.findById(id).orElseThrow()
    }
}

package example.micronaut

import io.micronaut.data.exceptions.DataIntegrityViolationException
import io.micronaut.http.HttpRequest
import io.micronaut.http.HttpResponse
import io.micronaut.http.HttpStatus
import io.micronaut.http.annotation.Produces
import io.micronaut.http.server.exceptions.ExceptionHandler
import io.micronaut.http.server.exceptions.response.ErrorContext
import io.micronaut.http.server.exceptions.response.ErrorResponseProcessor
import jakarta.inject.Singleton

@Produces
@Singleton
class ReservationExceptionHandler(
    private val errorResponseProcessor: ErrorResponseProcessor<*>
) : ExceptionHandler<DataIntegrityViolationException, HttpResponse<*>> { // 

    override fun handle(request: HttpRequest<*>, exception: DataIntegrityViolationException): HttpResponse<*> {
        val errorContext = ErrorContext.builder(request)
            .cause(exception)
            .errorMessage("The operation violates an account constraint") // 
            .build()
        return errorResponseProcessor.processResponse(errorContext, HttpResponse.status<Any>(HttpStatus.CONFLICT)) // 
    }
}

package example.micronaut

import example.micronaut.domain.Account
import io.micronaut.data.exceptions.DataIntegrityViolationException
import io.micronaut.http.HttpRequest
import io.micronaut.http.HttpStatus
import io.micronaut.http.client.HttpClient
import io.micronaut.http.client.annotation.Client
import io.micronaut.http.client.exceptions.HttpClientResponseException
import io.micronaut.test.extensions.junit5.annotation.MicronautTest
import jakarta.inject.Inject
import org.junit.jupiter.api.Assertions.assertEquals
import org.junit.jupiter.api.Assertions.assertThrows
import org.junit.jupiter.api.Assertions.assertTrue
import org.junit.jupiter.api.Test

@MicronautTest(transactional = false) // 
class AccountTest {

    @Inject
    lateinit var repository: AccountRepository

    @Inject
    @field:Client("/")
    lateinit var httpClient: HttpClient

    @Test
    fun depositIncrementsBalance() {
        val account = repository.save(Account(name = "Checking", balance = 100))

        val updated = repository.reserveIncrementBalance(account.id!!, 25) // 

        assertEquals(1L, updated)
        val found = repository.findById(account.id!!).orElseThrow()
        assertEquals(125L, found.balance)
    }

    @Test
    fun withdrawalBeyondBalanceIsRejected() {
        val account = repository.save(Account(name = "Checking", balance = 100))

        assertThrows(DataIntegrityViolationException::class.java) {
            repository.reserveDecrementBalance(account.id!!, 1000) // 
        }

        val found = repository.findById(account.id!!).orElseThrow()
        assertEquals(100L, found.balance) // 
    }

    @Test
    fun withdrawalBeyondBalanceRespondsWithConflict() {
        val account = repository.save(Account(name = "Checking", balance = 100))

        val e = assertThrows(HttpClientResponseException::class.java) {
            httpClient.toBlocking().exchange<Any, Any>(
                HttpRequest.POST("/accounts/${account.id}/withdraw?amount=1000", ""))
        }

        assertEquals(HttpStatus.CONFLICT, e.status) // 
        assertTrue(e.response.getBody(String::class.java).orElse("")
            .contains("The operation violates an account constraint")) // 
    }

    @Test
    fun accountIsCreatedDepositedAndWithdrawnOverHttp() {
        val client = httpClient.toBlocking()

        val created = client.exchange(
            HttpRequest.POST("/accounts", Account(name = "Savings", balance = 100)), Account::class.java) // 
        assertEquals(HttpStatus.CREATED, created.status)
        val account = created.body()!!

        val deposited = client.retrieve(
            HttpRequest.POST("/accounts/${account.id}/deposit?amount=25", ""), Account::class.java) // 
        assertEquals(125L, deposited.balance)

        val withdrawn = client.retrieve(
            HttpRequest.POST("/accounts/${account.id}/withdraw?amount=50", ""), Account::class.java)
        assertEquals(75L, withdrawn.balance)
    }

    @Test
    fun depositForUnknownAccountRespondsWithNotFound() {
        val e = assertThrows(HttpClientResponseException::class.java) {
            httpClient.toBlocking().exchange<Any, Any>(
                HttpRequest.POST("/accounts/-1/deposit?amount=1", ""))
        }

        assertEquals(HttpStatus.NOT_FOUND, e.status) // 
    }
}