client/io.github.octaviusframework.client.transaction

Package-level declarations

Types

SpreadParameters

class SpreadParameters(val source: TransactionValue<*>)

A value marked by spread. Not a TransactionValue, so map cannot follow spread().

StepBuilder

class StepBuilder @PublishedApi constructor(val query: RunnableQuery<*>)

Turns a query into a TransactionPlan step instead of running it; returned by RunnableQuery.asStep.

StepHandle

class StepHandle<out T>(position: Int)

Names a step of a TransactionPlan, so that later steps can refer to what it will produce. Returned by TransactionPlan.add and compared by identity alone.

TransactionDefinition

data class TransactionDefinition(val propagation: TransactionPropagation = TransactionPropagation.REQUIRED, val isolation: TransactionIsolationLevel? = null, val readOnly: Boolean = false, val statementTimeout: Duration? = null, val transactionTimeout: Duration? = null)

How a transaction should be run, as a SessionProvider is handed it.

TransactionPlan

class TransactionPlan

Operations to run as one transaction, assembled before any of it runs - for a sequence decided in one place and run in another. Where the sequence is written out where it runs, a transaction { } block is simpler.

TransactionPlanResult

class TransactionPlanResult(results: Map<StepHandle<*>, Any?>, val size: Int)

What a TransactionPlan produced: every step's result, referred to or not.

TransactionPropagation

enum TransactionPropagation : Enum<TransactionPropagation>

What a transaction does when it is started inside one that is already running.

TransactionStep

class TransactionStep<T> @PublishedApi constructor(val query: RunnableQuery<*>, val params: Map<String, Any?>, val run: (Map<String, Any?>) -> T)

One operation of a TransactionPlan, built by StepBuilder but not yet run: the query, its parameters as written, and the terminal to call once they are resolved.

TransactionValue

sealed class TransactionValue<out T>

A parameter of a TransactionPlan step whose value may not exist until an earlier step runs - the id an earlier insert generates. It is resolved when the step runs; anything else in a parameter map is passed through as it is.

Functions

describePlan

internal fun describePlan(entries: List<TransactionPlan.PlannedStep>): String

What a plan will do, as text: one block per step with its index, its SQL, and where each parameter comes from.

describeValue

internal fun describeValue(value: TransactionValue<*>, stepIndices: Map<StepHandle<*>, Int>? = null): String

Renders a value as the chain that will produce it, source first, never with a literal's value. A handle is rendered by its place in stepIndices where given; its own toString has the index it was created at, which after TransactionPlan.addPlan may not be where its step sits.

map

fun <IN, OUT> TransactionValue<IN>.map(transformation: (IN) -> OUT): TransactionValue<OUT>

Applies transformation to this value once it resolves, so a row becomes the column the next step needs without a step of its own:

resolveParams

internal fun resolveParams(raw: Map<String, Any?>, results: Map<StepHandle<*>, Any?>, stepIndex: Int, stepIndices: Map<StepHandle<*>, Int>): Map<String, Any?>

Replaces the unresolved values in a step's parameters with what the earlier steps produced. A SpreadParameters contributes its entries under their own names, so the result can be longer than raw. Every failure names the step, since a plan built in a loop has the same SQL and parameters in every step.

spread

fun TransactionValue<Map<String, Any?>>.spread(): SpreadParameters

Spreads this map into parameters under its own keys. The name it was filed under is only a placeholder and is not bound.

toTransactionValue

fun <T> T.toTransactionValue(): TransactionValue.Value<T>

Wraps a known value as a TransactionValue, for a function that takes either a value already there or one an earlier step will produce. A parameter map needs no wrapping.

validatePlan

internal fun validatePlan(steps: List<TransactionPlan.PlannedStep>): Map<StepHandle<*>, Int>

Checks a plan before a transaction is opened, so a malformed one fails before any step has done its work: a query that cannot render, and a handle naming no step ahead of it in this plan. The second can only come from another plan - its handle, merged in the wrong order or not at all.