[0.3.7] 版本更新

- `[A]` 为 UpdateBuilder 添加 `#addColumnValue(String,Object)` 方法。
- `[A]` 补充部分Builder的JavaDoc。

easysql-api/pom.xml

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

easysql-api/src/main/java/cc/carm/lib/easysql/api/builder/ConditionalBuilder.java

@@ -13,42 +13,72 @@ public interface ConditionalBuilder<B extends ConditionalBuilder<B, T>, T extend
     /**
      * 将现有条件构建完整的SQL语句用于执行。
      *
-	 * @return {@link cc.carm.lib.easysql.api.SQLAction}
+     * @return {@link SQLAction}
      */
     T build();
 
     /**
-	 * 设定取出的条数
+     * 设定限定的条目数
      *
      * @param limit 条数限制
      * @return {@link B}
      */
     B setLimit(int limit);
 
+    /**
+     * 直接设定条件的源文本,不需要以WHERE开头。
+     * <br>如 {@code id = 1 AND name = 'test' OR name = 'test2'} 。
+     *
+     * @param condition 条件文本，不需要以WHERE开头。
+     * @return {@link B}
+     */
     B setConditions(@Nullable String condition);
 
+    /**
+     * 直接设定每个条件的文本与其对应数值,将以AND链接，且不需要以WHERE开头。
+     * <br>条件如 {@code id = ? }，问号将被以对应的数值填充。。
+     *
+     * @param conditionSQLs 条件内容，将以AND链接，且不需要以WHERE开头。
+     * @return {@link B}
+     */
     B setConditions(LinkedHashMap<@NotNull String, @Nullable Object> conditionSQLs);
 
     B addCondition(@Nullable String condition);
 
-	B addCondition(@NotNull String queryName, @NotNull String operator, @Nullable Object queryValue);
+    B addCondition(@NotNull String columnName, @NotNull String operator, @Nullable Object queryValue);
 
-	default B addCondition(@NotNull String queryName, @Nullable Object queryValue) {
+    default B addCondition(@NotNull String columnName, @Nullable Object queryValue) {
-		return addCondition(queryName, "=", queryValue);
+        return addCondition(columnName, "=", queryValue);
     }
 
-	B addCondition(@NotNull String[] queryNames, @Nullable Object[] queryValues);
+    B addCondition(@NotNull String[] columnNames, @Nullable Object[] queryValues);
 
-	B addNotNullCondition(@NotNull String queryName);
+    B addNotNullCondition(@NotNull String columnName);
 
-	default B addTimeCondition(@NotNull String queryName, long startMillis, long endMillis) {
+    /**
-		return addTimeCondition(queryName,
+     * 添加时间的限定条件。 若设定了开始时间，则限定条件为 {@code endMillis >= startMillis}；
+     *
+     * @param columnName  判断的行
+     * @param startMillis 开始时间戳，若<0则不作限定
+     * @param endMillis   结束时间戳，若<0则不作限定
+     * @return {@link B}
+     */
+    default B addTimeCondition(@NotNull String columnName, long startMillis, long endMillis) {
+        return addTimeCondition(columnName,
                 startMillis > 0 ? new Date(startMillis) : null,
                 endMillis > 0 ? new Date(endMillis) : null
         );
     }
 
-	B addTimeCondition(@NotNull String queryName, @Nullable java.util.Date startDate, @Nullable java.util.Date endDate);
+    /**
+     * 添加时间的限定条件。 若设定了开始时间，则限定条件为 {@code endDate >= startTime}；
+     *
+     * @param columnName 判断的行
+     * @param startDate  开始时间，若为null则不作限定
+     * @param endDate    结束时间，若为null则不作限定
+     * @return {@link B}
+     */
+    B addTimeCondition(@NotNull String columnName, @Nullable java.util.Date startDate, @Nullable java.util.Date endDate);
 
 
 }

easysql-api/src/main/java/cc/carm/lib/easysql/api/builder/UpdateBuilder.java

@@ -1,6 +1,8 @@
 package cc.carm.lib.easysql.api.builder;
 
 import cc.carm.lib.easysql.api.SQLAction;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
 
 import java.util.LinkedHashMap;
 
@@ -8,11 +10,45 @@ public interface UpdateBuilder extends ConditionalBuilder<UpdateBuilder, SQLActi
 
     String getTableName();
 
-	UpdateBuilder setColumnValues(LinkedHashMap<String, Object> columnData);
+    /**
+     * 添加一条需要更新的字段名与值
+     *
+     * @param columnName  字段名
+     * @param columnValue 字段名对应的值
+     * @return {@link UpdateBuilder}
+     * @since 0.3.7
+     */
+    UpdateBuilder addColumnValue(@NotNull String columnName, @Nullable Object columnValue);
 
-	UpdateBuilder setColumnValues(String[] columnNames, Object[] columnValues);
+    /**
+     * 设定更新的全部字段值 <b>(此操作会覆盖之前的设定)</b>
+     * <p> <b>此操作会覆盖之前的设定</b>
+     *
+     * @param columnData 字段名和值的键值对
+     * @return {@link UpdateBuilder}
+     */
+    UpdateBuilder setColumnValues(LinkedHashMap<@NotNull String, @Nullable Object> columnData);
 
-	default UpdateBuilder setColumnValues(String columnName, Object columnValue) {
+    /**
+     * 设定更新的全部字段值 <b>(此操作会覆盖之前的设定)</b>
+     * <p> <b>此操作会覆盖之前的设定</b>
+     *
+     * @param columnNames  字段名
+     * @param columnValues 字段名对应的值
+     * @return {@link UpdateBuilder}
+     */
+    UpdateBuilder setColumnValues(@NotNull String[] columnNames, @Nullable Object[] columnValues);
+
+    /**
+     * 设定更新的全部字段值 <b>(此操作会覆盖之前的设定)</b>
+     * <p> 如需同时更新多条字段，请使用 {@link #setColumnValues(String[], Object[])} 或 {@link #setColumnValues(LinkedHashMap)}
+     * <br>也可以使用 {@link #addColumnValue(String, Object)} 一条条的添加字段
+     *
+     * @param columnName  字段名
+     * @param columnValue 字段名对应的值
+     * @return {@link UpdateBuilder}
+     */
+    default UpdateBuilder setColumnValues(@NotNull String columnName, @Nullable Object columnValue) {
         return setColumnValues(new String[]{columnName}, new Object[]{columnValue});
     }
 

easysql-api/src/main/java/cc/carm/lib/easysql/api/builder/UpsertBuilder.java

@@ -10,6 +10,8 @@ public interface UpsertBuilder {
 
     String getTableName();
 
-	UpsertBuilder setColumnNames(String[] columnNames, String updateColumn);
+    default UpsertBuilder setColumnNames(String[] columnNames, String updateColumn) {
+        throw new UnsupportedOperationException("Please use REPLACE .");
+    }
 
 }

easysql-impl/pom.xml

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

easysql-impl/src/main/java/cc/carm/lib/easysql/builder/impl/AbstractConditionalBuilder.java

@@ -53,40 +53,40 @@ public abstract class AbstractConditionalBuilder<B extends ConditionalBuilder<B,
 
 	@Override
 	public B addCondition(
-			@NotNull String queryName, @NotNull String operator, @Nullable Object queryValue
+			@NotNull String columnName, @NotNull String operator, @Nullable Object queryValue
 	) {
-		addCondition(withBackQuote(queryName) + " " + operator + " ?");
+		addCondition(withBackQuote(columnName) + " " + operator + " ?");
 		this.conditionParams.add(queryValue);
 		return getThis();
 	}
 
 	@Override
 	public B addCondition(
-			@NotNull String[] queryNames, @Nullable Object[] queryValues
+			@NotNull String[] columnNames, @Nullable Object[] queryValues
 	) {
-		if (queryValues == null || queryNames.length != queryValues.length) {
+		if (queryValues == null || columnNames.length != queryValues.length) {
 			throw new RuntimeException("queryNames are not match with queryValues");
 		}
-		for (int i = 0; i < queryNames.length; i++) {
+		for (int i = 0; i < columnNames.length; i++) {
-			addCondition(queryNames[i], queryValues[i]);
+			addCondition(columnNames[i], queryValues[i]);
 		}
 		return getThis();
 	}
 
 
 	@Override
-	public B addNotNullCondition(@NotNull String queryName) {
+	public B addNotNullCondition(@NotNull String columnName) {
-		return addCondition(withBackQuote(queryName) + " IS NOT NULL");
+		return addCondition(withBackQuote(columnName) + " IS NOT NULL");
 	}
 
 
 	@Override
 	public B addTimeCondition(
-			@NotNull String queryName, @Nullable Date startDate, @Nullable Date endDate
+			@NotNull String columnName, @Nullable Date startDate, @Nullable Date endDate
 	) {
 		if (startDate == null && endDate == null) return getThis(); // 都不限定时间，不用判断了
 		if (startDate != null) {
-			addCondition(withBackQuote(queryName) + " BETWEEN ? AND ?");
+			addCondition(withBackQuote(columnName) + " BETWEEN ? AND ?");
 			this.conditionParams.add(startDate);
 			if (endDate != null) {
 				this.conditionParams.add(endDate);
@@ -100,7 +100,7 @@ public abstract class AbstractConditionalBuilder<B extends ConditionalBuilder<B,
 				}
 			}
 		} else {
-			addCondition(queryName, "<=", endDate);
+			addCondition(columnName, "<=", endDate);
 		}
 		return getThis();
 	}

easysql-impl/src/main/java/cc/carm/lib/easysql/builder/impl/UpdateBuilderImpl.java

@@ -6,8 +6,12 @@ import cc.carm.lib.easysql.api.action.PreparedSQLUpdateAction;
 import cc.carm.lib.easysql.api.builder.UpdateBuilder;
 import cc.carm.lib.easysql.manager.SQLManagerImpl;
 import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
 
-import java.util.*;
+import java.util.ArrayList;
+import java.util.Iterator;
+import java.util.LinkedHashMap;
+import java.util.List;
 
 import static cc.carm.lib.easysql.api.SQLBuilder.withBackQuote;
 
@@ -17,12 +21,12 @@ public class UpdateBuilderImpl
 
     String tableName;
 
-	List<String> columnNames;
+    @NotNull LinkedHashMap<String, Object> columnData;
-	List<Object> columnValues;
 
     public UpdateBuilderImpl(@NotNull SQLManagerImpl manager, @NotNull String tableName) {
         super(manager);
         this.tableName = tableName;
+        this.columnData = new LinkedHashMap<>();
     }
 
     @Override
@@ -32,12 +36,12 @@ public class UpdateBuilderImpl
 
         sqlBuilder.append("UPDATE ").append(withBackQuote(getTableName())).append(" SET ");
 
-		Iterator<String> iterator = this.columnNames.iterator();
+        Iterator<String> iterator = this.columnData.keySet().iterator();
         while (iterator.hasNext()) {
             sqlBuilder.append(withBackQuote(iterator.next())).append(" = ?");
             if (iterator.hasNext()) sqlBuilder.append(" , ");
         }
-		List<Object> allParams = new ArrayList<>(this.columnValues);
+        List<Object> allParams = new ArrayList<>(this.columnData.values());
 
         if (hasConditions()) {
             sqlBuilder.append(" ").append(buildConditionSQL());
@@ -55,24 +59,27 @@ public class UpdateBuilderImpl
     }
 
     @Override
-	public UpdateBuilder setColumnValues(LinkedHashMap<String, Object> columnData) {
+    public UpdateBuilder addColumnValue(@NotNull String columnName, Object columnValue) {
-		this.columnNames = new ArrayList<>();
+        this.columnData.put(columnName, columnValue);
-		this.columnValues = new ArrayList<>();
-		columnData.forEach((name, value) -> {
-			this.columnNames.add(name);
-			this.columnValues.add(value);
-		});
         return this;
     }
 
     @Override
-	public UpdateBuilder setColumnValues(String[] columnNames, Object[] columnValues) {
+    public UpdateBuilder setColumnValues(LinkedHashMap<String, Object> columnData) {
+        this.columnData = columnData;
+        return this;
+    }
+
+    @Override
+    public UpdateBuilder setColumnValues(@NotNull String[] columnNames, @Nullable Object[] columnValues) {
         if (columnNames.length != columnValues.length) {
             throw new RuntimeException("columnNames are not match with columnValues");
         }
-		this.columnNames = Arrays.asList(columnNames);
+        LinkedHashMap<String, Object> columnData = new LinkedHashMap<>();
-		this.columnValues = Arrays.asList(columnValues);
+        for (int i = 0; i < columnNames.length; i++) {
-		return this;
+            columnData.put(columnNames[i], columnValues[i]);
+        }
+        return setColumnValues(columnData);
     }
 
 

example/easysql-demo/pom.xml

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

example/easysql-test/pom.xml

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

pom.xml

@@ -17,7 +17,7 @@
     <groupId>cc.carm.lib</groupId>
     <artifactId>easysql-parent</artifactId>
     <packaging>pom</packaging>
-    <version>0.3.6</version>
+    <version>0.3.7</version>
 
     <modules>
         <module>easysql-api</module>

with-pool/easysql-beecp/pom.xml

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

with-pool/easysql-hikaricp/pom.xml

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