Merge branch 'v3.4.x' of https://github.com/vincentlauvlwj/Ktorm into v3.4.x

Author: vincentlauvlwj

detekt.yml

@@ -50,7 +50,7 @@ complexity:
     threshold: 4
   ComplexInterface:
     active: true
-    threshold: 11
+    threshold: 12
     includeStaticDeclarations: false
   ComplexMethod:
     active: true

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

@@ -44,11 +44,11 @@ import kotlin.reflect.jvm.jvmErasure
  *
  * ### Creating Entity Objects
  *
- * As everyone knows, interfaces cannot be instantiated, so Ktorm provides [Entity.create] functions for us to
- * create entity objects. Those functions generate implementations for entity interfaces via JDK dynamic proxy
+ * As everyone knows, interfaces cannot be instantiated, so Ktorm provides a [Entity.create] function for us to
+ * create entity objects. This function generate implementations for entity interfaces via JDK dynamic proxy
  * and create their instances.
  *
- * If you don't like creating objects by [Entity.create] functions, Ktorm also provides an abstract factory class
+ * In case you don't like creating objects by [Entity.create], Ktorm also provides an abstract factory class
  * [Entity.Factory]. This class overloads the `invoke` operator of Kotlin, so we just need to add a companion
  * object to our entity class extending from [Entity.Factory], then entity objects can be created just like there
  * is a constructor: `val department = Department()`.
@@ -71,7 +71,7 @@ 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 the [String] type, the default value is the empty string.
+ * - 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.
@@ -150,15 +150,14 @@ public interface Entity<E : Entity<E>> : Serializable {
      * Using this function, we need to note that:
      *
      * 1. This function requires a primary key specified in the table object via [Table.primaryKey],
-     * otherwise Ktorm doesn’t know how to identify entity objects, then throws an exception.
+     * otherwise Ktorm doesn’t know how to identify entity objects and will throw an exception.
      *
-     * 2. The entity object calling this function must **be associated with a table** first. In Ktorm’s implementation,
-     * every entity object holds a reference `fromTable`, that means this object is associated with the table or was
-     * obtained from it. For entity objects obtained by sequence APIs, their `fromTable` references point to the current
-     * table object they are obtained from. But for entity objects created by [Entity.create] or [Entity.Factory], their
-     * `fromTable` references are `null` initially, so we can not call [flushChanges] on them. But once we use them with
-     * [add] or [update] function of entity sequences, Ktorm will modify their `fromTable` to the current table object,
-     * then we can call [flushChanges] on them afterwards.
+     * 2. The entity object calling this function must be ATTACHED to the database first. In Ktorm’s implementation,
+     * every entity object holds a reference `fromDatabase`. For entity objects obtained by sequence APIs, their
+     * `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.
      *
      * @see add
      * @see update
@@ -182,7 +181,7 @@ public interface Entity<E : Entity<E>> : Serializable {
      * 1. The function requires a primary key specified in the table object via [Table.primaryKey],
      * otherwise, Ktorm doesn’t know how to identify entity objects.
      *
-     * 2. The entity object calling this function must **be associated with a table** first.
+     * 2. The entity object calling this function must be ATTACHED to the database first.
      *
      * @see add
      * @see update
@@ -209,6 +208,27 @@ public interface Entity<E : Entity<E>> : Serializable {
      */
     public fun copy(): E
 
+    /**
+     * Indicate whether some other object is "equal to" this entity.
+     * Two entities are equal only if they have the same [entityClass] and [properties].
+     *
+     * @since 3.4.0
+     */
+    public override fun equals(other: Any?): Boolean
+
+    /**
+     * Return a hash code value for this entity.
+     *
+     * @since 3.4.0
+     */
+    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}`.
+     */
+    public override fun toString(): String
+
     /**
      * Companion object provides functions to create entity instances.
      */

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

@@ -30,7 +30,7 @@ import org.ktorm.schema.*
  * not to set the primary key’s value beforehand, otherwise, if you do that, the given value will be inserted
  * into the database, and no keys generated.
  *
- * Note that after calling this function, the [entity] will **be associated with the current table**.
+ * Note that after calling this function, the [entity] will be ATTACHED to the current database.
  *
  * @see Entity.flushChanges
  * @see Entity.delete
@@ -91,7 +91,7 @@ public fun <E : Entity<E>, T : Table<E>> EntitySequence<E, T>.add(entity: E): In
 /**
  * Update properties of the given entity to the database and return the affected record number.
  *
- * Note that after calling this function, the [entity] will **be associated with the current table**.
+ * Note that after calling this function, the [entity] will be ATTACHED to the current database.
  *
  * @see Entity.flushChanges
  * @see Entity.delete
@@ -148,10 +148,10 @@ public fun <E : Any, T : BaseTable<E>> EntitySequence<E, T>.clear(): Int {
 
 @Suppress("UNCHECKED_CAST")
 internal fun EntityImplementation.doFlushChanges(): Int {
-    check(parent == null) { "The entity is not associated with any database yet." }
+    check(parent == null) { "The entity is not attached to any database yet." }
 
-    val fromDatabase = fromDatabase ?: error("The entity is not associated with any database yet.")
-    val fromTable = fromTable ?: error("The entity is not associated with any table yet.")
+    val fromDatabase = fromDatabase ?: error("The entity is not attached to any database yet.")
+    val fromTable = fromTable ?: error("The entity is not attached to any database yet.")
     checkUnexpectedDiscarding(fromTable)
 
     val assignments = findChangedColumns(fromTable).takeIf { it.isNotEmpty() } ?: return 0
@@ -174,10 +174,10 @@ internal fun EntityImplementation.doFlushChanges(): Int {
 
 @Suppress("UNCHECKED_CAST")
 internal fun EntityImplementation.doDelete(): Int {
-    check(parent == null) { "The entity is not associated with any database yet." }
+    check(parent == null) { "The entity is not attached to any database yet." }
 
-    val fromDatabase = fromDatabase ?: error("The entity is not associated with any database yet.")
-    val fromTable = fromTable ?: error("The entity is not associated with any table yet.")
+    val fromDatabase = fromDatabase ?: error("The entity is not attached to any database yet.")
+    val fromTable = fromTable ?: error("The entity is not attached to any database yet.")
 
     val expression = AliasRemover.visit(
         expr = DeleteExpression(
@@ -272,8 +272,8 @@ private fun EntityImplementation.findChangedColumns(fromTable: Table<*>): Map<Co
 }
 
 internal fun EntityImplementation.doDiscardChanges() {
-    check(parent == null) { "The entity is not associated with any database yet." }
-    val fromTable = fromTable ?: error("The entity is not associated with any table yet.")
+    check(parent == null) { "The entity is not attached to any database yet." }
+    val fromTable = fromTable ?: error("The entity is not attached to any database yet.")
 
     for (column in fromTable.columns) {
         val binding = column.binding ?: continue

ktorm-core/src/test/kotlin/org/ktorm/entity/EntityTest.kt

@@ -522,7 +522,8 @@ class EntityTest : BaseTest() {
         val employee = database.employees.find { it.id eq 2 } ?: return
         val copy = employee.copy()
 
-        assert(employee.hireDate == copy.hireDate)
+        assert(employee == copy)
+        assert(employee !== copy)
         assert(employee.hireDate !== copy.hireDate) // should not be the same instance because of deep copy.
         assert(copy.manager?.implementation?.parent === copy.implementation) // should keep the parent relationship.
     }

ktorm-global/src/main/kotlin/org/ktorm/global/EntitySequence.kt

@@ -30,16 +30,15 @@ public fun <E : Any, T : BaseTable<E>> T.asSequence(withReferences: Boolean = tr
 }
 
 /**
- * Insert the given entity into this table and return the affected record number. Only non-null properties
- * are inserted.
+ * Insert the given entity into this sequence and return the affected record number.
  *
  * If we use an auto-increment key in our table, we need to tell Ktorm which is the primary key by calling
- * [Table.primaryKey] function while registering columns, then this function will obtain the generated key
- * from the database and fill it into the corresponding property after the insertion completes. But this
- * requires us not to set the primary key’s value beforehand, otherwise, if you do that, the given value
- * will be inserted into the database, and no keys generated.
+ * [Table.primaryKey] while registering columns, then this function will obtain the generated key from the
+ * database and fill it into the corresponding property after the insertion completes. But this requires us
+ * not to set the primary key’s value beforehand, otherwise, if you do that, the given value will be inserted
+ * into the database, and no keys generated.
  *
- * Note that after calling this function, the [entity] will **be associated with the current table**.
+ * Note that after calling this function, the [entity] will be ATTACHED to the current database.
  *
  * @see Entity.flushChanges
  * @see Entity.delete
@@ -53,16 +52,15 @@ public fun <E : Entity<E>> Table<E>.add(entity: E): Int {
 }
 
 /**
- * Insert the given entity into this table and return the affected record number. Only non-null properties
- * are inserted.
+ * Insert the given entity into this sequence and return the affected record number.
  *
  * If we use an auto-increment key in our table, we need to tell Ktorm which is the primary key by calling
- * [Table.primaryKey] function while registering columns, then this function will obtain the generated key
- * from the database and fill it into the corresponding property after the insertion completes. But this
- * requires us not to set the primary key’s value beforehand, otherwise, if you do that, the given value
- * will be inserted into the database, and no keys generated.
+ * [Table.primaryKey] while registering columns, then this function will obtain the generated key from the
+ * database and fill it into the corresponding property after the insertion completes. But this requires us
+ * not to set the primary key’s value beforehand, otherwise, if you do that, the given value will be inserted
+ * into the database, and no keys generated.
  *
- * Note that after calling this function, the [entity] will **be associated with the current table**.
+ * Note that after calling this function, the [entity] will be ATTACHED to the current database.
  *
  * @see Entity.flushChanges
  * @see Entity.delete
@@ -72,9 +70,9 @@ public fun <E : Entity<E>> Table<E>.addEntity(entity: E): Int {
 }
 
 /**
- * Update the non-null properties of the given entity to the database and return the affected record number.
+ * Update properties of the given entity to the database and return the affected record number.
  *
- * Note that after calling this function, the [entity] will **be associated with the current table**.
+ * Note that after calling this function, the [entity] will be ATTACHED to the current database.
  *
  * @see Entity.flushChanges
  * @see Entity.delete