stormify/onl.ycode.stormify/Stormify

Stormify

class Stormify(val dataSource: DataSource, registrars: EntityRegistrar, val poolConfig: PoolConfig = PoolConfig())

The main ORM controller. Entry point for all database operations.

Configuration lifecycle

A Stormify instance is designed to be configured once, then shared across threads. The intended usage is:

Construct the instance (optionally passing registrars).
Apply configuration — assign to namingPolicy, unmatchedColumnPolicy, logger, filterSyntax, inputParser; call addBlacklistField, registerPrimaryKeyResolver, etc.
Publish the instance to whoever needs it (DI container, asDefault(), dependency parameter, …) and start issuing queries.

After step 3, treat all configuration as frozen. Mutating configuration while other threads are executing queries is not supported — behaviour is undefined and any entity metadata already cached will not reflect the change. The query path itself (CRUD, read, findAll, stored procedures, transactions) is safe to call concurrently from many threads on a fully-configured instance.

Parameters

dataSource

the data source for all database operations

registrars

optional entity registrars to register at construction time

poolConfig

tuning for the connection pool behind suspending. The defaults are sensible for most applications — see PoolConfig for the double-pooling warning when dataSource already pools (e.g. HikariCP).

Constructors

Stormify

constructor(dataSource: DataSource, vararg registrars: EntityRegistrar, poolConfig: PoolConfig = PoolConfig())

constructor(dataSource: DataSource)

Single-argument convenience constructor. Exists primarily so Spring XML <constructor-arg ref="dataSource"/> (and similar DI containers that resolve constructors by arity) can pick an unambiguous one-arg match.

constructor(dataSource: DataSource, poolConfig: PoolConfig)

Convenience constructor with pool tuning and no registrars.

Types

Companion

object Companion

Holds the library-wide defaultInstance used when no instance is explicitly attached.

Properties

cursorFetchSize

@Volatile

var cursorFetchSize: Int

How many rows the driver buffers per round-trip during streaming reads. Used by readCursor on every dialect, and additionally by the eager read path on Oracle, whose driver default would otherwise turn a bulk read into a round-trip storm.

dataSource

val dataSource: DataSource

filterSyntax

@Volatile

var filterSyntax: FilterSyntax

The filter syntax used by facets on this instance. Controls which tokens represent OR, NOT, NULL, phrase delimiters, grouping, and wildcards. Default is Google-like syntax: OR, -, NULL, ", (), *.

inputParser

@Volatile

var inputParser: InputParser?

Default input parser for facet filter values. Applied after per-facet and per-list parsers in the resolution chain. Use for locale-aware number/date parsing across all facets.

logger

@Volatile

var logger: Logger

The logger used by this Stormify instance. Defaults to a logger named "Stormify".

namingPolicy

@Volatile

var namingPolicy: (String) -> String

The naming policy used to convert Kotlin property names to database column names. Default is NamingPolicy.LOWER_CASE_WITH_UNDERSCORES (snake_case). Changing this only affects entities resolved after the change.

poolConfig

val poolConfig: PoolConfig

sqlDialect

var sqlDialect: SqlDialect

The SQL dialect used by this Stormify instance. Auto-detected from the data source on first access. Can be set manually for proxy scenarios where auto-detection fails.

suspending

val suspending: SuspendStormify

The coroutine-aware API of this instance, backed by a single connection pool created lazily on first access with poolConfig.

unmatchedColumnPolicy

@Volatile

var unmatchedColumnPolicy: UnmatchedColumnPolicy

Policy for ResultSet columns that have no matching field on the target entity. Default is UnmatchedColumnPolicy.IGNORE.

Functions

addBlacklistField

fun addBlacklistField(name: String)

Excludes a field name from all entity mappings (e.g. inherited fields that have no database column).

asDefault

fun asDefault(): Stormify

Sets this instance as defaultInstance and returns it.

fun <R> asDefault(block: (Stormify) -> R): R

Runs block with this instance as the default, restoring the previous default when the block exits.

attach

fun <T : StormifyAware> attach(target: T): T

Attaches this Stormify instance to target so the target can use it for database operations without receiving it as an explicit parameter.

closeSuspending

suspend fun closeSuspending()

Closes the suspending connection pool if it was ever created; a no-op otherwise. Use this in shutdown hooks where touching suspending just to close it would needlessly spin up a pool.

create

fun <T : Any> create(item: T): T

Inserts a new entity into the database and returns it with generated values populated.

fun <T : Any> create(items: Collection<T>): List<T>

Inserts multiple entities in a batch and returns them. Generated keys are only populated for single-item batches.

delete

fun <T : Any> delete(deletedItem: T)

Deletes an entity from the database based on its primary key.

fun <T : Any> delete(items: Collection<T>)

Deletes multiple entities from the database based on their primary keys.

executeUpdate

fun executeUpdate(query: String, vararg params: Any?): Int

Executes an SQL UPDATE/INSERT/DELETE and returns the number of affected rows.

findAll

inline fun <T : Any> findAll(whereClause: String = "", vararg arguments: Any?): List<T>

Finds all entities, optionally filtered by a WHERE clause.

findById

inline fun <T : Any> findById(id: Any): T?

Finds a single entity by its primary key value (single PK only).

getDetails

inline fun <D : Any> getDetails(parent: Any, propertyName: String? = null): List<D>

Retrieves all detail (child) entities related to a parent entity through a foreign key.

inline fun <D : Any> getDetails(parent: Any, referenceField: ReferencePath): List<D>

Type-safe variant of getDetails that accepts an annotation-processor-generated reference path (e.g. Paths.AuditEntry_.createdBy) instead of a string. The compiler guarantees the referenced property exists on the child type, so typos and renames surface at build time rather than on first query.

getTableInfo

fun <T : Any> getTableInfo(kclass: KClass<T>): TableInfo<T>

Returns the TableInfo metadata for the given entity class, resolving and caching it if necessary.

procedure

fun procedure(name: String, vararg args: Any?)

Executes a stored procedure with IN / OUT / INOUT parameters.

read

inline fun <T : Any> read(query: String, vararg params: Any?, customFields: Map<String, (Any?) -> Unit>? = null): List<T>

Executes a SELECT query and returns all results as a list.

readCursor

inline fun <T : Any> readCursor(query: String, vararg params: Any?, fetchSize: Int = cursorFetchSize, customFields: Map<String, (Any?) -> Unit>? = null, noinline consumer: (T) -> Unit): Int

Executes a SELECT query and processes results row-by-row via consumer. Returns row count.

readOne

inline fun <T : Any> readOne(query: String, vararg params: Any?): T?

Executes a SELECT query and returns exactly one result, or null if no row is found.

refresh

fun <T : Any> refresh(entity: T): T

Refreshes an entity with fresh data from the database based on its primary key.

registerPrimaryKeyResolver

fun registerPrimaryKeyResolver(priority: Int, resolver: (String, String) -> Boolean)

Registers a primary key resolver used when no @Id or @DbField(primaryKey=true) annotation is present. The resolver receives the table name and field name and returns true if the field is a primary key. Lower priority values are evaluated first.

removeBlacklistField

fun removeBlacklistField(name: String)

Removes a previously blacklisted field name, allowing it to be mapped again.

transaction

fun <R> transaction(block: () -> R): R

Executes block within a database transaction with automatic commit on success and rollback on any thrown exception, returning the block's result.

update

fun <T : Any> update(updatedItem: T): T

Updates an existing entity in the database based on its primary key.

fun <T : Any> update(items: Collection<T>): List<T>

Updates multiple entities in a batch based on their primary keys.