[0.4.2] feat(table): 令 SQLTable 变为接口，额外添加 NamedSQLTable 抽象类用于简单实现 SQLTable。

BREAKING-CHANGE: SQLTable的类型已转变，以往的代码可能失效。

.github/workflows/deploy.yml

@@ -83,14 +83,14 @@ jobs:
           rm -rf deploy
           mkdir -vp deploy
           cp -vrf $HOME/local-deploy/* deploy/
-          cp -vrf .documentation/REPOSITORY-README.md deploy/README.md
+          cp -vrf .documentation/repository/README.md deploy/README.md
 
       - name: "Copy Javadoc"
         run: |
           rm -rf docs
           mkdir -vp docs
           cp -vrf api/target/apidocs/* docs/
-          cp -vrf .documentation/JAVADOC-README.md docs/README.md
+          cp -vrf .documentation/javadoc/README.md docs/README.md
 
       - name: "Generate the Javadoc sitemap"
         id: sitemap

api/pom.xml

@@ -5,7 +5,7 @@
     <parent>
         <groupId>cc.carm.lib</groupId>
         <artifactId>easysql-parent</artifactId>
-        <version>0.4.1</version>
+        <version>0.4.2</version>
     </parent>
     <modelVersion>4.0.0</modelVersion>
 

api/src/main/java/cc/carm/lib/easysql/api/SQLTable.java

@@ -4,26 +4,28 @@ import cc.carm.lib.easysql.api.action.PreparedSQLUpdateAction;
 import cc.carm.lib.easysql.api.action.PreparedSQLUpdateBatchAction;
 import cc.carm.lib.easysql.api.builder.*;
 import cc.carm.lib.easysql.api.function.SQLHandler;
+import cc.carm.lib.easysql.api.table.NamedSQLTable;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
 import java.sql.SQLException;
+import java.util.Optional;
 
 /**
  * SQLTable 基于 {@link TableCreateBuilder} 构建表，用于快速创建与该表相关的操作。
  * <ul>
- *  <li>1. 调用 {@link SQLTable#of(String, String[])} 方法创建一个 SQLTable 对象;</li>
+ *  <li>1. 调用 {@link NamedSQLTable#of(String, String[])} 方法创建一个 SQLTable 对象;</li>
- *  <li>2. 在应用初始化阶段调用 {@link SQLTable#create(SQLManager)} 方法初始化 SQLTable 对象;</li>
+ *  <li>2. 在应用初始化阶段调用 {@link NamedSQLTable#create(SQLManager)} 方法初始化 SQLTable 对象;</li>
- *  <li>3. 获取已创建的{@link SQLTable} 实例，直接调用对应方法进行关于表的相关操作。</li>
+ *  <li>3. 获取已创建的{@link NamedSQLTable} 实例，直接调用对应方法进行关于表的相关操作。</li>
  * </ul>
  *
  * @author CarmJos
  * @since 0.3.10
  */
-public abstract class SQLTable {
+public interface SQLTable {
 
-    public static @NotNull SQLTable of(@NotNull String tableName, @Nullable SQLHandler<TableCreateBuilder> table) {
+    static @NotNull NamedSQLTable of(@NotNull String tableName, @Nullable SQLHandler<TableCreateBuilder> table) {
-        return new SQLTable(tableName) {
+        return new NamedSQLTable(tableName) {
             @Override
             public boolean create(@NotNull SQLManager sqlManager, String tablePrefix) throws SQLException {
                 if (this.manager == null) this.manager = sqlManager;
@@ -36,108 +38,113 @@ public abstract class SQLTable {
         };
     }
 
-    public static @NotNull SQLTable of(@NotNull String tableName, @NotNull String[] columns) {
+    static @NotNull NamedSQLTable of(@NotNull String tableName, @NotNull String[] columns) {
         return of(tableName, columns, null);
     }
 
-    public static @NotNull SQLTable of(@NotNull String tableName,
+    static @NotNull NamedSQLTable of(@NotNull String tableName,
-                                       @NotNull String[] columns, @Nullable String tableSettings) {
+                                     @NotNull String[] columns, @Nullable String tableSettings) {
         return of(tableName, builder -> {
             builder.setColumns(columns);
             if (tableSettings != null) builder.setTableSettings(tableSettings);
         });
     }
 
-    private final @NotNull String tableName;
+    /**
-
+     * 以指定的 {@link SQLManager} 实例初始化并创建该表
-    protected String tablePrefix;
+     *
-    protected SQLManager manager;
+     * @param sqlManager {@link SQLManager} 实例
+     * @return 是否新创建了本表 (若已创建或创建失败则返回false)
+     * @throws SQLException 当数据库返回异常时抛出
+     */
+    boolean create(SQLManager sqlManager) throws SQLException;
 
     /**
-     * 请调用 {@link SQLTable} 下的静态方法进行对象的初始化。
+     * 得到 {@link #create(SQLManager)} 用于初始化本实例的 {@link SQLManager} 实例
      *
-     * @param tableName 该表的名称
+     * @return {@link SQLManager} 实例
      */
-    private SQLTable(@NotNull String tableName) {
+    @Nullable SQLManager getSQLManager();
-        this.tableName = tableName;
-    }
-
-    public @NotNull String getTableName() {
-        return (tablePrefix != null ? tablePrefix : "") + tableName;
-    }
 
     /**
-     * 使用指定 SQLManager 进行本示例的初始化。
+     * 得到本表表名，不得为空。
      *
-     * @param sqlManager  {@link SQLManager}
+     * @return 本表表名
-     * @param tablePrefix 表名前缀
-     * @return 本表是否为首次创建
-     * @throws SQLException 出现任何错误时抛出
      */
-    public abstract boolean create(@NotNull SQLManager sqlManager, @Nullable String tablePrefix) throws SQLException;
+    @NotNull String getTableName();
 
-    public boolean create(@NotNull SQLManager sqlManager) throws SQLException {
+    default @NotNull TableQueryBuilder createQuery() {
-        return create(manager, null);
+        return Optional.ofNullable(getSQLManager()).map(this::createQuery)
+                .orElseThrow(() -> new NullPointerException("This table doesn't have a SQLManger."));
     }
 
-    public @NotNull TableQueryBuilder createQuery(@NotNull SQLManager sqlManager) {
+    default @NotNull TableQueryBuilder createQuery(@NotNull SQLManager sqlManager) {
         return sqlManager.createQuery().inTable(getTableName());
     }
 
-    public @NotNull TableQueryBuilder createQuery() {
+    default @NotNull DeleteBuilder createDelete() {
-        return createQuery(this.manager);
+        return Optional.ofNullable(getSQLManager()).map(this::createDelete)
+                .orElseThrow(() -> new NullPointerException("This table doesn't have a SQLManger."));
     }
 
-    public @NotNull DeleteBuilder createDelete() {
+    default @NotNull DeleteBuilder createDelete(@NotNull SQLManager sqlManager) {
-        return createDelete(this.manager);
-    }
-
-    public @NotNull DeleteBuilder createDelete(@NotNull SQLManager sqlManager) {
         return sqlManager.createDelete(getTableName());
     }
 
-    public @NotNull UpdateBuilder createUpdate() {
+    default @NotNull UpdateBuilder createUpdate() {
-        return createUpdate(this.manager);
+        return Optional.ofNullable(getSQLManager()).map(this::createUpdate)
+                .orElseThrow(() -> new NullPointerException("This table doesn't have a SQLManger."));
     }
 
-    public @NotNull UpdateBuilder createUpdate(@NotNull SQLManager sqlManager) {
+    default @NotNull UpdateBuilder createUpdate(@NotNull SQLManager sqlManager) {
         return sqlManager.createUpdate(getTableName());
     }
 
-
+    default @NotNull InsertBuilder<PreparedSQLUpdateAction<Integer>> createInsert() {
-    public @NotNull InsertBuilder<PreparedSQLUpdateAction<Integer>> createInsert() {
+        return Optional.ofNullable(getSQLManager()).map(this::createInsert)
-        return createInsert(this.manager);
+                .orElseThrow(() -> new NullPointerException("This table doesn't have a SQLManger."));
     }
 
-    public @NotNull InsertBuilder<PreparedSQLUpdateAction<Integer>> createInsert(@NotNull SQLManager sqlManager) {
+    default @NotNull InsertBuilder<PreparedSQLUpdateAction<Integer>> createInsert(@NotNull SQLManager sqlManager) {
         return sqlManager.createInsert(getTableName());
     }
 
-
+    default @NotNull InsertBuilder<PreparedSQLUpdateBatchAction<Integer>> createInsertBatch() {
-    public @NotNull InsertBuilder<PreparedSQLUpdateBatchAction<Integer>> createInsertBatch() {
+        return Optional.ofNullable(getSQLManager()).map(this::createInsertBatch)
-        return createInsertBatch(this.manager);
+                .orElseThrow(() -> new NullPointerException("This table doesn't have a SQLManger."));
     }
 
-    public @NotNull InsertBuilder<PreparedSQLUpdateBatchAction<Integer>> createInsertBatch(@NotNull SQLManager sqlManager) {
+    default @NotNull InsertBuilder<PreparedSQLUpdateBatchAction<Integer>> createInsertBatch(@NotNull SQLManager sqlManager) {
         return sqlManager.createInsertBatch(getTableName());
     }
 
+    default @NotNull ReplaceBuilder<PreparedSQLUpdateAction<Integer>> createReplace() {
+        return Optional.ofNullable(getSQLManager()).map(this::createReplace)
+                .orElseThrow(() -> new NullPointerException("This table doesn't have a SQLManger."));
 
-    public @NotNull ReplaceBuilder<PreparedSQLUpdateAction<Integer>> createReplace() {
-        return createReplace(this.manager);
     }
 
-    public @NotNull ReplaceBuilder<PreparedSQLUpdateAction<Integer>> createReplace(@NotNull SQLManager sqlManager) {
+    default @NotNull ReplaceBuilder<PreparedSQLUpdateAction<Integer>> createReplace(@NotNull SQLManager sqlManager) {
-        return sqlManager.createReplace(getTableName());
+        return Optional.ofNullable(getSQLManager()).map(this::createReplace)
+                .orElseThrow(() -> new NullPointerException("This table doesn't have a SQLManger."));
     }
 
-
+    default @NotNull ReplaceBuilder<PreparedSQLUpdateBatchAction<Integer>> createReplaceBatch() {
-    public @NotNull ReplaceBuilder<PreparedSQLUpdateBatchAction<Integer>> createReplaceBatch() {
+        return Optional.ofNullable(getSQLManager()).map(this::createReplaceBatch)
-        return createReplaceBatch(this.manager);
+                .orElseThrow(() -> new NullPointerException("This table doesn't have a SQLManger."));
     }
 
-    public @NotNull ReplaceBuilder<PreparedSQLUpdateBatchAction<Integer>> createReplaceBatch(@NotNull SQLManager sqlManager) {
+    default @NotNull ReplaceBuilder<PreparedSQLUpdateBatchAction<Integer>> createReplaceBatch(@NotNull SQLManager sqlManager) {
         return sqlManager.createReplaceBatch(getTableName());
     }
 
+    default @NotNull TableAlterBuilder alter() {
+        return Optional.ofNullable(getSQLManager()).map(this::alter)
+                .orElseThrow(() -> new NullPointerException("This table doesn't have a SQLManger."));
+    }
+
+    default @NotNull TableAlterBuilder alter(@NotNull SQLManager sqlManager) {
+        return sqlManager.alterTable(getTableName());
+    }
+
 }

api/src/main/java/cc/carm/lib/easysql/api/table/NamedSQLTable.java

@@ -0,0 +1,50 @@
+package cc.carm.lib.easysql.api.table;
+
+import cc.carm.lib.easysql.api.SQLManager;
+import cc.carm.lib.easysql.api.SQLTable;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+
+import java.sql.SQLException;
+
+
+public abstract class NamedSQLTable implements SQLTable {
+
+    private final @NotNull String tableName;
+
+    protected @Nullable String tablePrefix;
+    protected @Nullable SQLManager manager;
+
+    /**
+     * 请调用 {@link NamedSQLTable} 下的静态方法进行对象的初始化。
+     *
+     * @param tableName 该表的名称
+     */
+    public NamedSQLTable(@NotNull String tableName) {
+        this.tableName = tableName;
+    }
+
+    public @NotNull String getTableName() {
+        return (tablePrefix != null ? tablePrefix : "") + tableName;
+    }
+
+    @Override
+    public @Nullable SQLManager getSQLManager() {
+        return this.manager;
+    }
+
+    /**
+     * 使用指定 SQLManager 进行本示例的初始化。
+     *
+     * @param sqlManager  {@link SQLManager}
+     * @param tablePrefix 表名前缀
+     * @return 本表是否为首次创建
+     * @throws SQLException 出现任何错误时抛出
+     */
+    public abstract boolean create(@NotNull SQLManager sqlManager, @Nullable String tablePrefix) throws SQLException;
+
+    public boolean create(@NotNull SQLManager sqlManager) throws SQLException {
+        return create(sqlManager, null);
+    }
+
+}

demo/pom.xml

@@ -5,7 +5,7 @@
     <parent>
         <artifactId>easysql-parent</artifactId>
         <groupId>cc.carm.lib</groupId>
-        <version>0.4.1</version>
+        <version>0.4.2</version>
     </parent>
     <modelVersion>4.0.0</modelVersion>
 

impl/pom.xml

@@ -5,7 +5,7 @@
     <parent>
         <artifactId>easysql-parent</artifactId>
         <groupId>cc.carm.lib</groupId>
-        <version>0.4.1</version>
+        <version>0.4.2</version>
     </parent>
     <modelVersion>4.0.0</modelVersion>
 

pom.xml

@@ -19,7 +19,7 @@
     <groupId>cc.carm.lib</groupId>
     <artifactId>easysql-parent</artifactId>
     <packaging>pom</packaging>
-    <version>0.4.1</version>
+    <version>0.4.2</version>
 
     <modules>
         <module>api</module>

with-pool/beecp/pom.xml

@@ -5,7 +5,7 @@
     <parent>
         <artifactId>easysql-parent</artifactId>
         <groupId>cc.carm.lib</groupId>
-        <version>0.4.1</version>
+        <version>0.4.2</version>
         <relativePath>../../pom.xml</relativePath>
     </parent>
     <modelVersion>4.0.0</modelVersion>

with-pool/hikaricp/pom.xml

@@ -5,7 +5,7 @@
     <parent>
         <artifactId>easysql-parent</artifactId>
         <groupId>cc.carm.lib</groupId>
-        <version>0.4.1</version>
+        <version>0.4.2</version>
         <relativePath>../../pom.xml</relativePath>
     </parent>
     <modelVersion>4.0.0</modelVersion>