Merge pull request #567 from kotlin-orm/dev

Release 4.1.0

.github/workflows/build.yml

@@ -14,19 +14,19 @@ jobs:
     strategy:
       fail-fast: true
       matrix:
-        java: [8, 11, 17, 20]
+        java: [8, 11, 17, 21]
     steps:
       - name: Checkout Code
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Setup Java
-        uses: actions/setup-java@v3
+        uses: actions/setup-java@v4
         with:
           distribution: zulu
           java-version: ${{ matrix.java }}
 
       - name: Setup Gradle
-        uses: gradle/gradle-build-action@v2
+        uses: gradle/actions/setup-gradle@v3
 
       - name: Assemble the Project
         run: ./gradlew assemble
@@ -45,6 +45,8 @@ jobs:
             ktorm-core/build/reports/jacoco/test/jacocoTestReport.csv
             ktorm-global/build/reports/jacoco/test/jacocoTestReport.csv
             ktorm-jackson/build/reports/jacoco/test/jacocoTestReport.csv
+            ktorm-ksp-annotations/build/reports/jacoco/test/jacocoTestReport.csv
+            ktorm-ksp-compiler/build/reports/jacoco/test/jacocoTestReport.csv
             ktorm-support-mysql/build/reports/jacoco/test/jacocoTestReport.csv
             ktorm-support-oracle/build/reports/jacoco/test/jacocoTestReport.csv
             ktorm-support-postgresql/build/reports/jacoco/test/jacocoTestReport.csv
@@ -78,16 +80,16 @@ jobs:
     needs: build
     steps:
       - name: Checkout Code
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Setup Java
-        uses: actions/setup-java@v3
+        uses: actions/setup-java@v4
         with:
           distribution: zulu
           java-version: 8
 
       - name: Setup Gradle
-        uses: gradle/gradle-build-action@v2
+        uses: gradle/actions/setup-gradle@v3
 
       - name: Assemble the Project
         run: ./gradlew assemble

README.md

@@ -260,7 +260,7 @@ object Employees : Table<Employee>("t_employee") {
 }
 ```
 
-> Naming Strategy: It's highly recommended to name your entity classes by singular nouns, name table objects by plurals (eg. Employee/Employees, Department/Departments). 
+> Naming Strategy: It's highly recommended to name your entity classes by singular nouns, name table objects by plurals (e.g. Employee/Employees, Department/Departments). 
 
 Now that column bindings are configured, so we can use [sequence APIs](#Entity-Sequence-APIs) to perform many operations on entities. Let's add two extension properties for `Database` first. These properties return new created sequence objects via `sequenceOf` and they can help us improve the readability of the code: 
 

buildSrc/build.gradle.kts

@@ -9,7 +9,7 @@ repositories {
 }
 
 dependencies {
-    api("org.jetbrains.kotlin:kotlin-gradle-plugin:1.9.0")
-    api("org.moditect:moditect-gradle-plugin:1.0.0-rc3")
-    api("io.gitlab.arturbosch.detekt:detekt-gradle-plugin:1.23.1")
+    api("org.jetbrains.kotlin:kotlin-gradle-plugin:1.9.23")
+    api("org.moditect:moditect:1.0.0.RC1")
+    api("io.gitlab.arturbosch.detekt:detekt-gradle-plugin:1.23.6")
 }

buildSrc/src/main/kotlin/ktorm.modularity.gradle.kts

@@ -1,30 +1,37 @@
 
 plugins {
     id("kotlin")
-    id("org.moditect.gradleplugin")
 }
 
-moditect {
-    // Generate a multi-release jar, the module descriptor will be located at META-INF/versions/9/module-info.class
-    addMainModuleInfo {
-        jvmVersion.set("9")
-        overwriteExistingFiles.set(true)
-        module {
-            moduleInfoFile = file("src/main/moditect/module-info.java")
+val moditect by tasks.registering {
+    doLast {
+        // Generate a multi-release modulized jar, module descriptor position: META-INF/versions/9/module-info.class
+        val inputJar = tasks.jar.flatMap { it.archiveFile }.map { it.asFile.toPath() }.get()
+        val outputDir = file("build/moditect").apply { mkdirs() }.toPath()
+        val moduleInfo = file("src/main/moditect/module-info.java").readText()
+        val version = project.version.toString()
+        org.moditect.commands.AddModuleInfo(moduleInfo, null, version, inputJar, outputDir, "9", true).run()
+
+        // Replace the original jar with the modulized jar.
+        copy {
+            from(outputDir.resolve(inputJar.fileName))
+            into(inputJar.parent)
         }
     }
+}
 
-    // Let kotlin compiler know the module descriptor.
-    if (JavaVersion.current() >= JavaVersion.VERSION_1_9) {
-        sourceSets.main {
-            kotlin.srcDir("src/main/moditect")
-        }
+tasks {
+    moditect {
+        dependsOn(jar)
     }
+    jar {
+        finalizedBy(moditect)
+    }
+}
 
-    // Workaround to avoid circular task dependencies, see https://github.com/moditect/moditect-gradle-plugin/issues/14
-    afterEvaluate {
-        val compileJava = tasks.compileJava.get()
-        val addDependenciesModuleInfo = tasks.addDependenciesModuleInfo.get()
-        compileJava.setDependsOn(compileJava.dependsOn - addDependenciesModuleInfo)
+if (JavaVersion.current() >= JavaVersion.VERSION_1_9) {
+    // Let kotlin compiler know the module descriptor.
+    sourceSets.main {
+        kotlin.srcDir("src/main/moditect")
     }
 }

buildSrc/src/main/kotlin/ktorm.publish.gradle.kts

@@ -155,6 +155,11 @@ publishing {
                         id.set("brohacz")
                         name.set("Michal Brosig")
                     }
+                    developer {
+                        id.set("hc224")
+                        name.set("hc224")
+                        email.set("[email protected]")
+                    }
                 }
             }
         }

detekt.yml

@@ -49,7 +49,7 @@ complexity:
     active: true
     threshold: 4
   ComplexInterface:
-    active: true
+    active: false
     threshold: 12
     includeStaticDeclarations: false
   CyclomaticComplexMethod:
@@ -75,7 +75,7 @@ complexity:
     active: false
     threshold: 7
   NestedBlockDepth:
-    active: true
+    active: false
     threshold: 5
   StringLiteralDuplication:
     active: false

gradle/wrapper/gradle-wrapper.properties

@@ -1,5 +1,5 @@
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-8.3-all.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.9-all.zip
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists

ktorm-core/ktorm-core.gradle.kts

@@ -19,7 +19,7 @@ val testOutput by configurations.creating {
 }
 
 val testJar by tasks.registering(Jar::class) {
-    dependsOn("testClasses")
+    dependsOn(tasks.testClasses)
     from(sourceSets.test.map { it.output })
     archiveClassifier.set("test")
 }

ktorm-core/src/main/kotlin/org/ktorm/database/CachedRowSet.kt

@@ -609,6 +609,7 @@ public open class CachedRowSet(rs: ResultSet) : ResultSet {
                 return index
             }
         }
+
         throw SQLException("Invalid column name: $columnLabel")
     }
 

ktorm-core/src/main/kotlin/org/ktorm/database/Database.kt

@@ -147,7 +147,7 @@ public class Database(
     public val name: String
 
     /**
-     * The name of the connected database product, eg. MySQL, H2.
+     * The name of the connected database product, e.g. MySQL, H2.
      */
     public val productName: String
 

ktorm-core/src/main/kotlin/org/ktorm/entity/Entity.kt

@@ -23,6 +23,7 @@ import java.io.ObjectInputStream
 import java.io.ObjectOutputStream
 import java.io.Serializable
 import java.lang.reflect.Proxy
+import java.sql.SQLException
 import kotlin.reflect.KClass
 import kotlin.reflect.full.isSubclassOf
 import kotlin.reflect.jvm.jvmErasure
@@ -69,12 +70,12 @@ import kotlin.reflect.jvm.jvmErasure
  *
  * - For [Boolean] type, the default value is `false`.
  * - For [Char] type, the default value is `\u0000`.
- * - For number types (such as [Int], [Long], [Double], etc), the default value is zero.
+ * - For number types (such as [Int], [Long], [Double], etc.), the default value is zero.
  * - For [String] type, the default value is an empty string.
  * - For entity types, the default value is a new-created entity object which is empty.
  * - For enum types, the default value is the first value of the enum, whose ordinal is 0.
  * - For array types, the default value is a new-created empty array.
- * - For collection types (such as [Set], [List], [Map], etc), the default value is a new created mutable collection
+ * - For collection types (such as [Set], [List], [Map], etc.), the default value is a new created mutable collection
  * of the concrete type.
  * - For any other types, the default value is an instance created by its no-args constructor. If the constructor
  * doesn't exist, an exception is thrown.
@@ -128,7 +129,7 @@ import kotlin.reflect.jvm.jvmErasure
  * refer to their documentation for more details.
  *
  * Besides of JDK serialization, the ktorm-jackson module also supports serializing entities in JSON format. This
- * module provides an extension for Jackson, the famous JSON framework in Java word. It supports serializing entity
+ * module provides an extension for Jackson, the famous JSON framework in Java world. It supports serializing entity
  * objects into JSON format and parsing JSONs as entity objects. More details can be found in its documentation.
  */
 public interface Entity<E : Entity<E>> : Serializable {
@@ -143,6 +144,13 @@ public interface Entity<E : Entity<E>> : Serializable {
      */
     public val properties: Map<String, Any?>
 
+    /**
+     * Return the immutable view of this entity's changed properties and their original values.
+     *
+     * @since 4.1.0
+     */
+    public val changedProperties: Map<String, Any?>
+
     /**
      * Update the property changes of this entity into the database and return the affected record number.
      *
@@ -156,18 +164,18 @@ public interface Entity<E : Entity<E>> : Serializable {
      * `fromDatabase` references point to the database they are obtained from. For entity objects created by
      * [Entity.create] or [Entity.Factory], their `fromDatabase` references are `null` initially, so we can not call
      * [flushChanges] on them. But once we use them with [add] or [update] function, `fromDatabase` will be modified
-     * to the current database, so we will be able to call [flushChanges] on them afterwards.
+     * to the current database, so we will be able to call [flushChanges] on them afterward.
      *
      * @see add
      * @see update
      */
+    @Throws(SQLException::class)
     public fun flushChanges(): Int
 
     /**
      * Clear the tracked property changes of this entity.
      *
-     * After calling this function, the [flushChanges] doesn't do anything anymore because the property changes
-     * are discarded.
+     * After calling this function, [flushChanges] will do nothing because property changes are discarded.
      */
     public fun discardChanges()
 
@@ -185,13 +193,14 @@ public interface Entity<E : Entity<E>> : Serializable {
      * @see update
      * @see flushChanges
      */
+    @Throws(SQLException::class)
     public fun delete(): Int
 
     /**
      * Obtain a property's value by its name.
      *
      * Note that this function doesn't follow the rules of default values discussed in the class level documentation.
-     * If the value doesn't exist, we will return `null` simply.
+     * If the value doesn't exist, it will simply return `null`.
      */
     public operator fun get(name: String): Any?
 
@@ -221,8 +230,8 @@ public interface Entity<E : Entity<E>> : Serializable {
     public override fun hashCode(): Int
 
     /**
-     * Return a string representation of this table.
-     * The format is like `Employee{id=1, name=Eric, job=contributor, hireDate=2021-05-05, salary=50}`.
+     * Return a string representation of this entity.
+     * The format is like `Employee(id=1, name=Eric, job=contributor, hireDate=2021-05-05, salary=50)`.
      */
     public override fun toString(): String