carm/EasySQL
1
Fork 0
mirror of https://github.com/CarmJos/EasySQL.git synced 2026-06-04 23:41:15 +08:00
Code Issues Releases Activity

补充部分JavaDoc

Browse Source
This commit is contained in:
Carm Jos
2021-12-14 19:47:35 +08:00
parent 76476a8f9f
commit f0650ea720
20 changed files with 268 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files
easysql-api/src/main/java/cc/carm/lib/easysql/api/SQLAction.java
+82
View File
@@ -9,20 +9,79 @@ import java.util.function.BiConsumer;
import java.util.function.Consumer;
import java.util.function.Function;
/**
* SQLAction 是用于承载SQL语句并进行处理、返回的基本类。
*
* <ul>
* <li>同步执行 {@link #execute()}, {@link #execute(Function, BiConsumer)}</li>
* <br> 同步执行方法中有会抛出异常的方法与不抛出异常的方法，
* <br> 若选择不抛出异常，则返回值可能为空，需要特殊处理。
*
* <li>异步执行 {@link #executeAsync(Consumer, BiConsumer)}</li>
* <br> 异步执行时将提供成功与异常两种处理方式
* <br> 可自行选择是否对数据或异常进行处理
* <br> 默认的异常处理器为 {@link #defaultExceptionHandler()}
* </ul>
*
* <b>注意：</b> 无论是否异步，都不需要自行关闭ResultSet，本API已自动关闭
*
* @param <T> 需要返回的类型
* @author CarmJos
* @since 0.0.1
*/
public interface SQLAction<T> {
/**
* 得到该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 <R> 需要返回的内容
* @return 指定类型数据
*/
@Nullable
default <R> R execute(@NotNull Function<T, R> function, @Nullable BiConsumer<SQLException, SQLAction<T>> exceptionHandler) {
T value = execute(exceptionHandler);
@@ -30,6 +89,12 @@ public interface SQLAction<T> {
else return function.apply(value);
}
/**
* 执行语句并返回值
*
* @param exceptionHandler 异常处理器 默认为 {@link #defaultExceptionHandler()}
* @return 指定类型数据
*/
@Nullable
default T execute(@Nullable BiConsumer<SQLException, SQLAction<T>> exceptionHandler) {
if (exceptionHandler == null) exceptionHandler = defaultExceptionHandler();
@@ -42,16 +107,33 @@ public interface SQLAction<T> {
return value;
}
/**
* 异步执行SQL语句，采用默认异常处理，无需返回值。
*/
default void executeAsync() {
executeAsync(null);
}
/**
* 异步执行SQL语句
*
* @param success 成功时的操作
*/
default void executeAsync(@Nullable Consumer<T> success) {
executeAsync(success, null);
}
/**
* 异步执行SQL语句
*
* @param success 成功时的操作
* @param failure 异常处理器 默认为 {@link SQLAction#defaultExceptionHandler()}
*/
void executeAsync(@Nullable Consumer<T> success, @Nullable BiConsumer<SQLException, SQLAction<T>> failure);
/**
* @return 默认的异常处理器
*/
default BiConsumer<SQLException, SQLAction<T>> defaultExceptionHandler() {
return (exception, action) -> {
getManager().getLogger().severe("Error when execute [" + action.getSQLContent() + "]");
easysql-api/src/main/java/cc/carm/lib/easysql/api/SQLBuilder.java
+12
View File
@@ -2,8 +2,20 @@ package cc.carm.lib.easysql.api;
import org.jetbrains.annotations.NotNull;
/**
* SQLBuilder 是用于构建SQL语句以生成SQLAction执行操作的中间类。
* <br> 其连接了{@link SQLManager} 与 {@link SQLAction} ,避免大量的代码堆积
* <br> 也是本接口的核心功能所在
*
* @author CarmJos
*/
public interface SQLBuilder {
/**
* 得到承载该Builder的对应{@link SQLManager}
*
* @return {@link SQLManager}
*/
@NotNull SQLManager getManager();
}
easysql-api/src/main/java/cc/carm/lib/easysql/api/SQLManager.java
+7
View File
@@ -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<Integer> executeSQLBatch(@NotNull String sql, String... moreSQL);
/**
* 执行多条不需要返回结果的SQL。
*
* @param sqlBatch SQL语句内容
* @return 对应参数返回的行数
*/
@Nullable List<Integer> executeSQLBatch(@NotNull Iterable<String> sqlBatch);
TableCreateBuilder createTable(@NotNull String tableName);
easysql-api/src/main/java/cc/carm/lib/easysql/api/action/PreparedSQLUpdateAction.java
+16
View File
@@ -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<Object> params);
}
easysql-api/src/main/java/cc/carm/lib/easysql/api/action/PreparedSQLUpdateBatchAction.java
+25
View File
@@ -6,12 +6,37 @@ import java.util.List;
public interface PreparedSQLUpdateBatchAction extends SQLAction<List<Integer>> {
/**
* 设定多组SQL语句中所有 ? 对应的参数
*
* @param allParams 所有参数内容
* @return {@link PreparedSQLUpdateBatchAction}
*/
PreparedSQLUpdateBatchAction setAllParams(Iterable<Object[]> allParams);
/**
* 添加一组SQL语句中所有 ? 对应的参数
*
* @param params 参数内容
* @return {@link PreparedSQLUpdateBatchAction}
*/
PreparedSQLUpdateBatchAction addParamsBatch(Object... params);
/**
* 设定自增主键的序列
*
* @param keyColumnIndex 自增主键的序列
* 若该值 > 0，则 {@link #execute()} 返回自增主键数值
* 若该值 ≤ 0，则 {@link #execute()} 返回变更的行数
* @return {@link PreparedSQLUpdateBatchAction}
*/
PreparedSQLUpdateBatchAction setKeyIndex(int keyColumnIndex);
/**
* 默认主键序列的数值为 -1 (≤0) ，即默认返回发生变更的行数。
*
* @return 默认主键序列
*/
default PreparedSQLUpdateBatchAction defaultKeyIndex() {
return setKeyIndex(-1); // will return changed lines number
}
easysql-api/src/main/java/cc/carm/lib/easysql/api/action/SQLUpdateAction.java
+13
View File
@@ -4,8 +4,21 @@ import cc.carm.lib.easysql.api.SQLAction;
public interface SQLUpdateAction extends SQLAction<Integer> {
/**
* 设定自增主键的序列
*
* @param keyColumnIndex 自增主键的序列
* 若该值 > 0，则 {@link #execute()} 返回自增主键数值
* 若该值 ≤ 0，则 {@link #execute()} 返回变更的行数
* @return {@link SQLUpdateAction}
*/
SQLUpdateAction setKeyIndex(int keyColumnIndex);
/**
* 默认主键序列的数值为 -1 (≤0) ，即默认返回发生变更的行数。
*
* @return 默认主键序列
*/
default SQLUpdateAction defaultKeyIndex() {
return setKeyIndex(-1); // will return changed lines number
}
easysql-api/src/main/java/cc/carm/lib/easysql/api/action/SQLUpdateBatchAction.java
+6
View File
@@ -7,6 +7,12 @@ import java.util.List;
public interface SQLUpdateBatchAction extends SQLAction<List<Integer>> {
/**
* 添加一条批量执行的SQL语句
*
* @param sql SQL语句
* @return {@link SQLUpdateBatchAction}
*/
SQLUpdateBatchAction addBatch(@NotNull String sql);
}
easysql-api/src/main/java/cc/carm/lib/easysql/api/action/query/PreparedQueryAction.java
+19
View File
@@ -7,10 +7,29 @@ import java.util.function.Consumer;
public interface PreparedQueryAction extends QueryAction {
/**
* 设定SQL语句中所有 ? 对应的参数
*
* @param params 参数内容
* @return {@link PreparedQueryAction}
*/
PreparedQueryAction setParams(@Nullable Object... params);
/**
* 设定SQL语句中所有 ? 对应的参数
*
* @param params 参数内容
* @return {@link PreparedQueryAction}
*/
PreparedQueryAction setParams(@Nullable Iterable<Object> params);
/**
* 直接对 {@link PreparedStatement} 进行处理
*
* @param statement {@link Consumer} 处理操作
* 若为空则不进行处理
* @return {@link PreparedQueryAction}
*/
PreparedQueryAction handleStatement(@Nullable Consumer<PreparedStatement> statement);
}
easysql-api/src/main/java/cc/carm/lib/easysql/api/action/query/QueryAction.java
-1
View File
@@ -1,7 +1,6 @@
package cc.carm.lib.easysql.api.action.query;
import cc.carm.lib.easysql.api.SQLAction;
import cc.carm.lib.easysql.api.SQLQuery;
public interface QueryAction extends SQLAction<SQLQuery> {
easysql-api/src/main/java/cc/carm/lib/easysql/api/SQLQuery.java → easysql-api/src/main/java/cc/carm/lib/easysql/api/action/query/SQLQuery.java
+12 -2
View File
@@ -1,6 +1,6 @@
package cc.carm.lib.easysql.api;
package cc.carm.lib.easysql.api.action.query;
import cc.carm.lib.easysql.api.action.query.QueryAction;
import cc.carm.lib.easysql.api.SQLManager;
import java.sql.Connection;
import java.sql.ResultSet;
@@ -15,8 +15,18 @@ public interface SQLQuery extends AutoCloseable {
*/
long getExecuteTime();
/**
* 得到承载该SQLQuery的对应{@link SQLManager}
*
* @return {@link SQLManager}
*/
SQLManager getManager();
/**
* 得到承载该SQLQuery的对应{@link QueryAction}
*
* @return {@link QueryAction} 或 {@link PreparedQueryAction}
*/
QueryAction getAction();
ResultSet getResultSet();
easysql-api/src/main/java/cc/carm/lib/easysql/api/builder/QueryBuilder.java
+20
View File
@@ -7,10 +7,30 @@ import org.jetbrains.annotations.NotNull;
public interface QueryBuilder extends SQLBuilder {
/**
* 通过一条 SQL语句创建查询
*
* @param sql SQL语句
* @return {@link QueryAction}
* @deprecated 存在SQL注入风险，请使用 {@link QueryBuilder#withPreparedSQL(String)}
*/
@Deprecated
QueryAction withSQL(@NotNull String sql);
/**
* 通过一条 SQL语句创建预查询
*
* @param sql SQL语句
* @return {@link PreparedQueryAction}
*/
PreparedQueryAction withPreparedSQL(@NotNull String sql);
/**
* 创建表查询
*
* @param tableName 表名
* @return {@link TableQueryBuilder}
*/
TableQueryBuilder inTable(@NotNull String tableName);
}
easysql-api/src/main/java/cc/carm/lib/easysql/api/enums/ReturnedType.java
-9
View File
@@ -1,9 +0,0 @@
package cc.carm.lib.easysql.api.enums;
public enum ReturnedType {
AUTO_INCREASE_KEY,
CHANGED_LINES
}
easysql-api/src/main/java/cc/carm/lib/easysql/api/util/TimeDateUtils.java
+38 -2
View File
@@ -11,19 +11,42 @@ public class TimeDateUtils {
public TimeDateUtils() {
}
/**
* 得到当前时间文本。
*
* @return 时间文本 格式{@link TimeDateUtils#getFormat()}
*/
public static String getCurrentTime() {
return getFormat().format(new Date());
return getTimeString(System.currentTimeMillis());
}
/**
* 得到一个时间戳的文本
*
* @param timeMillis 时间戳
* @return 时间文本 格式{@link TimeDateUtils#getFormat()}
*/
public static String getTimeString(long timeMillis) {
return getFormat().format(new Date(timeMillis));
}
/**
* 得到一个日期时间的文本
*
* @param time 日期时间
* @return 时间文本 格式{@link TimeDateUtils#getFormat()}
*/
public static String getTimeString(Date time) {
return getFormat().format(time);
}
public static long getTimeMillis(String timeString) {
/**
* 得到一个时间文本的时间戳
*
* @param timeString 时间文本
* @return 时间戳 格式{@link TimeDateUtils#getFormat()}
*/
public static long parseTimeMillis(String timeString) {
if (timeString == null) {
return -1L;
} else {
@@ -35,6 +58,13 @@ public class TimeDateUtils {
}
}
/**
* 得到一个时间文本的对应日期实例
*
* @param timeString 时间文本
* @return 日期实例 格式{@link TimeDateUtils#getFormat()}
*/
public static Date getTimeDate(String timeString) {
if (timeString == null) {
return null;
@@ -47,6 +77,12 @@ public class TimeDateUtils {
}
}
/**
* 将秒数转化为 DD:hh:mm:ss 格式
*
* @param allSeconds 秒数
* @return DD:hh:mm:ss格式文本
*/
public static String toDHMSStyle(long allSeconds) {
long days = allSeconds / 86400L;
long hours = allSeconds % 86400L / 3600L;
easysql-demo/src/main/java/EasySQLDemo.java
+1 -1
View File
@@ -1,5 +1,5 @@
import cc.carm.lib.easysql.api.SQLManager;
import cc.carm.lib.easysql.api.SQLQuery;
import cc.carm.lib.easysql.api.action.query.SQLQuery;
import cc.carm.lib.easysql.api.util.TimeDateUtils;
import cc.carm.lib.easysql.api.util.UUIDUtil;
easysql-impl/src/main/java/cc/carm/lib/easysql/action/PreparedSQLUpdateActionImpl.java
+12
View File
@@ -10,6 +10,7 @@ import java.sql.Connection;
import java.sql.PreparedStatement;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.util.ArrayList;
import java.util.List;
public class PreparedSQLUpdateActionImpl extends SQLUpdateActionImpl implements PreparedSQLUpdateAction {
@@ -37,6 +38,17 @@ public class PreparedSQLUpdateActionImpl extends SQLUpdateActionImpl implements
return this;
}
@Override
public PreparedSQLUpdateAction setParams(@Nullable Iterable<Object> params) {
if (params == null) {
return setParams((Object[]) null);
} else {
List<Object> paramsList = new ArrayList<>();
params.forEach(paramsList::add);
return setParams(paramsList.toArray());
}
}
@Override
public @NotNull Integer execute() throws SQLException {
int value = -1;
easysql-impl/src/main/java/cc/carm/lib/easysql/action/query/PreparedQueryActionImpl.java
+1 -6
View File
@@ -1,7 +1,5 @@
package cc.carm.lib.easysql.action.query;
import cc.carm.lib.easysql.api.SQLAction;
import cc.carm.lib.easysql.api.SQLQuery;
import cc.carm.lib.easysql.api.action.query.PreparedQueryAction;
import cc.carm.lib.easysql.manager.SQLManagerImpl;
import cc.carm.lib.easysql.query.SQLQueryImpl;
@@ -15,7 +13,6 @@ import java.sql.ResultSet;
import java.sql.SQLException;
import java.util.ArrayList;
import java.util.List;
import java.util.function.BiConsumer;
import java.util.function.Consumer;
public class PreparedQueryActionImpl extends QueryActionImpl implements PreparedQueryAction {
@@ -39,9 +36,7 @@ public class PreparedQueryActionImpl extends QueryActionImpl implements Prepared
return setParams((Object[]) null);
} else {
List<Object> paramsList = new ArrayList<>();
for (Object param : params) {
paramsList.add(param);
}
params.forEach(paramsList::add);
return setParams(paramsList.toArray());
}
}
easysql-impl/src/main/java/cc/carm/lib/easysql/action/query/QueryActionImpl.java
+1 -1
View File
@@ -2,7 +2,7 @@ package cc.carm.lib.easysql.action.query;
import cc.carm.lib.easysql.action.AbstractSQLAction;
import cc.carm.lib.easysql.api.SQLAction;
import cc.carm.lib.easysql.api.SQLQuery;
import cc.carm.lib.easysql.api.action.query.SQLQuery;
import cc.carm.lib.easysql.api.action.query.QueryAction;
import cc.carm.lib.easysql.manager.SQLManagerImpl;
import cc.carm.lib.easysql.query.SQLQueryImpl;
easysql-impl/src/main/java/cc/carm/lib/easysql/builder/impl/QueryBuilderImpl.java
+1
View File
@@ -16,6 +16,7 @@ public class QueryBuilderImpl extends AbstractSQLBuilder implements QueryBuilder
}
@Override
@Deprecated
public QueryAction withSQL(@NotNull String sql) {
return new QueryActionImpl(getManager(), sql);
}
easysql-impl/src/main/java/cc/carm/lib/easysql/manager/SQLManagerImpl.java
+1 -1
View File
@@ -5,7 +5,7 @@ import cc.carm.lib.easysql.action.PreparedSQLUpdateActionImpl;
import cc.carm.lib.easysql.action.SQLUpdateActionImpl;
import cc.carm.lib.easysql.action.SQLUpdateBatchActionImpl;
import cc.carm.lib.easysql.api.SQLManager;
import cc.carm.lib.easysql.api.SQLQuery;
import cc.carm.lib.easysql.api.action.query.SQLQuery;
import cc.carm.lib.easysql.api.action.PreparedSQLUpdateAction;
import cc.carm.lib.easysql.api.action.PreparedSQLUpdateBatchAction;
import cc.carm.lib.easysql.api.action.SQLUpdateBatchAction;
easysql-impl/src/main/java/cc/carm/lib/easysql/query/SQLQueryImpl.java
+1 -1
View File
@@ -1,7 +1,7 @@
package cc.carm.lib.easysql.query;
import cc.carm.lib.easysql.action.query.QueryActionImpl;
import cc.carm.lib.easysql.api.SQLQuery;
import cc.carm.lib.easysql.api.action.query.SQLQuery;
import cc.carm.lib.easysql.manager.SQLManagerImpl;
import java.sql.Connection;