Implement SuperTableClass annotation

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

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

ktorm-ksp-annotations/src/main/kotlin/org/ktorm/ksp/annotation/SuperTableClass.kt

@@ -0,0 +1,38 @@
+/*
+ * Copyright 2018-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.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.ktorm.ksp.annotation
+
+import org.ktorm.schema.BaseTable
+import kotlin.reflect.KClass
+
+/**
+ * Be used on Entity interface, to specify the super table class for the table class generated.
+ * @property value the super table class, which should be a subclass of `org.ktorm.schema.BaseTable`
+ * the `tableName` and `alias` parameters be required on primary constructor, other parameters are optional.
+ *
+ * if not specified, the super table class will be determined by the kind of the entity class.
+ * `org.ktorm.schema.Table` for interface, `org.ktorm.schema.BaseTable` for class.
+ *
+ * If there are multiple `SuperTableClass` on the inheritance hierarchy of entity,
+ * and they have an inheritance relationship, the super table class will be the last one of them.
+ * and they don't have an inheritance relationship, an error will be reported.
+ */
+@Target(AnnotationTarget.CLASS)
+@Retention(AnnotationRetention.SOURCE)
+public annotation class SuperTableClass(
+    public val value: KClass<out BaseTable<out Any>>
+)

ktorm-ksp-compiler/src/main/kotlin/org/ktorm/ksp/compiler/generator/TableClassGenerator.kt

@@ -28,9 +28,7 @@ import org.ktorm.ksp.compiler.util._type
 import org.ktorm.ksp.compiler.util.getKotlinType
 import org.ktorm.ksp.compiler.util.getRegisteringCodeBlock
 import org.ktorm.ksp.spi.TableMetadata
-import org.ktorm.schema.BaseTable
 import org.ktorm.schema.Column
-import org.ktorm.schema.Table
 
 @OptIn(KotlinPoetKspPreview::class)
 internal object TableClassGenerator {
@@ -49,11 +47,7 @@ internal object TableClassGenerator {
     }
 
     private fun TypeSpec.Builder.configureSuperClass(table: TableMetadata): TypeSpec.Builder {
-        if (table.entityClass.classKind == ClassKind.INTERFACE) {
-            superclass(Table::class.asClassName().parameterizedBy(table.entityClass.toClassName()))
-        } else {
-            superclass(BaseTable::class.asClassName().parameterizedBy(table.entityClass.toClassName()))
-        }
+        superclass(table.superClass.parameterizedBy(table.entityClass.toClassName()))
 
         addSuperclassConstructorParameter("%S", table.name)
         addSuperclassConstructorParameter("alias")

ktorm-ksp-compiler/src/main/kotlin/org/ktorm/ksp/compiler/parser/MetadataParser.kt

@@ -21,6 +21,10 @@ import com.google.devtools.ksp.processing.Resolver
 import com.google.devtools.ksp.processing.SymbolProcessorEnvironment
 import com.google.devtools.ksp.symbol.*
 import com.google.devtools.ksp.symbol.ClassKind.*
+import com.squareup.kotlinpoet.ClassName
+import com.squareup.kotlinpoet.asClassName
+import com.squareup.kotlinpoet.ksp.KotlinPoetKspPreview
+import com.squareup.kotlinpoet.ksp.toClassName
 import org.ktorm.entity.Entity
 import org.ktorm.ksp.annotation.*
 import org.ktorm.ksp.compiler.util.*
@@ -93,6 +97,11 @@ internal class MetadataParser(resolver: Resolver, environment: SymbolProcessorEn
 
         _logger.info("[ktorm-ksp-compiler] parse table metadata from entity: $className")
         val table = cls.getAnnotationsByType(Table::class).first()
+
+        val (finalSuperClass, allSuperTableClasses) = parseSuperTableClass(cls)
+        val shouldIgnorePropertyNames =
+            allSuperTableClasses.flatMap { it.getProperties(emptySet()) }.map { it.simpleName.asString() }
+
         val tableMetadata = TableMetadata(
             entityClass = cls,
             name = table.name.ifEmpty { _databaseNamingStrategy.getTableName(cls) },
@@ -101,8 +110,9 @@ internal class MetadataParser(resolver: Resolver, environment: SymbolProcessorEn
             schema = table.schema.ifEmpty { _options["ktorm.schema"] }?.takeIf { it.isNotEmpty() },
             tableClassName = table.className.ifEmpty { _codingNamingStrategy.getTableClassName(cls) },
             entitySequenceName = table.entitySequenceName.ifEmpty { _codingNamingStrategy.getEntitySequenceName(cls) },
-            ignoreProperties = table.ignoreProperties.toSet(),
-            columns = ArrayList()
+            ignoreProperties = table.ignoreProperties.toSet() + shouldIgnorePropertyNames,
+            columns = ArrayList(),
+            superClass = finalSuperClass
         )
 
         val columns = tableMetadata.columns as MutableList
@@ -196,8 +206,8 @@ internal class MetadataParser(resolver: Resolver, environment: SymbolProcessorEn
 
             if (!hasConstructor) {
                 val msg = "" +
-                    "Parse sqlType error for property $propName: the sqlType should be a Kotlin singleton object or " +
-                    "a normal class with a constructor that accepts a single org.ktorm.schema.TypeReference argument."
+                        "Parse sqlType error for property $propName: the sqlType should be a Kotlin singleton object or " +
+                        "a normal class with a constructor that accepts a single org.ktorm.schema.TypeReference argument."
                 throw IllegalArgumentException(msg)
             }
         }
@@ -274,6 +284,84 @@ internal class MetadataParser(resolver: Resolver, environment: SymbolProcessorEn
         )
     }
 
+    /**
+     * @return the final super table class and all super table classes in the inheritance hierarchy.
+     */
+    @OptIn(KotlinPoetKspPreview::class)
+    private fun parseSuperTableClass(cls: KSClassDeclaration): Pair<ClassName, Set<KSClassDeclaration>> {
+        val entityAnnPairs =
+            cls.findAnnotationsInHierarchy(SuperTableClass::class.qualifiedName!!)
+
+        // if there is no SuperTableClass annotation, return the default super table class based on the class kind.
+        if (entityAnnPairs.isEmpty()) {
+            return if (cls.classKind == INTERFACE) {
+                org.ktorm.schema.Table::class.asClassName() to emptySet()
+            } else {
+                org.ktorm.schema.BaseTable::class.asClassName() to emptySet()
+            }
+        }
+
+        // SuperTableClass annotation can only be used on interface
+        if (entityAnnPairs.map { it.first }.any { it.classKind != INTERFACE }) {
+            val msg = "SuperTableClass annotation can only be used on interface."
+            throw IllegalArgumentException(msg)
+        }
+
+        val superTableClasses = entityAnnPairs
+            .map { it.second }
+            .map { it.arguments.single { it.name?.asString() == SuperTableClass::value.name } }
+            .map { it.value as KSType }
+            .map { it.declaration as KSClassDeclaration }
+
+        val lowestSubClass = findLowestSubClass(superTableClasses, cls)
+
+        validateSuperTableClassConstructor(lowestSubClass)
+
+        return lowestSubClass.toClassName() to superTableClasses.toSet()
+    }
+
+    // find the last annotation in the inheritance hierarchy
+    private fun findLowestSubClass(
+        superTableClasses: List<KSClassDeclaration>,
+        cls: KSClassDeclaration,
+    ): KSClassDeclaration {
+        var lowestSubClass = superTableClasses.first()
+        for (i in 1 until superTableClasses.size) {
+            val cur = superTableClasses[i]
+            if (cur.isSubclassOf(lowestSubClass)) {
+                lowestSubClass = cur
+            } else if (!lowestSubClass.isSubclassOf(cur)) {
+                val msg = """
+                    There are multiple SuperTableClass annotations in the inheritance hierarchy 
+                    of class ${cls.qualifiedName?.asString()}.
+                    but the values of annotation are not in the same inheritance hierarchy.
+                """.trimIndent()
+                throw IllegalArgumentException(msg)
+            }
+        }
+        return lowestSubClass
+    }
+
+    // validate the primary constructor of the super table class
+    private fun validateSuperTableClassConstructor(superTableClass: KSClassDeclaration) {
+        if (superTableClass.primaryConstructor == null) {
+            val msg =
+                "The super table class ${superTableClass.qualifiedName?.asString()} should have a primary constructor."
+            throw IllegalArgumentException(msg)
+        }
+
+        val parameters = superTableClass.primaryConstructor!!.parameters
+        if (parameters.size < 2 ||
+            parameters[0].name!!.asString() != "tableName" ||
+            parameters[1].name!!.asString() != "alias"
+        ) {
+            val msg = "" +
+                    "The super table class ${superTableClass.qualifiedName?.asString()} should have " +
+                    "a primary constructor with parameters tableName and alias."
+            throw IllegalArgumentException(msg)
+        }
+    }
+
     private fun TableMetadata.checkCircularRef(ref: KSClassDeclaration, stack: LinkedList<String> = LinkedList()) {
         val className = this.entityClass.qualifiedName?.asString()
         val refClassName = ref.qualifiedName?.asString()

ktorm-ksp-compiler/src/main/kotlin/org/ktorm/ksp/compiler/util/KspExtensions.kt

@@ -56,6 +56,13 @@ internal inline fun <reified T : Any> KSClassDeclaration.isSubclassOf(): Boolean
     return findSuperTypeReference(T::class.qualifiedName!!) != null
 }
 
+/**
+ * Check if this class is a subclass of declaration.
+ */
+internal fun KSClassDeclaration.isSubclassOf(declaration: KSClassDeclaration): Boolean {
+    return findSuperTypeReference(declaration.qualifiedName!!.asString()) != null
+}
+
 /**
  * Find the specific super type reference for this class.
  */
@@ -76,6 +83,26 @@ internal fun KSClassDeclaration.findSuperTypeReference(name: String): KSTypeRefe
     return null
 }
 
+/**
+ * Find all annotations with the given name in the inheritance hierarchy of this class.
+ *
+ * @param name the qualified name of the annotation.
+ * @return a list of pairs, each pair contains the class declaration and the annotation.
+ */
+internal fun KSClassDeclaration.findAnnotationsInHierarchy(name: String): List<Pair<KSClassDeclaration, KSAnnotation>> {
+    val pairs = mutableListOf<Pair<KSClassDeclaration, KSAnnotation>>()
+
+    fun KSClassDeclaration.collectAnnotations() {
+        pairs += annotations
+            .filter { it.annotationType.resolve().declaration.qualifiedName?.asString() == name }
+            .map { this to it }
+        superTypes.forEach { (it.resolve().declaration as KSClassDeclaration).collectAnnotations() }
+    }
+
+    collectAnnotations()
+    return pairs
+}
+
 /**
  * Check if the given symbol is valid.
  */

ktorm-ksp-compiler/src/test/kotlin/org/ktorm/ksp/compiler/BaseKspTest.kt

@@ -61,7 +61,7 @@ abstract class BaseKspTest {
 
     private fun compile(@Language("kotlin") code: String, options: Map<String, String>): KotlinCompilation.Result {
         @Language("kotlin")
-        val header = """
+        val source = """
             import java.math.*
             import java.sql.*
             import java.time.*
@@ -73,12 +73,13 @@ abstract class BaseKspTest {
             import org.ktorm.entity.*
             import org.ktorm.ksp.annotation.*
 
+            $code
+
             lateinit var database: Database
 
 
         """.trimIndent()
 
-        val source = header + code
         printFile(source, "Source.kt")
 
         val compilation = createCompilation(SourceFile.kotlin("Source.kt", source), options)