client/io.github.octaviusframework.client.query/RunnableQuery

RunnableQuery

abstract class RunnableQuery<T : RunnableQuery<T>> @PublishedApi constructor(val queryProvider: SessionProvider)

Something that knows how to produce a query, and can therefore be run.

This is where the terminal methods live, written once for everything that can be run. Every builder the client offers extends it, and so does a hand-written RawQuery; a subclass supplies the SQL and inherits fetchRows, fetchObjects, fetchField, forEach* and update without restating a line of them.

The names and their meanings are the driver's, unchanged, and parameters are supplied at the terminal as they are there. What these add is the one thing a RunnableQuery knows and a driver query does not: which session to run on. Nothing has to be opened around a query, which is what keeps a single one to a single expression - the session is asked for when a terminal runs, and inside a transaction that is the transaction's own.

They throw, as the driver throws. Where a failure should be a value instead, asResult switches this query to terminals that return one.

Parameters are @name only. Positional $1 placeholders stay reachable where they always were - db.execute { createNativeQuery(…) }.

Inheritors

Constructors

RunnableQuery

@PublishedApi

internal constructor(queryProvider: SessionProvider)

Properties

queryParameterConverters

@PublishedApi

internal var queryParameterConverters: MutableList<ParameterConverter<*>>?

queryProvider

@PublishedApi

internal val queryProvider: SessionProvider

Decides which session the terminals run on.

queryResultConverters

@PublishedApi

internal var queryResultConverters: MutableList<ResultConverter<*, *>>?

Functions

asResult

fun asResult(): ResultQuery

Switches this query to the result style: every terminal on the returned object hands back a DataResult instead of throwing.

asStep

fun asStep(): StepBuilder

Turns this query into a step of a TransactionPlan instead of something to run now.

copyConvertersFrom

internal fun copyConvertersFrom(other: RunnableQuery<*>)

Carries registered converters into a builder's copy(), alongside whatever clauses it copies.

fetchField

inline fun <T> fetchField(params: Map<String, Any?> = emptyMap()): T

inline fun <T> fetchField(vararg params: Pair<String, Any?>): T

Runs the query and returns the first column of its single row as T.

fetchFields

inline fun <T> fetchFields(params: Map<String, Any?> = emptyMap()): List<T>

inline fun <T> fetchFields(vararg params: Pair<String, Any?>): List<T>

Runs the query and returns the first column of every row as T.

fetchFieldStrict

inline fun <T> fetchFieldStrict(params: Map<String, Any?> = emptyMap()): T

inline fun <T> fetchFieldStrict(vararg params: Pair<String, Any?>): T

As fetchField, but the query must return exactly one row rather than at most one.

fetchObject

inline fun <T : Any> fetchObject(params: Map<String, Any?> = emptyMap()): T?

inline fun <T : Any> fetchObject(vararg params: Pair<String, Any?>): T?

Runs the query and maps its single row onto T, or null where none matched.

fetchObjects

inline fun <T : Any> fetchObjects(params: Map<String, Any?> = emptyMap()): List<T>

inline fun <T : Any> fetchObjects(vararg params: Pair<String, Any?>): List<T>

Runs the query and maps every row onto T.

fetchObjectStrict

inline fun <T : Any> fetchObjectStrict(params: Map<String, Any?> = emptyMap()): T

inline fun <T : Any> fetchObjectStrict(vararg params: Pair<String, Any?>): T

Runs the query and maps its single row onto T, throwing where the count was anything but one.

fetchRow

fun fetchRow(params: Map<String, Any?> = emptyMap()): Row?

fun fetchRow(vararg params: Pair<String, Any?>): Row?

Runs the query and returns its single row, or null where none matched.

fetchRows

fun fetchRows(params: Map<String, Any?> = emptyMap()): List<Row>

fun fetchRows(vararg params: Pair<String, Any?>): List<Row>

Runs the query and returns every row.

fetchRowStrict

fun fetchRowStrict(params: Map<String, Any?> = emptyMap()): Row

fun fetchRowStrict(vararg params: Pair<String, Any?>): Row

Runs the query and returns its single row, throwing where the count was anything but one.

forEachField

inline fun <T> forEachField(params: Map<String, Any?> = emptyMap(), fetchSize: Int, crossinline block: (T) -> Unit)

inline fun <T> forEachField(vararg params: Pair<String, Any?>, fetchSize: Int, crossinline block: (T) -> Unit)

Runs the query and hands the first column of each row, as T, to block as it arrives.

forEachObject

inline fun <T : Any> forEachObject(params: Map<String, Any?> = emptyMap(), fetchSize: Int, crossinline block: (T) -> Unit)

inline fun <T : Any> forEachObject(vararg params: Pair<String, Any?>, fetchSize: Int, crossinline block: (T) -> Unit)

Runs the query and hands each row, mapped onto T, to block as it arrives.

forEachRow

fun forEachRow(params: Map<String, Any?> = emptyMap(), fetchSize: Int, block: (Row) -> Unit)

fun forEachRow(vararg params: Pair<String, Any?>, fetchSize: Int, block: (Row) -> Unit)

Runs the query and hands each row to block as it arrives, in batches of fetchSize.

preparedQuery

@PublishedApi

internal fun OctaviusSessionOperations.preparedQuery(): NamedParameterQuery

Builds the driver query a terminal is about to run, with this query's own converters on it.

querySql

@PublishedApi

internal abstract fun querySql(): String

Renders the SQL. Called once per terminal call, so a builder may put off assembling it until here.

registerParameterConverter

fun registerParameterConverter(converter: ParameterConverter<*>): T

Registers a ParameterConverter for this query and nothing else.

registerResultConverter

fun registerResultConverter(converter: ResultConverter<*, *>): T

Registers a ResultConverter for this query and nothing else.

toSql

fun toSql(): String

Renders the SQL this query would send.

update

fun update(params: Map<String, Any?> = emptyMap()): Long

fun update(vararg params: Pair<String, Any?>): Long

Runs the statement and returns how many rows it affected.