From d02aeac3581eea155ed6a68e9ae00cde4cf9f222 Mon Sep 17 00:00:00 2001 From: qiaoyuang Date: Sat, 5 Aug 2023 10:11:14 +0800 Subject: [PATCH 1/2] Some code optimization of remove the DBEntity and fix some docs --- CHANGELOG.md | 5 +++++ sqllin-dsl/doc/advanced-query-cn.md | 14 ++++--------- sqllin-dsl/doc/advanced-query.md | 14 ++++--------- sqllin-dsl/doc/getting-start-cn.md | 8 ++++---- sqllin-dsl/doc/getting-start.md | 6 +++--- .../doc/modify-database-and-transaction-cn.md | 6 +++--- .../doc/modify-database-and-transaction.md | 4 ++-- sqllin-dsl/doc/query-cn.md | 2 +- sqllin-dsl/doc/query.md | 2 +- .../kotlin/com/ctrip/sqllin/dsl/Database.kt | 20 +++++++++---------- .../ctrip/sqllin/processor/ClauseProcessor.kt | 2 +- 11 files changed, 38 insertions(+), 45 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 08c9ffe..bb2f3a3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,11 @@ ## v1.1.1 / 2023-xx-xx +### sqllin-dsl + +* *Breaking Change*: Remove the public API `DBEntity`([#36](https://github.com/ctripcorp/SQLlin/pull/36)), any data classes used in _sqllin-dsl_ don't need to extend `DBEntity` anymore. + + ### sqllin-driver * Fix a bug about empty `ByteArray` on native platforms([#30](https://github.com/ctripcorp/SQLlin/pull/30)) diff --git a/sqllin-dsl/doc/advanced-query-cn.md b/sqllin-dsl/doc/advanced-query-cn.md index 50c89a7..f064525 100644 --- a/sqllin-dsl/doc/advanced-query-cn.md +++ b/sqllin-dsl/doc/advanced-query-cn.md @@ -62,7 +62,7 @@ SQLlin 还不支持子查询，我们将会尽快开发该功能。 SQLlin 目前支持 join 表。 -我们需要另外两个 `DBEntity`： +我们需要另外两个数据库实体： ```kotlin @DBRow("transcript") @@ -71,9 +71,7 @@ data class Transcript( val name: String?, val math: Int, val english: Int, -): DBEntity { - override fun kSerializer(): KSerializer = serializer() -} +) @Serializable data class Student( @@ -81,18 +79,14 @@ data class Student( val age: Int?, val math: Int, val english: Int, -): DBEntity { - override fun kSerializer(): KSerializer = serializer() -} +) @Serializable data class CrossJoinStudent( val age: Int?, val math: Int, val english: Int, -): DBEntity { - override fun kSerializer(): KSerializer = CrossJoinStudent() -} +) ``` `Transcript` 代表另一张表，`Student` 表示 join 的查询结果的类型（所以 `Student` 不需要被添加 `@DBRow` 注解），它拥有所有 `Person` 和 `Transcript` diff --git a/sqllin-dsl/doc/advanced-query.md b/sqllin-dsl/doc/advanced-query.md index 2d872c2..aed9ae6 100644 --- a/sqllin-dsl/doc/advanced-query.md +++ b/sqllin-dsl/doc/advanced-query.md @@ -65,7 +65,7 @@ SQLlin doesn't yet support subqueries, we will develop as soon as possible. SQLlin supports joining tables now. -We need other two `DBEntity`s: +We need other two database entities: ```kotlin @DBRow("transcript") @@ -74,9 +74,7 @@ data class Transcript( val name: String?, val math: Int, val english: Int, -): DBEntity { - override fun kSerializer(): KSerializer = serializer() -} +) @Serializable data class Student( @@ -84,18 +82,14 @@ data class Student( val age: Int?, val math: Int, val english: Int, -): DBEntity { - override fun kSerializer(): KSerializer = serializer() -} +) @Serializable data class CrossJoinStudent( val age: Int?, val math: Int, val english: Int, -): DBEntity { - override fun kSerializer(): KSerializer = CrossJoinStudent() -} +) ``` The `Transcript` represents a other table. And the `Student` represents the join query results' type(so `Student` diff --git a/sqllin-dsl/doc/getting-start-cn.md b/sqllin-dsl/doc/getting-start-cn.md index 7a22f5e..17204ed 100644 --- a/sqllin-dsl/doc/getting-start-cn.md +++ b/sqllin-dsl/doc/getting-start-cn.md @@ -126,9 +126,9 @@ override fun onDestroy() { } ``` -## 定义你的 DBEntity +## 定义你的数据库实体 -在 _sqllin-dsl_ 中，你可以直接插入或查找对象。所以，你需要使用正确的方式定义你的 data class，比如： +在 _sqllin-dsl_ 中，你可以直接插入或查找对象。所以，你需要使用正确的方式定义你的数据库实体，比如： ```kotlin import com.ctrip.sqllin.dsl.annotation.DBRow @@ -141,8 +141,8 @@ data class Person( val age: Int, ) ``` -你定义的 DBEntity 的属性名应与数据库表的列名相对应。DBEntity 不应该拥有名字与表中的所有列名均不相同的属性，但是 -DBEntity 的属性数量可以比表中列的数量少。 +你定义的数据库实体的属性名应与数据库表的列名相对应。数据库实体不应该拥有名字与表中的所有列名均不相同的属性，但是 +数据库实体的属性数量可以比表中列的数量少。 `@DBRow` 的参数 `tableName` 表示数据库中的表名，请确保传入正确的值。如果不手动传入，_sqllin-processor_ 将会使用类名作为表名，比如 `Person` 类的默认表名是"Person"。 diff --git a/sqllin-dsl/doc/getting-start.md b/sqllin-dsl/doc/getting-start.md index e44a0c4..8ca9f22 100644 --- a/sqllin-dsl/doc/getting-start.md +++ b/sqllin-dsl/doc/getting-start.md @@ -134,7 +134,7 @@ override fun onDestroy() { } ``` -## Defining Your DBEntity +## Defining Your database entity In _sqllin-dsl_, you can insert and query objects directly. So, you need to use the correct way to define your data class. For example: @@ -150,8 +150,8 @@ data class Person( ) ``` -Your DBEntity's property names should same with the database table's column names. The DBEntity cannot have properties with names different from all -column names in the table. But the count of your DBEntity's properties can less than the count of columns. +Your database entity's property names should same with the database table's column names. The database entity cannot have properties with names different from all +column names in the table. But the count of your database entity's properties can less than the count of columns. The `@DBRow`'s param `tableName` represents the table name in Database, please ensure pass the correct value. If you don't pass the parameter manually, _sqllin-processor_ will use the class diff --git a/sqllin-dsl/doc/modify-database-and-transaction-cn.md b/sqllin-dsl/doc/modify-database-and-transaction-cn.md index b207895..246d95e 100644 --- a/sqllin-dsl/doc/modify-database-and-transaction-cn.md +++ b/sqllin-dsl/doc/modify-database-and-transaction-cn.md @@ -1,6 +1,6 @@ # 修改数据库与事务 -在[《开始使用》](getting-start-cn.md)中，我们学习了如何创建 `Database` 实例以及定义你自己的 `DBEntity`。现在我们将开始学习如何在 SQLlin 中编写 SQL 语句。 +在[《开始使用》](getting-start-cn.md)中，我们学习了如何创建 `Database` 实例以及定义你自己的数据库实体。现在我们将开始学习如何在 SQLlin 中编写 SQL 语句。 ## 插入 @@ -20,8 +20,8 @@ fun sample() { } } ``` -`PersonTable` 由 _sqllin-processor_ 生成，这是因为 `Person` 类被添加了 `@DBRow` 注解。任何继承自 `DBEntity` -且被添加了 `@DBRow` 注解的类都会生成一个 `Table` object，它的名字为 `类名 + 'Table'`。 +`PersonTable` 由 _sqllin-processor_ 生成，这是因为 `Person` 类被添加了 `@DBRow` 注解。任何添加了 `@DBRow` +注解的类都会生成一个 `Table` object，它的名字为 `类名 + 'Table'`。 现在让我们来进行真正的 _INSERT_ 操作： diff --git a/sqllin-dsl/doc/modify-database-and-transaction.md b/sqllin-dsl/doc/modify-database-and-transaction.md index 83e1670..b0fbbab 100644 --- a/sqllin-dsl/doc/modify-database-and-transaction.md +++ b/sqllin-dsl/doc/modify-database-and-transaction.md @@ -2,7 +2,7 @@ 中文版请见[这里](modify-database-and-transaction-cn.md) -In [Getting Start](getting-start.md), we have learned how to create the `Database` instance and define your `DBEntity`. Now, +In [Getting Start](getting-start.md), we have learned how to create the `Database` instance and define your database entity. Now, we start learn how to write SQL statements with SQLlin. ## Insert @@ -27,7 +27,7 @@ fun sample() { ``` The `PersonTable` is generated by _sqllin-processor_, because `Person` is annotated the `@DBRow` -annotation. Any class that extended from `DBEntity` and be annotated the `@DBRow` will be generated a `Table` object, its name is +annotation. Any class that be annotated the `@DBRow` will be generated a `Table` object, its name is `class name + 'Table'`. Now, let's do the real _INSERT_: diff --git a/sqllin-dsl/doc/query-cn.md b/sqllin-dsl/doc/query-cn.md index a43a66d..2d4feef 100644 --- a/sqllin-dsl/doc/query-cn.md +++ b/sqllin-dsl/doc/query-cn.md @@ -23,7 +23,7 @@ fun sample() { `X` 表示没有任何子句，我们已经在 _DELETE_ 语句中见过它了。 _SELECT_ 语句与其他语句的另一个不同点在于它拥有查询结果。所以你需要声明一个类型为 `SelectStatement` -的变量，泛型参数 `T` 是你希望反序列化的 `DBEntity`。你应该将你构建的 _SELECT_ 语句赋值给此变量。 +的变量，泛型参数 `T` 是你希望反序列化的数据库实体的类型。你应该将你构建的 _SELECT_ 语句赋值给此变量。 注意，所有的语句只会在 _DatabaseScope_ 结束后执行，我们曾在[《修改数据库与事务》](modify-database-and-transaction-cn.md)中提到过这一点。 所以你必须在 `database { ... }` 外部调用 `getResults` 函数，SQLlin 将会帮助你将查询结果反序列化为你期待的对象。 diff --git a/sqllin-dsl/doc/query.md b/sqllin-dsl/doc/query.md index d7131bb..eef2912 100644 --- a/sqllin-dsl/doc/query.md +++ b/sqllin-dsl/doc/query.md @@ -24,7 +24,7 @@ fun sample() { The `X` represents without any clause, we’ve seen it in _DELETE_ statements. The _SELECT_ statement has query results, this is another difference from other statements. So, you need to declare a variable that -type is `SelectStatement`. The generic parameter `T` is your `DBEntity` that you expect to deserialize. You should assign _SELECT_ statement you built to this variable. +type is `SelectStatement`. The generic parameter `T` is your database entity's type that you expect to deserialize. You should assign _SELECT_ statement you built to this variable. Note, all statements will only be executed when the _DatabaseScope_ ends, we mentioned this in the [Modify Database and Transaction](modify-database-and-transaction.md). So, you must invoke the `getResults` function outside the `database { ... }` block, SQLlin will help you deserialize query results to objects that you expected. diff --git a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/Database.kt b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/Database.kt index 6eab07b..41b2ebc 100644 --- a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/Database.kt +++ b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/Database.kt @@ -171,10 +171,10 @@ public class Database( * Select with no any clause. */ public inline infix fun Table.SELECT(x: X): FinalSelectStatement = - select(getKSerializer(), false) + select(kSerializer(), false) public inline infix fun Table.SELECT_DISTINCT(x: X): FinalSelectStatement = - select(getKSerializer(), true) + select(kSerializer(), true) public fun Table.select(serializer: KSerializer, isDistinct: Boolean): FinalSelectStatement { val container = getSelectStatementGroup() @@ -187,10 +187,10 @@ public class Database( * Receive the 'WHERE' clause. */ public inline infix fun Table.SELECT(clause: WhereClause): WhereSelectStatement = - select(getKSerializer(), clause, false) + select(kSerializer(), clause, false) public inline infix fun Table.SELECT_DISTINCT(clause: WhereClause): WhereSelectStatement = - select(getKSerializer(), clause, true) + select(kSerializer(), clause, true) public fun Table.select(serializer: KSerializer, clause: WhereClause, isDistinct: Boolean): WhereSelectStatement { val container = getSelectStatementGroup() @@ -203,10 +203,10 @@ public class Database( * Receive the 'ORDER BY' clause. */ public inline infix fun Table.SELECT(clause: OrderByClause): OrderBySelectStatement = - select(getKSerializer(), clause, false) + select(kSerializer(), clause, false) public inline infix fun Table.SELECT_DISTINCT(clause: OrderByClause): OrderBySelectStatement = - select(getKSerializer(), clause, true) + select(kSerializer(), clause, true) public fun Table.select(serializer: KSerializer, clause: OrderByClause, isDistinct: Boolean): OrderBySelectStatement { val container = getSelectStatementGroup() @@ -219,10 +219,10 @@ public class Database( * Receive the 'LIMIT' clause. */ public inline infix fun Table.SELECT(clause: LimitClause): LimitSelectStatement = - select(getKSerializer(), clause, false) + select(kSerializer(), clause, false) public inline infix fun Table.SELECT_DISTINCT(clause: LimitClause): LimitSelectStatement = - select(getKSerializer(), clause, true) + select(kSerializer(), clause, true) public fun Table.select(serializer: KSerializer, clause: LimitClause, isDistinct: Boolean): LimitSelectStatement { val container = getSelectStatementGroup() @@ -235,10 +235,10 @@ public class Database( * Receive the 'GROUP BY' clause. */ public inline infix fun Table.SELECT(clause: GroupByClause): GroupBySelectStatement = - select(getKSerializer(), clause, false) + select(kSerializer(), clause, false) public inline infix fun Table.SELECT_DISTINCT(clause: GroupByClause): GroupBySelectStatement = - select(getKSerializer(), clause, true) + select(kSerializer(), clause, true) public fun Table.select(serializer: KSerializer, clause: GroupByClause, isDistinct: Boolean): GroupBySelectStatement { val container = getSelectStatementGroup() diff --git a/sqllin-processor/src/main/kotlin/com/ctrip/sqllin/processor/ClauseProcessor.kt b/sqllin-processor/src/main/kotlin/com/ctrip/sqllin/processor/ClauseProcessor.kt index 098119e..7455e91 100644 --- a/sqllin-processor/src/main/kotlin/com/ctrip/sqllin/processor/ClauseProcessor.kt +++ b/sqllin-processor/src/main/kotlin/com/ctrip/sqllin/processor/ClauseProcessor.kt @@ -50,7 +50,7 @@ class ClauseProcessor( for (classDeclaration in allClassAnnotatedWhereProperties) { if (classDeclaration.annotations.all { !it.annotationType.resolve().isAssignableFrom(serializableType) }) - continue // Don't handle the class that don't implement 'DBEntity' or not annotated 'Serializable' + continue // Don't handle the class that don't annotated 'Serializable' val className = classDeclaration.simpleName.asString() val packageName = classDeclaration.packageName.asString() From 5db8c862cf8b4607b3de8321807cba7b5189d6c3 Mon Sep 17 00:00:00 2001 From: qiaoyuang Date: Mon, 7 Aug 2023 14:26:43 +0800 Subject: [PATCH 2/2] Revert and deprecated the DBEntity --- .../kotlin/com/ctrip/sqllin/dsl/DBEntity.kt | 30 +++++++++++++++++++ 1 file changed, 30 insertions(+) create mode 100644 sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/DBEntity.kt diff --git a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/DBEntity.kt b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/DBEntity.kt new file mode 100644 index 0000000..35e7134 --- /dev/null +++ b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/DBEntity.kt @@ -0,0 +1,30 @@ +/* + * Copyright (C) 2022 Ctrip.com. + * + * 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 com.ctrip.sqllin.dsl + +import kotlinx.serialization.KSerializer + +/** + * Base where clause property in SQL + * @author yaqiao + */ + +@Deprecated(message = "The DBEntity hae benn deprecated, you don't need to implement this interface anymore") +public fun interface DBEntity { + + public fun kSerializer(): KSerializer +} \ No newline at end of file