From 457edd1adfb3e7eaf21fdb4247fd9ea0f52f7582 Mon Sep 17 00:00:00 2001 From: Thijs Koppen Date: Wed, 27 Nov 2024 21:31:21 +0100 Subject: [PATCH] Add documentation for UpdateComponent terminal operations and Column extension functions --- src/main/kotlin/ch/icken/query/Column.kt | 158 ++++++++++++++----- src/main/kotlin/ch/icken/query/Component.kt | 31 ++-- src/main/kotlin/ch/icken/query/Expression.kt | 9 +- 3 files changed, 138 insertions(+), 60 deletions(-) diff --git a/src/main/kotlin/ch/icken/query/Column.kt b/src/main/kotlin/ch/icken/query/Column.kt index fc77de2..4fc17f5 100644 --- a/src/main/kotlin/ch/icken/query/Column.kt +++ b/src/main/kotlin/ch/icken/query/Column.kt @@ -39,12 +39,19 @@ class Column(internal val name: String) { private fun eq(name: String, value: Any?): Expression = if (value == null) IsNull(name) else EqualTo(name, value) /** - * TODO + * Creates an [Expression][ch.icken.query.Expression] using the '=' operator. + * + * @param value the value to be compared with + * @return a new `Expression` instance */ @JvmName("eq") infix fun Column.eq(value: Type) = eq(name, value) /** - * TODO + * Creates an [Expression][ch.icken.query.Expression] using the '=' operator when `value` is not null, + * or using 'IS NULL' when `value` is null. + * + * @param value the value to be compared with + * @return a new `Expression` instance */ @JvmName("eqNullable") infix fun Column.eq(value: Type?) = eq(name, value) @@ -53,12 +60,19 @@ infix fun Column.eq(value: Type?) = eq neq(name: String, value: Any?): Expression = if (value == null) IsNotNull(name) else NotEqualTo(name, value) /** - * TODO + * Creates an [Expression][ch.icken.query.Expression] using the '!=' operator. + * + * @param value the value to be compared with + * @return a new `Expression` instance */ @JvmName("neq") infix fun Column.neq(value: Type) = neq(name, value) /** - * TODO + * Creates an [Expression][ch.icken.query.Expression] using the '!=' operator when `value` is not null, + * or using 'IS NOT NULL' when `value` is not null. + * + * @param value the value to be compared with + * @return a new `Expression` instance */ @JvmName("neqNullable") infix fun Column.neq(value: Type?) = neq(name, value) @@ -66,12 +80,18 @@ infix fun Column.neq(value: Type?) = neq lt(name: String, value: Any): Expression = LessThan(name, value) /** - * TODO + * Creates an [Expression][ch.icken.query.Expression] using the '<' operator. + * + * @param value the value to be compared with + * @return a new `Expression` instance */ @JvmName("lt") infix fun Column.lt(value: Type) = lt(name, value) /** - * TODO + * Creates an [Expression][ch.icken.query.Expression] using the '<' operator. + * + * @param value the value to be compared with + * @return a new `Expression` instance */ @JvmName("ltNullable") infix fun Column.lt(value: Type) = lt(name, value) @@ -79,12 +99,18 @@ infix fun Column.lt(value: Type) = lt gt(name: String, value: Any): Expression = GreaterThan(name, value) /** - * TODO + * Creates an [Expression][ch.icken.query.Expression] using the '>' operator. + * + * @param value the value to be compared with + * @return a new `Expression` instance */ @JvmName("gt") infix fun Column.gt(value: Type) = gt(name, value) /** - * TODO + * Creates an [Expression][ch.icken.query.Expression] using the '>' operator. + * + * @param value the value to be compared with + * @return a new `Expression` instance */ @JvmName("gtNullable") infix fun Column.gt(value: Type) = gt(name, value) @@ -92,12 +118,18 @@ infix fun Column.gt(value: Type) = gt lte(name: String, value: Any): Expression = LessThanOrEqualTo(name, value) /** - * TODO + * Creates an [Expression][ch.icken.query.Expression] using the '<=' operator. + * + * @param value the value to be compared with + * @return a new `Expression` instance */ @JvmName("lte") infix fun Column.lte(value: Type) = lte(name, value) /** - * TODO + * Creates an [Expression][ch.icken.query.Expression] using the '<=' operator. + * + * @param value the value to be compared with + * @return a new `Expression` instance */ @JvmName("lteNullable") infix fun Column.lte(value: Type) = lte(name, value) @@ -105,12 +137,18 @@ infix fun Column.lte(value: Type) = lte gte(name: String, value: Any): Expression = GreaterThanOrEqualTo(name, value) /** - * TODO + * Creates an [Expression][ch.icken.query.Expression] using the '>=' operator. + * + * @param value the value to be compared with + * @return a new `Expression` instance */ @JvmName("gte") infix fun Column.gte(value: Type) = gte(name, value) /** - * TODO + * Creates an [Expression][ch.icken.query.Expression] using the '>=' operator. + * + * @param value the value to be compared with + * @return a new `Expression` instance */ @JvmName("gteNullable") infix fun Column.gte(value: Type) = gte(name, value) @@ -119,12 +157,18 @@ infix fun Column.gte(value: Type) = gte `in`(name: String, values: Collection): Expression = In(name, values) /** - * TODO + * Creates an [Expression][ch.icken.query.Expression] using the 'IN' operator. + * + * @param values the values to be compared with + * @return a new `Expression` instance */ @JvmName("in") infix fun Column.`in`(values: Collection) = `in`(name, values) /** - * TODO + * Creates an [Expression][ch.icken.query.Expression] using the 'IN' operator. + * + * @param values the values to be compared with + * @return a new `Expression` instance */ @JvmName("inNullable") infix fun Column.`in`(values: Collection) = `in`(name, values) @@ -132,50 +176,64 @@ infix fun Column.`in`(values: Collection notIn(name: String, values: Collection): Expression = NotIn(name, values) /** - * TODO + * Creates an [Expression][ch.icken.query.Expression] using the 'NOT IN' operator. + * + * @param values the values to be compared with + * @return a new `Expression` instance */ @JvmName("notIn") infix fun Column.notIn(values: Collection) = notIn(name, values) /** - * TODO + * Creates an [Expression][ch.icken.query.Expression] using the 'NOT IN' operator. + * + * @param values the values to be compared with + * @return a new `Expression` instance */ @JvmName("notInNullable") infix fun Column.notIn(values: Collection) = notIn(name, values) //endregion //region like -private fun like(name: String, expression: String?): Expression = - if (expression == null) IsNull(name) else Like(name, expression) +private fun like(name: String, pattern: String?): Expression = + if (pattern == null) IsNull(name) else Like(name, pattern) /** - * TODO + * Creates an [Expression][ch.icken.query.Expression] using the 'LIKE' operator. + * + * @param pattern the pattern to be matched + * @return a new `Expression` instance */ @JvmName("like") -infix fun Column.like(expression: String) = like(name, expression) +infix fun Column.like(pattern: String) = like(name, pattern) /** - * TODO + * Creates an [Expression][ch.icken.query.Expression] using the 'LIKE' operator when `pattern` is not null, + * or using 'IS NULL' when `pattern` is null. + * + * @param pattern the pattern to be matched + * @return a new `Expression` instance */ @JvmName("likeNullable") -infix fun Column.like(expression: String?) = like(name, expression) -//TODO startsWith -//TODO contains -//TODO endsWith +infix fun Column.like(pattern: String?) = like(name, pattern) //endregion //region notLike -private fun notLike(name: String, expression: String?): Expression = - if (expression == null) IsNotNull(name) else NotLike(name, expression) +private fun notLike(name: String, pattern: String?): Expression = + if (pattern == null) IsNotNull(name) else NotLike(name, pattern) /** - * TODO + * Creates an [Expression][ch.icken.query.Expression] using the 'NOT LIKE' operator. + * + * @param pattern the pattern to be matched + * @return a new `Expression` instance */ @JvmName("notLike") -infix fun Column.notLike(expression: String) = notLike(name, expression) +infix fun Column.notLike(pattern: String) = notLike(name, pattern) /** - * TODO + * Creates an [Expression][ch.icken.query.Expression] using the 'NOT LIKE' operator when `pattern` is not null, + * or using 'IS NOT NULL' when `pattern` is not null. + * + * @param pattern the pattern to be matched + * @return a new `Expression` instance */ @JvmName("notLikeNullable") -infix fun Column.notLike(expression: String?) = notLike(name, expression) -//TODO notStartsWith -//TODO notContains -//TODO notEndsWith +infix fun Column.notLike(pattern: String?) = notLike(name, pattern) //endregion //region between @@ -186,13 +244,25 @@ private fun between(name: String, min: Any?, maxIncl: Any?): Expressio else -> IsNull(name) } /** - * TODO + * Creates an [Expression][ch.icken.query.Expression] using the 'BETWEEN' operator. + * + * @param min the minimum value to be compared with + * @param maxIncl the maximum (inclusive) value to be compared with + * @return a new `Expression` instance */ @JvmName("between") fun Column.between(min: Type, maxIncl: Type) = between(name, min, maxIncl) /** - * TODO + * Creates an [Expression][ch.icken.query.Expression] using exactly one of the following: + * - the 'BETWEEN' operator when both `min` and `maxIncl` are not null + * - the '>=' operator when `min` is not null and `maxIncl` is null + * - the '<=' operator when `min` is null and `maxIncl` is not null + * - 'IS NULL' when both `min` and `maxIncl` are null + * + * @param min the minimum value to be compared with + * @param maxIncl the maximum (inclusive) value to be compared with + * @return a new `Expression` instance */ @JvmName("betweenNullable") fun Column.between(min: Type?, maxIncl: Type?) = @@ -206,13 +276,25 @@ private fun notBetween(name: String, min: Any?, maxIncl: Any?): Expres else -> IsNotNull(name) } /** - * TODO + * Creates an [Expression][ch.icken.query.Expression] using the 'NOT BETWEEN' operator. + * + * @param min the minimum value to be compared with + * @param maxIncl the maximum (inclusive) value to be compared with + * @return a new `Expression` instance */ @JvmName("notBetween") fun Column.notBetween(min: Type, maxIncl: Type) = notBetween(name, min, maxIncl) /** - * TODO + * Creates an [Expression][ch.icken.query.Expression] using exactly one of the following: + * - the 'NOT BETWEEN' operator when both `min` and `maxIncl` are not null + * - the '<' operator when `min` is not null and `maxIncl` is null + * - the '>' operator when `min` is null and `maxIncl` is not null + * - 'IS NOT NULL' when both `min` and `maxIncl` are null + * + * @param min the minimum value to be compared with + * @param maxIncl the maximum (inclusive) value to be compared with + * @return a new `Expression` instance */ @JvmName("notBetweenNullable") fun Column.notBetween(min: Type?, maxIncl: Type?) = diff --git a/src/main/kotlin/ch/icken/query/Component.kt b/src/main/kotlin/ch/icken/query/Component.kt index 94e0841..5568acd 100644 --- a/src/main/kotlin/ch/icken/query/Component.kt +++ b/src/main/kotlin/ch/icken/query/Component.kt @@ -50,14 +50,8 @@ sealed class Component private co protected val expression: Expression ) : Component(companion) { //region Chaining operations - /** - * TODO - */ fun and(expression: Expression): QueryComponent = LogicalQueryComponent.AndQueryComponent(companion, this, expression) - /** - * TODO - */ fun or(expression: Expression): QueryComponent = LogicalQueryComponent.OrQueryComponent(companion, this, expression) //endregion @@ -223,16 +217,20 @@ sealed class Component private co private val setters: Array SetterExpression> ) : UpdateComponent(companion) { //region Chaining operations - /** - * TODO - */ fun where(expression: Expression): LogicalUpdateComponent = LogicalUpdateComponent.WhereUpdateComponent(companion, this, expression) //endregion //region Terminal operations /** - * TODO + * Updates all entities of this type. + * + * WARNING: this function updates ALL entities without a WHERE clause + * + * WARNING: this function requires a transaction to be active. + * + * @return the number of entities updated + * @see io.quarkus.hibernate.orm.panache.kotlin.PanacheCompanionBase.update */ fun executeWithoutWhere() = withCompiled { companion.update(component, parameters) } //endregion @@ -263,21 +261,20 @@ sealed class Component private co private val expression: Expression ) : UpdateComponent(companion) { //region Chaining operations - /** - * TODO - */ fun and(expression: Expression): LogicalUpdateComponent = AndUpdateComponent(companion, this, expression) - /** - * TODO - */ fun or(expression: Expression): LogicalUpdateComponent = OrUpdateComponent(companion, this, expression) //endregion //region Terminal operations /** - * TODO + * Updates all entities matching the preceding query + * + * WARNING: this function requires a transaction to be active + * + * @return the number of entities updated + * @see io.quarkus.hibernate.orm.panache.kotlin.PanacheCompanionBase.update */ fun execute() = withCompiled { companion.update(component, parameters) } //endregion diff --git a/src/main/kotlin/ch/icken/query/Expression.kt b/src/main/kotlin/ch/icken/query/Expression.kt index 7975c27..2ed042e 100644 --- a/src/main/kotlin/ch/icken/query/Expression.kt +++ b/src/main/kotlin/ch/icken/query/Expression.kt @@ -68,11 +68,10 @@ sealed class Expression { class NotIn internal constructor(key: String, values: Collection) : BooleanValueExpression(key, "NOT IN", values) - class Like internal constructor(key: String, expression: String) : - BooleanValueExpression(key, "LIKE", expression) - class NotLike internal constructor(key: String, expression: String) : - BooleanValueExpression(key, "NOT LIKE", expression) - + class Like internal constructor(key: String, pattern: String) : + BooleanValueExpression(key, "LIKE", pattern) + class NotLike internal constructor(key: String, pattern: String) : + BooleanValueExpression(key, "NOT LIKE", pattern) } sealed class BetweenExpression private constructor(