chore!: Raise deprecation level of OptionalReferrers (#2325)

Author: joc-a

documentation-website/Writerside/topics/Breaking-Changes.md

@@ -24,6 +24,7 @@
   -- Starting from version 0.57.0
   INSERT INTO TEST DEFAULT VALUES
   ```
+* The `OptionalReferrers` class is now deprecated as it is a complete duplicate of the `Referrers` class; therefore, the latter should be used instead.
 
 ## 0.56.0
 * If the `distinct` parameter of `groupConcat()` is set to `true`, when using Oracle or SQL Server, this will now fail early with an

exposed-dao/api/exposed-dao.api

@@ -146,12 +146,12 @@ public abstract class org/jetbrains/exposed/dao/EntityClass {
 	public final fun optionalBackReferencedOnOpt (Lorg/jetbrains/exposed/dao/EntityClass;Lorg/jetbrains/exposed/sql/Column;)Lorg/jetbrains/exposed/dao/OptionalBackReference;
 	public final fun optionalReferencedOn (Lorg/jetbrains/exposed/dao/id/IdTable;)Lorg/jetbrains/exposed/dao/OptionalReference;
 	public final fun optionalReferencedOn (Lorg/jetbrains/exposed/sql/Column;)Lorg/jetbrains/exposed/dao/OptionalReference;
-	public final fun optionalReferrersOn (Lorg/jetbrains/exposed/dao/EntityClass;Lorg/jetbrains/exposed/dao/id/IdTable;)Lorg/jetbrains/exposed/dao/OptionalReferrers;
-	public final fun optionalReferrersOn (Lorg/jetbrains/exposed/dao/EntityClass;Lorg/jetbrains/exposed/dao/id/IdTable;Z)Lorg/jetbrains/exposed/dao/OptionalReferrers;
-	public final fun optionalReferrersOn (Lorg/jetbrains/exposed/dao/EntityClass;Lorg/jetbrains/exposed/sql/Column;)Lorg/jetbrains/exposed/dao/OptionalReferrers;
-	public final fun optionalReferrersOn (Lorg/jetbrains/exposed/dao/EntityClass;Lorg/jetbrains/exposed/sql/Column;Z)Lorg/jetbrains/exposed/dao/OptionalReferrers;
-	public static synthetic fun optionalReferrersOn$default (Lorg/jetbrains/exposed/dao/EntityClass;Lorg/jetbrains/exposed/dao/EntityClass;Lorg/jetbrains/exposed/dao/id/IdTable;ZILjava/lang/Object;)Lorg/jetbrains/exposed/dao/OptionalReferrers;
-	public static synthetic fun optionalReferrersOn$default (Lorg/jetbrains/exposed/dao/EntityClass;Lorg/jetbrains/exposed/dao/EntityClass;Lorg/jetbrains/exposed/sql/Column;ZILjava/lang/Object;)Lorg/jetbrains/exposed/dao/OptionalReferrers;
+	public final fun optionalReferrersOn (Lorg/jetbrains/exposed/dao/EntityClass;Lorg/jetbrains/exposed/dao/id/IdTable;)Lorg/jetbrains/exposed/dao/Referrers;
+	public final fun optionalReferrersOn (Lorg/jetbrains/exposed/dao/EntityClass;Lorg/jetbrains/exposed/dao/id/IdTable;Z)Lorg/jetbrains/exposed/dao/Referrers;
+	public final fun optionalReferrersOn (Lorg/jetbrains/exposed/dao/EntityClass;Lorg/jetbrains/exposed/sql/Column;)Lorg/jetbrains/exposed/dao/Referrers;
+	public final fun optionalReferrersOn (Lorg/jetbrains/exposed/dao/EntityClass;Lorg/jetbrains/exposed/sql/Column;Z)Lorg/jetbrains/exposed/dao/Referrers;
+	public static synthetic fun optionalReferrersOn$default (Lorg/jetbrains/exposed/dao/EntityClass;Lorg/jetbrains/exposed/dao/EntityClass;Lorg/jetbrains/exposed/dao/id/IdTable;ZILjava/lang/Object;)Lorg/jetbrains/exposed/dao/Referrers;
+	public static synthetic fun optionalReferrersOn$default (Lorg/jetbrains/exposed/dao/EntityClass;Lorg/jetbrains/exposed/dao/EntityClass;Lorg/jetbrains/exposed/sql/Column;ZILjava/lang/Object;)Lorg/jetbrains/exposed/dao/Referrers;
 	public final fun referencedOn (Lorg/jetbrains/exposed/dao/id/IdTable;)Lorg/jetbrains/exposed/dao/Reference;
 	public final fun referencedOn (Lorg/jetbrains/exposed/sql/Column;)Lorg/jetbrains/exposed/dao/Reference;
 	public final fun referrersOn (Lorg/jetbrains/exposed/dao/EntityClass;Lorg/jetbrains/exposed/dao/id/IdTable;)Lorg/jetbrains/exposed/dao/Referrers;

exposed-dao/src/main/kotlin/org/jetbrains/exposed/dao/EntityClass.kt

@@ -654,7 +654,7 @@ abstract class EntityClass<ID : Any, out T : Entity<ID>>(
     infix fun <TargetID : Any, Target : Entity<TargetID>, REF : Any> EntityClass<TargetID, Target>.optionalReferrersOn(
         column: Column<REF?>
     ) =
-        registerRefRule(column) { OptionalReferrers<ID, Entity<ID>, TargetID, Target, REF>(column, this, true) }
+        registerRefRule(column) { Referrers<ID, Entity<ID>, TargetID, Target, REF?>(column, this, true) }
 
     /**
      * Registers an optional reference as an immutable field of the parent entity class, which returns a collection of
@@ -671,10 +671,10 @@ abstract class EntityClass<ID : Any, out T : Entity<ID>>(
      */
     infix fun <TargetID : Any, Target : Entity<TargetID>> EntityClass<TargetID, Target>.optionalReferrersOn(
         table: IdTable<*>
-    ): OptionalReferrers<ID, Entity<ID>, TargetID, Target, Any> {
+    ): Referrers<ID, Entity<ID>, TargetID, Target, Any?> {
         val tableFK = this@EntityClass.getCompositeForeignKey(table)
         val delegate = tableFK.from.first() as Column<Any?>
-        return registerRefRule(delegate) { OptionalReferrers(delegate, this, true, tableFK.references) }
+        return registerRefRule(delegate) { Referrers(delegate, this, true, tableFK.references) }
     }
 
     /**
@@ -694,7 +694,7 @@ abstract class EntityClass<ID : Any, out T : Entity<ID>>(
         column: Column<REF?>,
         cache: Boolean = false
     ) =
-        registerRefRule(column) { OptionalReferrers<ID, Entity<ID>, TargetID, Target, REF>(column, this, cache) }
+        registerRefRule(column) { Referrers<ID, Entity<ID>, TargetID, Target, REF?>(column, this, cache) }
 
     /**
      * Registers an optional reference as an immutable field of the parent entity class, which returns a collection of
@@ -708,10 +708,10 @@ abstract class EntityClass<ID : Any, out T : Entity<ID>>(
     fun <TargetID : Any, Target : Entity<TargetID>> EntityClass<TargetID, Target>.optionalReferrersOn(
         table: IdTable<*>,
         cache: Boolean = false
-    ): OptionalReferrers<ID, Entity<ID>, TargetID, Target, Any> {
+    ): Referrers<ID, Entity<ID>, TargetID, Target, Any?> {
         val tableFK = this@EntityClass.getCompositeForeignKey(table)
         val delegate = tableFK.from.first() as Column<Any?>
-        return registerRefRule(delegate) { OptionalReferrers(delegate, this, cache, tableFK.references) }
+        return registerRefRule(delegate) { Referrers(delegate, this, cache, tableFK.references) }
     }
 
     /**

exposed-dao/src/main/kotlin/org/jetbrains/exposed/dao/References.kt

@@ -84,7 +84,7 @@ class OptionalBackReference<ParentID : Any, out Parent : Entity<ParentID>, Child
     factory: EntityClass<ParentID, Parent>,
     references: Map<Column<*>, Column<*>>? = null
 ) : ReadOnlyProperty<Child, Parent?> {
-    internal val delegate = OptionalReferrers<ChildID, Child, ParentID, Parent, REF>(reference, factory, true, references)
+    internal val delegate = Referrers<ChildID, Child, ParentID, Parent, REF?>(reference, factory, true, references)
 
     override operator fun getValue(thisRef: Child, property: KProperty<*>) =
         delegate.getValue(thisRef.apply { thisRef.id.value }, property).singleOrNull() // flush entity before to don't miss newly created entities
@@ -190,7 +190,7 @@ open class Referrers<ParentID : Any, in Parent : Entity<ParentID>, ChildID : Any
 @Deprecated(
     message = "The OptionalReferrers class is a complete duplicate of the Referrers class; therefore, the latter should be used instead.",
     replaceWith = ReplaceWith("Referrers"),
-    level = DeprecationLevel.WARNING
+    level = DeprecationLevel.ERROR
 )
 class OptionalReferrers<ParentID : Any, in Parent : Entity<ParentID>, ChildID : Any, out Child : Entity<ChildID>, REF>(
     reference: Column<REF?>,
@@ -345,7 +345,7 @@ private fun <ID : Any> List<Entity<ID>>.preloadRelations(
                 }
             }
             is OptionalBackReference<*, *, *, *, *> -> {
-                (refObject.delegate as OptionalReferrers<ID, Entity<ID>, *, Entity<*>, Any>).allReferences.let { refColumns ->
+                (refObject.delegate as Referrers<ID, Entity<ID>, *, Entity<*>, Any?>).allReferences.let { refColumns ->
                     val delegateRefColumn = refObject.delegate.reference
                     if (hasSingleReferenceWithReferee(refColumns)) {
                         val refIds = this.map { it.run { delegateRefColumn.referee<Any>()!!.lookup() } }