Add Json support to kotlinx

This commit is contained in:
2025-03-29 19:49:35 -04:00
parent 33daaed7b4
commit 79436d6fd0
7 changed files with 1125 additions and 8 deletions

View File

@@ -0,0 +1,348 @@
package solutions.bitbadger.documents.kotlinx
import solutions.bitbadger.documents.*
import solutions.bitbadger.documents.query.FindQuery
import solutions.bitbadger.documents.query.orderBy
import solutions.bitbadger.documents.java.Json as CoreJson
import java.sql.Connection
/**
* Functions to find and retrieve documents, returning them as JSON strings
*/
object Json {
/**
* Retrieve all documents in the given table, ordering results by the optional given fields
*
* @param tableName The table from which documents should be retrieved
* @param orderBy Fields by which the query should be ordered (optional, defaults to no ordering)
* @param conn The connection over which documents should be retrieved
* @return A JSON array of documents from the given table
* @throws DocumentException If query execution fails
*/
fun all(tableName: String, orderBy: Collection<Field<*>>? = null, conn: Connection) =
CoreJson.all(tableName, orderBy, conn)
/**
* Retrieve all documents in the given table (creates connection)
*
* @param tableName The table from which documents should be retrieved
* @param orderBy Fields by which the query should be ordered (optional, defaults to no ordering)
* @return A JSON array of documents from the given table
* @throws DocumentException If no connection string has been set, or if query execution fails
*/
fun all(tableName: String, orderBy: Collection<Field<*>>? = null) =
CoreJson.all(tableName, orderBy)
/**
* Retrieve all documents in the given table
*
* @param tableName The table from which documents should be retrieved
* @param conn The connection over which documents should be retrieved
* @return A JSON array of documents from the given table
* @throws DocumentException If query execution fails
*/
fun all(tableName: String, conn: Connection) =
CoreJson.all(tableName, conn)
/**
* Retrieve a document by its ID
*
* @param tableName The table from which the document should be retrieved
* @param docId The ID of the document to retrieve
* @param conn The connection over which documents should be retrieved
* @return A JSON document if found, an empty JSON object if not found
* @throws DocumentException If no dialect has been configured
*/
fun <TKey> byId(tableName: String, docId: TKey, conn: Connection) =
CoreJson.byId(tableName, docId, conn)
/**
* Retrieve a document by its ID (creates connection)
*
* @param tableName The table from which the document should be retrieved
* @param docId The ID of the document to retrieve
* @return A JSON document if found, an empty JSON object if not found
* @throws DocumentException If no connection string has been set
*/
fun <TKey> byId(tableName: String, docId: TKey) =
CoreJson.byId(tableName, docId)
/**
* Retrieve documents using a field comparison, ordering results by the given fields
*
* @param tableName The table from which documents should be retrieved
* @param fields The fields which should be compared
* @param howMatched How the fields should be matched
* @param orderBy Fields by which the query should be ordered (optional, defaults to no ordering)
* @param conn The connection over which documents should be retrieved
* @return A JSON array of documents matching the field comparison
* @throws DocumentException If no dialect has been configured, or if parameters are invalid
*/
fun byFields(
tableName: String,
fields: Collection<Field<*>>,
howMatched: FieldMatch? = null,
orderBy: Collection<Field<*>>? = null,
conn: Connection
) = CoreJson.byFields(tableName, fields, howMatched, orderBy, conn)
/**
* Retrieve documents using a field comparison, ordering results by the given fields (creates connection)
*
* @param tableName The table from which documents should be retrieved
* @param fields The fields which should be compared
* @param howMatched How the fields should be matched
* @param orderBy Fields by which the query should be ordered (optional, defaults to no ordering)
* @return A JSON array of documents matching the field comparison
* @throws DocumentException If no connection string has been set, or if parameters are invalid
*/
fun byFields(
tableName: String,
fields: Collection<Field<*>>,
howMatched: FieldMatch? = null,
orderBy: Collection<Field<*>>? = null
) = CoreJson.byFields(tableName, fields, howMatched, orderBy)
/**
* Retrieve documents using a field comparison
*
* @param tableName The table from which documents should be retrieved
* @param fields The fields which should be compared
* @param howMatched How the fields should be matched
* @param conn The connection over which documents should be retrieved
* @return A JSON array of documents matching the field comparison
* @throws DocumentException If no dialect has been configured, or if parameters are invalid
*/
fun byFields(tableName: String, fields: Collection<Field<*>>, howMatched: FieldMatch? = null, conn: Connection) =
CoreJson.byFields(tableName, fields, howMatched, conn)
/**
* Retrieve documents using a JSON containment query, ordering results by the given fields (PostgreSQL only)
*
* @param tableName The table from which documents should be retrieved
* @param criteria The object for which JSON containment should be checked
* @param orderBy Fields by which the query should be ordered (optional, defaults to no ordering)
* @param conn The connection over which documents should be retrieved
* @return A JSON array of documents matching the JSON containment query
* @throws DocumentException If called on a SQLite connection
*/
inline fun <reified TContains> byContains(
tableName: String,
criteria: TContains,
orderBy: Collection<Field<*>>? = null,
conn: Connection
) = Custom.jsonArray(
FindQuery.byContains(tableName) + (orderBy?.let(::orderBy) ?: ""),
listOf(Parameters.json(":criteria", criteria)),
conn,
Results::jsonFromData
)
/**
* Retrieve documents using a JSON containment query, ordering results by the given fields (PostgreSQL only; creates
* connection)
*
* @param tableName The table from which documents should be retrieved
* @param criteria The object for which JSON containment should be checked
* @param orderBy Fields by which the query should be ordered (optional, defaults to no ordering)
* @return A JSON array of documents matching the JSON containment query
* @throws DocumentException If no connection string has been set, or if called on a SQLite connection
*/
inline fun <reified TContains> byContains(
tableName: String,
criteria: TContains,
orderBy: Collection<Field<*>>? = null
) = Configuration.dbConn().use { byContains(tableName, criteria, orderBy, it) }
/**
* Retrieve documents using a JSON containment query (PostgreSQL only)
*
* @param tableName The table from which documents should be retrieved
* @param criteria The object for which JSON containment should be checked
* @param conn The connection over which documents should be retrieved
* @return A JSON array of documents matching the JSON containment query
* @throws DocumentException If called on a SQLite connection
*/
inline fun <reified TContains> byContains(tableName: String, criteria: TContains, conn: Connection) =
byContains(tableName, criteria, null, conn)
/**
* Retrieve documents using a JSON Path match query, ordering results by the given fields (PostgreSQL only)
*
* @param tableName The table from which documents should be retrieved
* @param path The JSON path comparison to match
* @param orderBy Fields by which the query should be ordered (optional, defaults to no ordering)
* @param conn The connection over which documents should be retrieved
* @return A JSON array of documents matching the JSON Path match query
* @throws DocumentException If called on a SQLite connection
*/
fun byJsonPath(tableName: String, path: String, orderBy: Collection<Field<*>>? = null, conn: Connection) =
CoreJson.byJsonPath(tableName, path, orderBy, conn)
/**
* Retrieve documents using a JSON Path match query, ordering results by the given fields (PostgreSQL only; creates
* connection)
*
* @param tableName The table from which documents should be retrieved
* @param path The JSON path comparison to match
* @param orderBy Fields by which the query should be ordered (optional, defaults to no ordering)
* @return A JSON array of documents matching the JSON Path match query
* @throws DocumentException If no connection string has been set, or if called on a SQLite connection
*/
fun byJsonPath(tableName: String, path: String, orderBy: Collection<Field<*>>? = null) =
CoreJson.byJsonPath(tableName, path, orderBy)
/**
* Retrieve documents using a JSON Path match query (PostgreSQL only)
*
* @param tableName The table from which documents should be retrieved
* @param path The JSON path comparison to match
* @param conn The connection over which documents should be retrieved
* @return A JSON array of documents matching the JSON Path match query
* @throws DocumentException If called on a SQLite connection
*/
fun byJsonPath(tableName: String, path: String, conn: Connection) =
CoreJson.byJsonPath(tableName, path, conn)
/**
* Retrieve the first document using a field comparison and optional ordering fields
*
* @param tableName The table from which documents should be retrieved
* @param fields The fields which should be compared
* @param howMatched How the fields should be matched (optional, defaults to `FieldMatch.ALL`)
* @param orderBy Fields by which the query should be ordered (optional, defaults to no ordering)
* @param conn The connection over which documents should be retrieved
* @return The first JSON document matching the field comparison if found, an empty JSON object otherwise
* @throws DocumentException If no dialect has been configured, or if parameters are invalid
*/
fun firstByFields(
tableName: String,
fields: Collection<Field<*>>,
howMatched: FieldMatch? = null,
orderBy: Collection<Field<*>>? = null,
conn: Connection
) = CoreJson.firstByFields(tableName, fields, howMatched, orderBy, conn)
/**
* Retrieve the first document using a field comparison and optional ordering fields (creates connection)
*
* @param tableName The table from which documents should be retrieved
* @param fields The fields which should be compared
* @param howMatched How the fields should be matched (optional, defaults to `FieldMatch.ALL`)
* @param orderBy Fields by which the query should be ordered (optional, defaults to no ordering)
* @return The first JSON document matching the field comparison if found, an empty JSON object otherwise
* @throws DocumentException If no connection string has been set, or if parameters are invalid
*/
fun firstByFields(
tableName: String,
fields: Collection<Field<*>>,
howMatched: FieldMatch? = null,
orderBy: Collection<Field<*>>? = null
) = CoreJson.firstByFields(tableName, fields, howMatched, orderBy)
/**
* Retrieve the first document using a field comparison
*
* @param tableName The table from which documents should be retrieved
* @param fields The fields which should be compared
* @param howMatched How the fields should be matched (optional, defaults to `FieldMatch.ALL`)
* @param conn The connection over which documents should be retrieved
* @return The first JSON document matching the field comparison if found, an empty JSON object otherwise
* @throws DocumentException If no dialect has been configured, or if parameters are invalid
*/
fun firstByFields(
tableName: String,
fields: Collection<Field<*>>,
howMatched: FieldMatch? = null,
conn: Connection
) = CoreJson.firstByFields(tableName, fields, howMatched, conn)
/**
* Retrieve the first document using a JSON containment query and optional ordering fields (PostgreSQL only)
*
* @param tableName The table from which documents should be retrieved
* @param criteria The object for which JSON containment should be checked
* @param orderBy Fields by which the query should be ordered (optional, defaults to no ordering)
* @param conn The connection over which documents should be retrieved
* @return The first JSON document matching the JSON containment query if found, an empty JSON object otherwise
* @throws DocumentException If called on a SQLite connection
*/
inline fun <reified TContains> firstByContains(
tableName: String,
criteria: TContains,
orderBy: Collection<Field<*>>? = null,
conn: Connection
) = Custom.jsonSingle(
FindQuery.byContains(tableName) + (orderBy?.let(::orderBy) ?: ""),
listOf(Parameters.json(":criteria", criteria)),
conn,
Results::jsonFromData
)
/**
* Retrieve the first document using a JSON containment query (PostgreSQL only)
*
* @param tableName The table from which documents should be retrieved
* @param criteria The object for which JSON containment should be checked
* @param conn The connection over which documents should be retrieved
* @return The first JSON document matching the JSON containment query if found, an empty JSON object otherwise
* @throws DocumentException If called on a SQLite connection
*/
inline fun <reified TContains> firstByContains(tableName: String, criteria: TContains, conn: Connection) =
firstByContains(tableName, criteria, null, conn)
/**
* Retrieve the first document using a JSON containment query and optional ordering fields (PostgreSQL only; creates
* connection)
*
* @param tableName The table from which documents should be retrieved
* @param criteria The object for which JSON containment should be checked
* @param orderBy Fields by which the query should be ordered (optional, defaults to no ordering)
* @return The first JSON document matching the JSON containment query if found, an empty JSON object otherwise
* @throws DocumentException If no connection string has been set, or if called on a SQLite connection
*/
inline fun <reified TContains> firstByContains(
tableName: String,
criteria: TContains,
orderBy: Collection<Field<*>>? = null
) = Configuration.dbConn().use { firstByContains(tableName, criteria, orderBy, it) }
/**
* Retrieve the first document using a JSON Path match query and optional ordering fields (PostgreSQL only)
*
* @param tableName The table from which documents should be retrieved
* @param path The JSON path comparison to match
* @param orderBy Fields by which the query should be ordered (optional, defaults to no ordering)
* @param conn The connection over which documents should be retrieved
* @return The first JSON document matching the JSON Path match query if found, an empty JSON object otherwise
* @throws DocumentException If called on a SQLite connection
*/
fun firstByJsonPath(tableName: String, path: String, orderBy: Collection<Field<*>>? = null, conn: Connection) =
CoreJson.firstByJsonPath(tableName, path, orderBy, conn)
/**
* Retrieve the first document using a JSON Path match query (PostgreSQL only)
*
* @param tableName The table from which documents should be retrieved
* @param path The JSON path comparison to match
* @param conn The connection over which documents should be retrieved
* @return The first JSON document matching the JSON Path match query if found, an empty JSON object otherwise
* @throws DocumentException If called on a SQLite connection
*/
fun firstByJsonPath(tableName: String, path: String, conn: Connection) =
CoreJson.firstByJsonPath(tableName, path, conn)
/**
* Retrieve the first document using a JSON Path match query and optional ordering fields (PostgreSQL only; creates
* connection)
*
* @param tableName The table from which documents should be retrieved
* @param path The JSON path comparison to match
* @param orderBy Fields by which the query should be ordered (optional, defaults to no ordering)
* @return The first JSON document matching the JSON Path match query if found, an empty JSON object otherwise
* @throws DocumentException If no connection string has been set, or if called on a SQLite connection
*/
fun firstByJsonPath(tableName: String, path: String, orderBy: Collection<Field<*>>? = null) =
CoreJson.firstByJsonPath(tableName, path, orderBy)
}

View File

@@ -233,7 +233,7 @@ inline fun <reified TContains> Connection.existsByContains(tableName: String, cr
fun Connection.existsByJsonPath(tableName: String, path: String) =
Exists.byJsonPath(tableName, path, this)
// ~~~ DOCUMENT RETRIEVAL QUERIES ~~~
// ~~~ DOCUMENT RETRIEVAL QUERIES (Domain Objects) ~~~
/**
* Retrieve all documents in the given table, ordering results by the optional given fields
@@ -347,6 +347,119 @@ inline fun <reified TDoc : Any> Connection.findFirstByJsonPath(
orderBy: Collection<Field<*>>? = null
) = Find.firstByJsonPath<TDoc>(tableName, path, orderBy, this)
// ~~~ DOCUMENT RETRIEVAL QUERIES (Raw JSON) ~~~
/**
* Retrieve all documents in the given table
*
* @param tableName The table from which documents should be retrieved
* @param orderBy Fields by which the query should be ordered (optional, defaults to no ordering)
* @return A JSON array of documents from the given table
* @throws DocumentException If no connection string has been set, or if query execution fails
*/
fun Connection.jsonAll(tableName: String, orderBy: Collection<Field<*>>? = null) =
Json.all(tableName, orderBy, this)
/**
* Retrieve a document by its ID
*
* @param tableName The table from which the document should be retrieved
* @param docId The ID of the document to retrieve
* @return A JSON document if found, an empty JSON object if not found
* @throws DocumentException If no connection string has been set
*/
fun <TKey> Connection.jsonById(tableName: String, docId: TKey) =
Json.byId(tableName, docId, this)
/**
* Retrieve documents using a field comparison, ordering results by the given fields
*
* @param tableName The table from which documents should be retrieved
* @param fields The fields which should be compared
* @param howMatched How the fields should be matched
* @param orderBy Fields by which the query should be ordered (optional, defaults to no ordering)
* @return A JSON array of documents matching the field comparison
* @throws DocumentException If no connection string has been set, or if parameters are invalid
*/
fun Connection.jsonByFields(
tableName: String,
fields: Collection<Field<*>>,
howMatched: FieldMatch? = null,
orderBy: Collection<Field<*>>? = null
) = Json.byFields(tableName, fields, howMatched, orderBy, this)
/**
* Retrieve documents using a JSON containment query, ordering results by the given fields (PostgreSQL only)
*
* @param tableName The table from which documents should be retrieved
* @param criteria The object for which JSON containment should be checked
* @param orderBy Fields by which the query should be ordered (optional, defaults to no ordering)
* @return A JSON array of documents matching the JSON containment query
* @throws DocumentException If no connection string has been set, or if called on a SQLite connection
*/
inline fun <reified TContains> Connection.jsonByContains(
tableName: String,
criteria: TContains,
orderBy: Collection<Field<*>>? = null
) = Json.byContains(tableName, criteria, orderBy, this)
/**
* Retrieve documents using a JSON Path match query, ordering results by the given fields (PostgreSQL only)
*
* @param tableName The table from which documents should be retrieved
* @param path The JSON path comparison to match
* @param orderBy Fields by which the query should be ordered (optional, defaults to no ordering)
* @return A JSON array of documents matching the JSON Path match query
* @throws DocumentException If no connection string has been set, or if called on a SQLite connection
*/
fun Connection.jsonByJsonPath(tableName: String, path: String, orderBy: Collection<Field<*>>? = null) =
Json.byJsonPath(tableName, path, orderBy, this)
/**
* Retrieve the first document using a field comparison and optional ordering fields
*
* @param tableName The table from which documents should be retrieved
* @param fields The fields which should be compared
* @param howMatched How the fields should be matched (optional, defaults to `FieldMatch.ALL`)
* @param orderBy Fields by which the query should be ordered (optional, defaults to no ordering)
* @return The first JSON document matching the field comparison if found, an empty JSON object otherwise
* @throws DocumentException If no connection string has been set, or if parameters are invalid
*/
fun Connection.jsonFirstByFields(
tableName: String,
fields: Collection<Field<*>>,
howMatched: FieldMatch? = null,
orderBy: Collection<Field<*>>? = null
) = Json.firstByFields(tableName, fields, howMatched, orderBy, this)
/**
* Retrieve the first document using a JSON containment query and optional ordering fields (PostgreSQL only)
*
* @param tableName The table from which documents should be retrieved
* @param criteria The object for which JSON containment should be checked
* @param orderBy Fields by which the query should be ordered (optional, defaults to no ordering)
* @return The first JSON document matching the JSON containment query if found, an empty JSON object otherwise
* @throws DocumentException If no connection string has been set, or if called on a SQLite connection
*/
inline fun <reified TContains> Connection.jsonFirstByContains(
tableName: String,
criteria: TContains,
orderBy: Collection<Field<*>>? = null
) = Json.firstByContains(tableName, criteria, orderBy, this)
/**
* Retrieve the first document using a JSON Path match query and optional ordering fields (PostgreSQL only; creates
* connection)
*
* @param tableName The table from which documents should be retrieved
* @param path The JSON path comparison to match
* @param orderBy Fields by which the query should be ordered (optional, defaults to no ordering)
* @return The first JSON document matching the JSON Path match query if found, an empty JSON object otherwise
* @throws DocumentException If no connection string has been set, or if called on a SQLite connection
*/
fun Connection.jsonFirstByJsonPath(tableName: String, path: String, orderBy: Collection<Field<*>>? = null) =
Json.firstByJsonPath(tableName, path, orderBy, this)
// ~~~ DOCUMENT PATCH (PARTIAL UPDATE) QUERIES ~~~
/**