diff --git a/easysql-api/src/main/java/cc/carm/lib/easysql/api/SQLAction.java b/easysql-api/src/main/java/cc/carm/lib/easysql/api/SQLAction.java
index 6b7e5d3..6ec43bf 100644
--- a/easysql-api/src/main/java/cc/carm/lib/easysql/api/SQLAction.java
+++ b/easysql-api/src/main/java/cc/carm/lib/easysql/api/SQLAction.java
@@ -9,20 +9,79 @@ import java.util.function.BiConsumer;
import java.util.function.Consumer;
import java.util.function.Function;
+/**
+ * SQLAction 是用于承载SQL语句并进行处理、返回的基本类。
+ *
+ *
+ * - 同步执行 {@link #execute()}, {@link #execute(Function, BiConsumer)}
+ *
同步执行方法中有会抛出异常的方法与不抛出异常的方法,
+ *
若选择不抛出异常,则返回值可能为空,需要特殊处理。
+ *
+ * - 异步执行 {@link #executeAsync(Consumer, BiConsumer)}
+ *
异步执行时将提供成功与异常两种处理方式
+ *
可自行选择是否对数据或异常进行处理
+ *
默认的异常处理器为 {@link #defaultExceptionHandler()}
+ *
+ *
+ * 注意: 无论是否异步,都不需要自行关闭ResultSet,本API已自动关闭
+ *
+ * @param 需要返回的类型
+ * @author CarmJos
+ * @since 0.0.1
+ */
public interface SQLAction {
+ /**
+ * 得到该Action的UUID
+ *
+ * @return UUID
+ */
@NotNull UUID getActionUUID();
+ /**
+ * 得到短八位格式的UUID
+ *
+ * @return UUID(8)
+ */
@NotNull String getShortID();
+ /**
+ * 得到该Action的创建时间
+ *
+ * @return 创建时间
+ */
long getCreateTime();
+ /**
+ * 得到该Action所要执行的源SQL语句
+ *
+ * @return 源SQL语句
+ */
@NotNull String getSQLContent();
+ /**
+ * 得到承载该Action的对应{@link SQLManager}
+ *
+ * @return {@link SQLManager}
+ */
@NotNull SQLManager getManager();
+ /**
+ * 执行该Action对应的SQL语句
+ *
+ * @return 指定数据类型
+ * @throws SQLException 当SQL操作出现问题时抛出
+ */
@NotNull T execute() throws SQLException;
+ /**
+ * 执行语句并处理返回值
+ *
+ * @param function 处理方法
+ * @param exceptionHandler 异常处理器 默认为 {@link #defaultExceptionHandler()}
+ * @param 需要返回的内容
+ * @return 指定类型数据
+ */
@Nullable
default R execute(@NotNull Function function, @Nullable BiConsumer> exceptionHandler) {
T value = execute(exceptionHandler);
@@ -30,6 +89,12 @@ public interface SQLAction {
else return function.apply(value);
}
+ /**
+ * 执行语句并返回值
+ *
+ * @param exceptionHandler 异常处理器 默认为 {@link #defaultExceptionHandler()}
+ * @return 指定类型数据
+ */
@Nullable
default T execute(@Nullable BiConsumer> exceptionHandler) {
if (exceptionHandler == null) exceptionHandler = defaultExceptionHandler();
@@ -42,16 +107,33 @@ public interface SQLAction {
return value;
}
+ /**
+ * 异步执行SQL语句,采用默认异常处理,无需返回值。
+ */
default void executeAsync() {
executeAsync(null);
}
+ /**
+ * 异步执行SQL语句
+ *
+ * @param success 成功时的操作
+ */
default void executeAsync(@Nullable Consumer success) {
executeAsync(success, null);
}
+ /**
+ * 异步执行SQL语句
+ *
+ * @param success 成功时的操作
+ * @param failure 异常处理器 默认为 {@link SQLAction#defaultExceptionHandler()}
+ */
void executeAsync(@Nullable Consumer success, @Nullable BiConsumer> failure);
+ /**
+ * @return 默认的异常处理器
+ */
default BiConsumer> defaultExceptionHandler() {
return (exception, action) -> {
getManager().getLogger().severe("Error when execute [" + action.getSQLContent() + "]");
diff --git a/easysql-api/src/main/java/cc/carm/lib/easysql/api/SQLBuilder.java b/easysql-api/src/main/java/cc/carm/lib/easysql/api/SQLBuilder.java
index 90690e8..ba47dc1 100644
--- a/easysql-api/src/main/java/cc/carm/lib/easysql/api/SQLBuilder.java
+++ b/easysql-api/src/main/java/cc/carm/lib/easysql/api/SQLBuilder.java
@@ -2,8 +2,20 @@ package cc.carm.lib.easysql.api;
import org.jetbrains.annotations.NotNull;
+/**
+ * SQLBuilder 是用于构建SQL语句以生成SQLAction执行操作的中间类。
+ *
其连接了{@link SQLManager} 与 {@link SQLAction} ,避免大量的代码堆积
+ *
也是本接口的核心功能所在
+ *
+ * @author CarmJos
+ */
public interface SQLBuilder {
+ /**
+ * 得到承载该Builder的对应{@link SQLManager}
+ *
+ * @return {@link SQLManager}
+ */
@NotNull SQLManager getManager();
}
diff --git a/easysql-api/src/main/java/cc/carm/lib/easysql/api/SQLManager.java b/easysql-api/src/main/java/cc/carm/lib/easysql/api/SQLManager.java
index f6d8280..ee8d81e 100644
--- a/easysql-api/src/main/java/cc/carm/lib/easysql/api/SQLManager.java
+++ b/easysql-api/src/main/java/cc/carm/lib/easysql/api/SQLManager.java
@@ -2,6 +2,7 @@ package cc.carm.lib.easysql.api;
import cc.carm.lib.easysql.api.action.PreparedSQLUpdateAction;
import cc.carm.lib.easysql.api.action.PreparedSQLUpdateBatchAction;
+import cc.carm.lib.easysql.api.action.query.SQLQuery;
import cc.carm.lib.easysql.api.builder.*;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;
@@ -76,6 +77,12 @@ public interface SQLManager {
*/
@Nullable List executeSQLBatch(@NotNull String sql, String... moreSQL);
+ /**
+ * 执行多条不需要返回结果的SQL。
+ *
+ * @param sqlBatch SQL语句内容
+ * @return 对应参数返回的行数
+ */
@Nullable List executeSQLBatch(@NotNull Iterable sqlBatch);
TableCreateBuilder createTable(@NotNull String tableName);
diff --git a/easysql-api/src/main/java/cc/carm/lib/easysql/api/action/PreparedSQLUpdateAction.java b/easysql-api/src/main/java/cc/carm/lib/easysql/api/action/PreparedSQLUpdateAction.java
index aed83ce..34b9141 100644
--- a/easysql-api/src/main/java/cc/carm/lib/easysql/api/action/PreparedSQLUpdateAction.java
+++ b/easysql-api/src/main/java/cc/carm/lib/easysql/api/action/PreparedSQLUpdateAction.java
@@ -1,7 +1,23 @@
package cc.carm.lib.easysql.api.action;
+import org.jetbrains.annotations.Nullable;
+
public interface PreparedSQLUpdateAction extends SQLUpdateAction {
+ /**
+ * 设定SQL语句中所有 ? 对应的参数
+ *
+ * @param params 参数内容
+ * @return {@link PreparedSQLUpdateAction}
+ */
PreparedSQLUpdateAction setParams(Object... params);
+ /**
+ * 设定SQL语句中所有 ? 对应的参数
+ *
+ * @param params 参数内容
+ * @return {@link PreparedSQLUpdateAction}
+ */
+ PreparedSQLUpdateAction setParams(@Nullable Iterable