From 78fbea43b6a7c3c91c186cffc49bbc603b165aa2 Mon Sep 17 00:00:00 2001 From: Christoph Strobl Date: Thu, 12 Sep 2024 10:39:48 +0200 Subject: [PATCH] Polishing. Add since tags to extension methods and issue references to tests. Update antora playbook to consider maintenance branches. Original Pull Request: #4753 --- .../core/query/TypedUpdateExtensions.kt | 24 +++++++++- .../core/query/TypedUpdateExtensionsTests.kt | 48 +++++++++---------- src/main/antora/antora-playbook.yml | 2 +- .../modules/ROOT/pages/kotlin/extensions.adoc | 8 +++- 4 files changed, 53 insertions(+), 29 deletions(-) diff --git a/spring-data-mongodb/src/main/kotlin/org/springframework/data/mongodb/core/query/TypedUpdateExtensions.kt b/spring-data-mongodb/src/main/kotlin/org/springframework/data/mongodb/core/query/TypedUpdateExtensions.kt index d35c1d74cd..e6d06386a1 100644 --- a/spring-data-mongodb/src/main/kotlin/org/springframework/data/mongodb/core/query/TypedUpdateExtensions.kt +++ b/spring-data-mongodb/src/main/kotlin/org/springframework/data/mongodb/core/query/TypedUpdateExtensions.kt @@ -1,5 +1,5 @@ /* - * Copyright 2018-2024 the original author or authors. + * Copyright 2024 the original author or authors. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -23,6 +23,7 @@ import kotlin.reflect.KProperty * Static factory method to create an Update using the provided key * * @author Pawel Matysek + * @since 4.4 * @see Update.update */ fun update(key: KProperty, value: T?) = @@ -32,6 +33,7 @@ fun update(key: KProperty, value: T?) = * Update using the {@literal $set} update modifier * * @author Pawel Matysek + * @since 4.4 * @see Update.set */ fun Update.set(key: KProperty, value: T?) = @@ -41,6 +43,7 @@ fun Update.set(key: KProperty, value: T?) = * Update using the {@literal $setOnInsert} update modifier * * @author Pawel Matysek + * @since 4.4 * @see Update.setOnInsert */ fun Update.setOnInsert(key: KProperty, value: T?) = @@ -50,6 +53,7 @@ fun Update.setOnInsert(key: KProperty, value: T?) = * Update using the {@literal $unset} update modifier * * @author Pawel Matysek + * @since 4.4 * @see Update.unset */ fun Update.unset(key: KProperty) = @@ -59,6 +63,7 @@ fun Update.unset(key: KProperty) = * Update using the {@literal $inc} update modifier * * @author Pawel Matysek + * @since 4.4 * @see Update.inc */ fun Update.inc(key: KProperty, inc: Number) = @@ -71,6 +76,7 @@ fun Update.inc(key: KProperty) = * Update using the {@literal $push} update modifier * * @author Pawel Matysek + * @since 4.4 * @see Update.push */ fun Update.push(key: KProperty>, value: T?) = @@ -79,9 +85,10 @@ fun Update.push(key: KProperty>, value: T?) = /** * Update using {@code $push} modifier.
* Allows creation of {@code $push} command for single or multiple (using {@code $each}) values as well as using - * * {@code $position}. + * * @author Pawel Matysek + * @since 4.4 * @see Update.push */ fun Update.push(key: KProperty) = @@ -92,6 +99,7 @@ fun Update.push(key: KProperty) = * Allows creation of {@code $push} command for single or multiple (using {@code $each}) values * {@code $position}. * * @author Pawel Matysek + * @since 4.4 * @see Update.addToSet */ fun Update.addToSet(key: KProperty) = @@ -101,6 +109,7 @@ fun Update.addToSet(key: KProperty) = * Update using the {@literal $addToSet} update modifier * * @author Pawel Matysek + * @since 4.4 * @see Update.addToSet */ fun Update.addToSet(key: KProperty>, value: T?) = @@ -110,6 +119,7 @@ fun Update.addToSet(key: KProperty>, value: T?) = * Update using the {@literal $pop} update modifier * * @author Pawel Matysek + * @since 4.4 * @see Update.pop */ fun Update.pop(key: KProperty, pos: Position) = @@ -119,6 +129,7 @@ fun Update.pop(key: KProperty, pos: Position) = * Update using the {@literal $pull} update modifier * * @author Pawel Matysek + * @since 4.4 * @see Update.pull */ fun Update.pull(key: KProperty, value: Any) = @@ -128,6 +139,7 @@ fun Update.pull(key: KProperty, value: Any) = * Update using the {@literal $pullAll} update modifier * * @author Pawel Matysek + * @since 4.4 * @see Update.pullAll */ fun Update.pullAll(key: KProperty>, values: Array) = @@ -137,6 +149,7 @@ fun Update.pullAll(key: KProperty>, values: Array) = * Update given key to current date using {@literal $currentDate} modifier. * * @author Pawel Matysek + * @since 4.4 * @see Update.currentDate */ fun Update.currentDate(key: KProperty) = @@ -146,6 +159,7 @@ fun Update.currentDate(key: KProperty) = * Update given key to current date using {@literal $currentDate : { $type : "timestamp" }} modifier. * * @author Pawel Matysek + * @since 4.4 * @see Update.currentTimestamp */ fun Update.currentTimestamp(key: KProperty) = @@ -155,6 +169,7 @@ fun Update.currentTimestamp(key: KProperty) = * Multiply the value of given key by the given number. * * @author Pawel Matysek + * @since 4.4 * @see Update.multiply */ fun Update.multiply(key: KProperty, multiplier: Number) = @@ -164,6 +179,7 @@ fun Update.multiply(key: KProperty, multiplier: Number) = * Update given key to the {@code value} if the {@code value} is greater than the current value of the field. * * @author Pawel Matysek + * @since 4.4 * @see Update.max */ fun Update.max(key: KProperty, value: T) = @@ -173,6 +189,7 @@ fun Update.max(key: KProperty, value: T) = * Update given key to the {@code value} if the {@code value} is less than the current value of the field. * * @author Pawel Matysek + * @since 4.4 * @see Update.min */ fun Update.min(key: KProperty, value: T) = @@ -182,6 +199,7 @@ fun Update.min(key: KProperty, value: T) = * The operator supports bitwise {@code and}, bitwise {@code or}, and bitwise {@code xor} operations. * * @author Pawel Matysek + * @since 4.4 * @see Update.bitwise */ fun Update.bitwise(key: KProperty) = @@ -192,6 +210,7 @@ fun Update.bitwise(key: KProperty) = * driver without further type or field mapping. * * @author Pawel Matysek + * @since 4.4 * @see Update.filterArray */ fun Update.filterArray(identifier: KProperty, expression: Any) = @@ -201,6 +220,7 @@ fun Update.filterArray(identifier: KProperty, expression: Any) = * Determine if a given {@code key} will be touched on execution. * * @author Pawel Matysek + * @since 4.4 * @see Update.modifies */ fun Update.modifies(key: KProperty) = diff --git a/spring-data-mongodb/src/test/kotlin/org/springframework/data/mongodb/core/query/TypedUpdateExtensionsTests.kt b/spring-data-mongodb/src/test/kotlin/org/springframework/data/mongodb/core/query/TypedUpdateExtensionsTests.kt index 994f629270..f40b180814 100644 --- a/spring-data-mongodb/src/test/kotlin/org/springframework/data/mongodb/core/query/TypedUpdateExtensionsTests.kt +++ b/spring-data-mongodb/src/test/kotlin/org/springframework/data/mongodb/core/query/TypedUpdateExtensionsTests.kt @@ -1,5 +1,5 @@ /* - * Copyright 2018-2024 the original author or authors. + * Copyright 2024 the original author or authors. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -27,7 +27,7 @@ import java.time.Instant */ class TypedUpdateExtensionsTests { - @Test + @Test // GH-3028 fun `update() should equal expected Update`() { val typed = update(Book::title, "Moby-Dick") @@ -36,7 +36,7 @@ class TypedUpdateExtensionsTests { assertThat(typed).isEqualTo(expected) } - @Test + @Test // GH-3028 fun `set() should equal expected Update`() { val typed = Update().set(Book::title, "Moby-Dick") @@ -45,7 +45,7 @@ class TypedUpdateExtensionsTests { assertThat(typed).isEqualTo(expected) } - @Test + @Test // GH-3028 fun `setOnInsert() should equal expected Update`() { val typed = Update().setOnInsert(Book::title, "Moby-Dick") @@ -54,7 +54,7 @@ class TypedUpdateExtensionsTests { assertThat(typed).isEqualTo(expected) } - @Test + @Test // GH-3028 fun `unset() should equal expected Update`() { val typed = Update().unset(Book::title) @@ -63,7 +63,7 @@ class TypedUpdateExtensionsTests { assertThat(typed).isEqualTo(expected) } - @Test + @Test // GH-3028 fun `inc(key, inc) should equal expected Update`() { val typed = Update().inc(Book::price, 5) @@ -72,7 +72,7 @@ class TypedUpdateExtensionsTests { assertThat(typed).isEqualTo(expected) } - @Test + @Test // GH-3028 fun `inc(key) should equal expected Update`() { val typed = Update().inc(Book::price) @@ -81,7 +81,7 @@ class TypedUpdateExtensionsTests { assertThat(typed).isEqualTo(expected) } - @Test + @Test // GH-3028 fun `push(key, value) should equal expected Update`() { val typed = Update().push(Book::categories, "someCategory") @@ -90,7 +90,7 @@ class TypedUpdateExtensionsTests { assertThat(typed).isEqualTo(expected) } - @Test + @Test // GH-3028 fun `push(key) should equal expected Update`() { val typed = Update().push(Book::categories) @@ -99,7 +99,7 @@ class TypedUpdateExtensionsTests { assertThat(typed).isEqualTo(expected) } - @Test + @Test // GH-3028 fun `addToSet(key) should equal expected Update`() { val typed = Update().addToSet(Book::categories).each("category", "category2") @@ -108,7 +108,7 @@ class TypedUpdateExtensionsTests { assertThat(typed).isEqualTo(expected) } - @Test + @Test // GH-3028 fun `addToSet(key, value) should equal expected Update`() { val typed = Update().addToSet(Book::categories, "someCategory") @@ -117,7 +117,7 @@ class TypedUpdateExtensionsTests { assertThat(typed).isEqualTo(expected) } - @Test + @Test // GH-3028 fun `pop() should equal expected Update`() { val typed = Update().pop(Book::categories, Update.Position.FIRST) @@ -126,7 +126,7 @@ class TypedUpdateExtensionsTests { assertThat(typed).isEqualTo(expected) } - @Test + @Test // GH-3028 fun `pull() should equal expected Update`() { val typed = Update().pull(Book::categories, "someCategory") @@ -135,7 +135,7 @@ class TypedUpdateExtensionsTests { assertThat(typed).isEqualTo(expected) } - @Test + @Test // GH-3028 fun `pullAll() should equal expected Update`() { val typed = Update().pullAll(Book::categories, arrayOf("someCategory", "someCategory2")) @@ -144,7 +144,7 @@ class TypedUpdateExtensionsTests { assertThat(typed).isEqualTo(expected) } - @Test + @Test // GH-3028 fun `currentDate() should equal expected Update`() { val typed = Update().currentDate(Book::releaseDate) @@ -153,7 +153,7 @@ class TypedUpdateExtensionsTests { assertThat(typed).isEqualTo(expected) } - @Test + @Test // GH-3028 fun `currentTimestamp() should equal expected Update`() { val typed = Update().currentTimestamp(Book::releaseDate) @@ -162,7 +162,7 @@ class TypedUpdateExtensionsTests { assertThat(typed).isEqualTo(expected) } - @Test + @Test // GH-3028 fun `multiply() should equal expected Update`() { val typed = Update().multiply(Book::price, 2) @@ -171,7 +171,7 @@ class TypedUpdateExtensionsTests { assertThat(typed).isEqualTo(expected) } - @Test + @Test // GH-3028 fun `max() should equal expected Update`() { val typed = Update().max(Book::price, 200) @@ -180,7 +180,7 @@ class TypedUpdateExtensionsTests { assertThat(typed).isEqualTo(expected) } - @Test + @Test // GH-3028 fun `min() should equal expected Update`() { val typed = Update().min(Book::price, 100) @@ -189,7 +189,7 @@ class TypedUpdateExtensionsTests { assertThat(typed).isEqualTo(expected) } - @Test + @Test // GH-3028 fun `bitwise() should equal expected Update`() { val typed = Update().bitwise(Book::price).and(2) @@ -198,7 +198,7 @@ class TypedUpdateExtensionsTests { assertThat(typed).isEqualTo(expected) } - @Test + @Test // GH-3028 fun `filterArray() should equal expected Update`() { val typed = Update().filterArray(Book::categories, "someCategory") @@ -207,7 +207,7 @@ class TypedUpdateExtensionsTests { assertThat(typed).isEqualTo(expected) } - @Test + @Test // GH-3028 fun `typed modifies() should equal expected modifies()`() { val typed = update(Book::title, "Moby-Dick") @@ -216,7 +216,7 @@ class TypedUpdateExtensionsTests { assertThat(typed.modifies(Book::price)).isEqualTo(typed.modifies("price")) } - @Test + @Test // GH-3028 fun `One level nested should equal expected Update`() { val typed = update(Book::author / Author::name, "Herman Melville") @@ -225,7 +225,7 @@ class TypedUpdateExtensionsTests { assertThat(typed).isEqualTo(expected) } - @Test + @Test // GH-3028 fun `Two levels nested should equal expected Update`() { data class Entity(val book: Book) diff --git a/src/main/antora/antora-playbook.yml b/src/main/antora/antora-playbook.yml index 183d4036d6..e04a7a4188 100644 --- a/src/main/antora/antora-playbook.yml +++ b/src/main/antora/antora-playbook.yml @@ -17,7 +17,7 @@ content: - url: https://github.com/spring-projects/spring-data-commons # Refname matching: # https://docs.antora.org/antora/latest/playbook/content-refname-matching/ - branches: [ main, 3.2.x ] + branches: [ main, 3.3.x, 3.2.x] start_path: src/main/antora asciidoc: attributes: diff --git a/src/main/antora/modules/ROOT/pages/kotlin/extensions.adoc b/src/main/antora/modules/ROOT/pages/kotlin/extensions.adoc index 8c03fa176e..381a48be13 100644 --- a/src/main/antora/modules/ROOT/pages/kotlin/extensions.adoc +++ b/src/main/antora/modules/ROOT/pages/kotlin/extensions.adoc @@ -19,7 +19,7 @@ val characters : Flux = template.query().inTable("star-wars").all() As in Java, `characters` in Kotlin is strongly typed, but Kotlin's clever type inference allows for shorter syntax. [[mongo.query.kotlin-support]] -== Type-safe Queries and Updates for Kotlin +== Type-safe Queries for Kotlin Kotlin embraces domain-specific language creation through its language syntax and its extension system. Spring Data MongoDB ships with a Kotlin Extension for `Criteria` using https://kotlinlang.org/docs/reference/reflection.html#property-references[Kotlin property references] to build type-safe queries. @@ -64,7 +64,11 @@ mongoOperations.find( <3> To construct nested properties, use the `/` character (overloaded operator `div`). ==== -Similar syntax can be used while updating a document: +[[mongo.update.kotlin-support]] +== Type-safe Updates for Kotlin + +A syntax similar to <> can be used to update documents: + ==== [source,kotlin] ----