Major Enhancements for Spring

CHANGELOG.md

@@ -8,18 +8,28 @@ GitHub milestone: [https://github.com/mybatis/mybatis-dynamic-sql/issues?q=miles
 
 ### General Announcements
 
-This release includes a significant refactoring of the classes in the "org.mybatis.dynamic.sql.select.function" package. The new classes are more consistent and flexible and should be compatible with existing code at the source level (meaning that code should be recompiled for the new version of the library).
+This release includes major improvements to the Spring support in the library. Spring support is now functionally equivalent to MyBatis support.
 
-If you have written your own set of functions to extend the library, you will notice that the base classes 'AbstractFunction" and "AbstractMultipleColumnArithmeticFunction" are now deprecated. Their replacement classes are "AbstractUniTypeFunction" and "OperatorFunction" respectively.
+This release includes a significant refactoring of the classes in the "org.mybatis.dynamic.sql.select.function" package. The new classes are more consistent and flexible and should be compatible with existing code at the source level (meaning code should be recompiled for the new version of the library). If you have written your own set of functions to extend the library, you will notice that the base classes 'AbstractFunction" and "AbstractMultipleColumnArithmeticFunction" are now deprecated. Their replacement classes are "AbstractUniTypeFunction" and "OperatorFunction" respectively.
+
+With this release, we deprecated several insert methods because they were inconsistently named or awkward. All deprecated methods have documented direct replacements.
+
+In the next major release of the library, all deprecated code will be removed.
 
 ### Added
 
 - Added a general insert statement that does not require a separate record class to hold values for the insert. ([#201](https://github.com/mybatis/mybatis-dynamic-sql/issues/201))
-- Added the capability to specify a rendering strategy on a column to override the defaut rendering strategy for a statement. This will allow certain edge cases where a parameter marker needs to be formatted in a unique way (for example, "::jsonb" needs to be added to parameter markers for JSON fields in PostgreSQL) ([#200](https://github.com/mybatis/mybatis-dynamic-sql/issues/200))
+- Added the capability to specify a rendering strategy on a column to override the default rendering strategy for a statement. This will allow certain edge cases where a parameter marker needs to be formatted uniquely (for example, "::jsonb" needs to be added to parameter markers for JSON fields in PostgreSQL) ([#200](https://github.com/mybatis/mybatis-dynamic-sql/issues/200))
 - Added the ability to write a function that will change the column data type ([#197](https://github.com/mybatis/mybatis-dynamic-sql/issues/197))
 - Added the `applyOperator` function to make it easy to use non-standard database operators in expressions ([#220](https://github.com/mybatis/mybatis-dynamic-sql/issues/220))
-- Added convenience methods for count(column) and count(distinct column)([#221](https://github.com/mybatis/mybatis-dynamic-sql/issues/221))
-- Added support for union queries in Kotlin([#187](https://github.com/mybatis/mybatis-dynamic-sql/issues/187))
+- Added convenience methods for count(column) and count(distinct column) ([#221](https://github.com/mybatis/mybatis-dynamic-sql/issues/221))
+- Added support for union queries in Kotlin ([#187](https://github.com/mybatis/mybatis-dynamic-sql/issues/187))
+- Many enhancements for Spring including:
+  - Fixed a bug where multi-row insert statements did not render properly for Spring  ([#224](https://github.com/mybatis/mybatis-dynamic-sql/issues/224))
+  - Added support for a parameter type converter for use cases where the Java type of a column does not match the database column type  ([#131](https://github.com/mybatis/mybatis-dynamic-sql/issues/131))
+  - Added a utility class which simplifies the use of the named parameter JDBC template for Java code - `org.mybatis.dynamic.sql.util.spring.NamedParameterJdbcTemplateExtensions`
+  - Added support for general inserts, multi-row inserts, batch inserts in the Kotlin DSL for Spring ([#225](https://github.com/mybatis/mybatis-dynamic-sql/issues/225))
+  - Added support for generated keys in the Kotlin DSL for Spring  ([#226](https://github.com/mybatis/mybatis-dynamic-sql/issues/226))
 
 ## Release 1.1.4 - November 23, 2019
 
@@ -53,7 +63,7 @@ GitHub milestone: [https://github.com/mybatis/mybatis-dynamic-sql/issues?q=miles
 ### Added
 
 - Changed the public SQLBuilder API to accept Collection instead of List for in conditions and batch record inserts. This should have no impact on existing code, but allow for some future flexibility ([#88](https://github.com/mybatis/mybatis-dynamic-sql/pull/88))
-- Added the ability have have table catalog and/or schema calculated at query runtime. This is useful for situations where there are different database schemas for different environments, or in some sharding situations ([#92](https://github.com/mybatis/mybatis-dynamic-sql/pull/92))
+- Added the ability to have table catalog and/or schema calculated at runtime. This is useful for situations where there are different database schemas for different environments, or in some sharding situations ([#92](https://github.com/mybatis/mybatis-dynamic-sql/pull/92))
 - Add support for paging queries with "offset" and "fetch first" - this seems to be standard on most databases ([#96](https://github.com/mybatis/mybatis-dynamic-sql/pull/96))
 - Added the ability to call a builder method on any intermediate object in a select statement and receive a fully rendered statement. This makes it easier to build very dynamic queries ([#106](https://github.com/mybatis/mybatis-dynamic-sql/pull/106))
 - Add the ability to modify values on any condition before they are placed in the parameter map ([#105](https://github.com/mybatis/mybatis-dynamic-sql/issues/105))

src/main/java/org/mybatis/dynamic/sql/BindableColumn.java

@@ -26,9 +26,7 @@
  * 
  * @author Jeff Butler
  *
- * @param <T> - even though the type is not directly used in this class,
- *     it is used by the compiler to match columns with conditions so it should
- *     not be removed.
+ * @param <T> - the Java type that corresponds to this column
 */
 public interface BindableColumn<T> extends BasicColumn {
 
@@ -49,4 +47,8 @@ default Optional<String> typeHandler() {
     default Optional<RenderingStrategy> renderingStrategy() {
         return Optional.empty();
     }
+
+    default Object convertParameterType(T value) {
+        return value;
+    }
 }

src/main/java/org/mybatis/dynamic/sql/ParameterTypeConverter.java

@@ -0,0 +1,54 @@
+/**
+ *    Copyright 2016-2020 the original author or authors.
+ *
+ *    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 org.mybatis.dynamic.sql;
+
+/**
+ * A parameter type converter is used to change a parameter value from one type to another
+ * during statement rendering and before the parameter is placed into the parameter map. This can be used
+ * to somewhat mimic the function of a MyBatis type handler for runtimes such as Spring that don't have
+ * a corresponding concept.
+ * 
+ * <p>Since Spring does not have the concept of type handlers, it is a best practice to only use
+ * Java data types that have a clear correlation to SQL data types (for example Java String correlates
+ * automatically with VARCHAR). Using a parameter type converter will allow you to use data types in your
+ * model classes that would otherwise be difficult to use with Spring.
+ *
+ * <p>A parameter type converter is associated with a SqlColumn.
+ * 
+ * <p>This interface is based on Spring's general Converter interface and is intentionally compatible with it.
+ * Existing converters may be reused if they are marked with this additional interface.
+ *
+ * <p>The converter is only used for parameters in a parameter map. It is not used for result set processing.
+ * It is also not used for insert statements that are based on an external record class. The converter will be called
+ * in the following circumstances:
+ *
+ * <ul>
+ *     <li>Parameters in a general insert statement (for the Value and ValueWhenPresent mappings)</li>
+ *     <li>Parameters in an update statement (for the Value and ValueWhenPresent mappings)</li>
+ *     <li>Parameters in a where clause in any statement (for conditions that accept a value or multiple values)</li>
+ * </ul>
+ * 
+ * @param <S> Source Type
+ * @param <T> Target Type
+ *
+ * @see SqlColumn
+ * @author Jeff Butler
+ * @since 1.1.5
+ */
+@FunctionalInterface
+public interface ParameterTypeConverter<S, T> {
+    T convert(S source);
+}

src/main/java/org/mybatis/dynamic/sql/SqlBuilder.java

@@ -136,21 +136,84 @@ static DeleteDSL<DeleteModel> deleteFrom(SqlTable table) {
     static <T> InsertDSL.IntoGatherer<T> insert(T record) {
         return InsertDSL.insert(record);
     }
-
+
+    /**
+     * Insert a Batch of records. The model object is structured to support bulk inserts with JDBC batch support.
+     *
+     * @param records records to insert
+     * @param <T> the type of record to insert
+     * @return the next step in the DSL
+     * @deprecated Use {@link SqlBuilder#insertBatch(Object[])} instead
+     */
+    @Deprecated
     @SafeVarargs
     static <T> BatchInsertDSL.IntoGatherer<T> insert(T...records) {
-        return BatchInsertDSL.insert(records);
+        return insertBatch(records);
     }
-
+
+    /**
+     * Insert a Batch of records. The model object is structured to support bulk inserts with JDBC batch support.
+     *
+     * @param records records to insert
+     * @param <T> the type of record to insert
+     * @return the next step in the DSL
+     * @deprecated Use {@link SqlBuilder#insertBatch(Collection)} instead
+     */
+    @Deprecated
     static <T> BatchInsertDSL.IntoGatherer<T> insert(Collection<T> records) {
+        return insertBatch(records);
+    }
+
+    /**
+     * Insert a Batch of records. The model object is structured to support bulk inserts with JDBC batch support.
+     *
+     * @param records records to insert
+     * @param <T> the type of record to insert
+     * @return the next step in the DSL
+     */
+    @SafeVarargs
+    static <T> BatchInsertDSL.IntoGatherer<T> insertBatch(T...records) {
         return BatchInsertDSL.insert(records);
     }
-
+
+    /**
+     * Insert a Batch of records. The model object is structured to support bulk inserts with JDBC batch support.
+     *
+     * @param records records to insert
+     * @param <T> the type of record to insert
+     * @return the next step in the DSL
+     */
+    static <T> BatchInsertDSL.IntoGatherer<T> insertBatch(Collection<T> records) {
+        return BatchInsertDSL.insert(records);
+    }
+
+    /**
+     * Insert multiple records in a single statement. The model object is structured as a single insert statement with
+     * multiple values clauses. This statement is suitable for use with a small number of records. It is not suitable
+     * for large bulk inserts as it is possible to exceed the limit of parameter markers in a prepared statement.
+     * 
+     * <p>For large bulk inserts, see {@link SqlBuilder#insertBatch(Object[])}
+     *
+     * @param records records to insert
+     * @param <T> the type of record to insert
+     * @return the next step in the DSL
+     */
     @SafeVarargs
     static <T> MultiRowInsertDSL.IntoGatherer<T> insertMultiple(T...records) {
         return MultiRowInsertDSL.insert(records);
     }
-
+
+    /**
+     * Insert multiple records in a single statement. The model object is structured as a single insert statement with
+     * multiple values clauses. This statement is suitable for use with a small number of records. It is not suitable
+     * for large bulk inserts as it is possible to exceed the limit of parameter markers in a prepared statement.
+     *
+     * <p>For large bulk inserts, see {@link SqlBuilder#insertBatch(Collection)}
+     *
+     * @param records records to insert
+     * @param <T> the type of record to insert
+     * @return the next step in the DSL
+     */
     static <T> MultiRowInsertDSL.IntoGatherer<T> insertMultiple(Collection<T> records) {
         return MultiRowInsertDSL.insert(records);
     }

src/main/java/org/mybatis/dynamic/sql/SqlColumn.java

@@ -19,6 +19,7 @@
 import java.util.Objects;
 import java.util.Optional;
 
+import org.jetbrains.annotations.NotNull;
 import org.mybatis.dynamic.sql.render.RenderingStrategy;
 import org.mybatis.dynamic.sql.render.TableAliasCalculator;
 
@@ -31,22 +32,24 @@ public class SqlColumn<T> implements BindableColumn<T>, SortSpecification {
     protected String alias;
     protected String typeHandler;
     protected RenderingStrategy renderingStrategy;
-
+    protected ParameterTypeConverter<T, ?> parameterTypeConverter;
+
     private SqlColumn(Builder builder) {
         name = Objects.requireNonNull(builder.name);
         jdbcType = builder.jdbcType;
         table = Objects.requireNonNull(builder.table);
         typeHandler = builder.typeHandler;
     }
-    
-    protected SqlColumn(SqlColumn<?> sqlColumn) {
+
+    protected SqlColumn(SqlColumn<T> sqlColumn) {
         name = sqlColumn.name;
         table = sqlColumn.table;
         jdbcType = sqlColumn.jdbcType;
         isDescending = sqlColumn.isDescending;
         alias = sqlColumn.alias;
         typeHandler = sqlColumn.typeHandler;
         renderingStrategy = sqlColumn.renderingStrategy;
+        parameterTypeConverter = sqlColumn.parameterTypeConverter;
     }
 
     public String name() {
@@ -72,6 +75,11 @@ public Optional<String> typeHandler() {
         return Optional.ofNullable(typeHandler);
     }
 
+    @Override
+    public Object convertParameterType(T value) {
+        return parameterTypeConverter == null ? value : parameterTypeConverter.convert(value);
+    }
+
     @Override
     public SortSpecification descending() {
         SqlColumn<T> column = new SqlColumn<>(this);
@@ -107,19 +115,42 @@ public String renderWithTableAlias(TableAliasCalculator tableAliasCalculator) {
     public Optional<RenderingStrategy> renderingStrategy() {
         return Optional.ofNullable(renderingStrategy);
     }
-
-    public SqlColumn<T> withTypeHandler(String typeHandler) {
-        SqlColumn<T> column = new SqlColumn<>(this);
+
+    @NotNull
+    public <S> SqlColumn<S> withTypeHandler(String typeHandler) {
+        SqlColumn<S> column = copy();
         column.typeHandler = typeHandler;
         return column;
     }
 
+    @NotNull
     public <S> SqlColumn<S> withRenderingStrategy(RenderingStrategy renderingStrategy) {
-        SqlColumn<S> column = new SqlColumn<>(this);
+        SqlColumn<S> column = copy();
         column.renderingStrategy = renderingStrategy;
         return column;
     }
 
+    @NotNull
+    public <S> SqlColumn<S> withParameterTypeConverter(ParameterTypeConverter<S, ?> parameterTypeConverter) {
+        SqlColumn<S> column = copy();
+        column.parameterTypeConverter = parameterTypeConverter;
+        return column;
+    }
+
+    /**
+     * This method helps us tell a bit of fiction to the Java compiler. Java, for better or worse,
+     * does not carry generic type information through chained methods. We want to enable method
+     * chaining in the "with" methods. With this bit of fiction, we force the compiler to delay type
+     * inference to the last method in the chain.
+     *
+     * @param <S> the type. Will be the same as T for this usage.
+     * @return a new SqlColumn of type S (S is the same as T)
+     */
+    @SuppressWarnings("unchecked")
+    private <S> SqlColumn<S> copy() {
+        return new SqlColumn<>((SqlColumn<S>) this);
+    }
+
     private String applyTableAlias(String tableAlias) {
         return tableAlias + "." + name(); //$NON-NLS-1$
     }

src/main/java/org/mybatis/dynamic/sql/insert/AbstractMultiRowInsertModel.java

@@ -1,5 +1,5 @@
 /**
- *    Copyright 2016-2019 the original author or authors.
+ *    Copyright 2016-2020 the original author or authors.
  *
  *    Licensed under the Apache License, Version 2.0 (the "License");
  *    you may not use this file except in compliance with the License.

src/main/java/org/mybatis/dynamic/sql/insert/BatchInsertDSL.java

@@ -1,5 +1,5 @@
 /**
- *    Copyright 2016-2019 the original author or authors.
+ *    Copyright 2016-2020 the original author or authors.
  *
  *    Licensed under the Apache License, Version 2.0 (the "License");
  *    you may not use this file except in compliance with the License.
@@ -23,12 +23,13 @@
 import org.mybatis.dynamic.sql.SqlColumn;
 import org.mybatis.dynamic.sql.SqlTable;
 import org.mybatis.dynamic.sql.util.AbstractColumnMapping;
+import org.mybatis.dynamic.sql.util.Buildable;
 import org.mybatis.dynamic.sql.util.ConstantMapping;
 import org.mybatis.dynamic.sql.util.NullMapping;
 import org.mybatis.dynamic.sql.util.PropertyMapping;
 import org.mybatis.dynamic.sql.util.StringConstantMapping;
 
-public class BatchInsertDSL<T> {
+public class BatchInsertDSL<T> implements Buildable<BatchInsertModel<T>> {
 
     private Collection<T> records;
     private SqlTable table;
@@ -43,6 +44,7 @@ public <F> ColumnMappingFinisher<F> map(SqlColumn<F> column) {
         return new ColumnMappingFinisher<>(column);
     }
 
+    @Override
     public BatchInsertModel<T> build() {
         return BatchInsertModel.withRecords(records)
                 .withTable(table)

src/main/java/org/mybatis/dynamic/sql/insert/BatchInsertModel.java

@@ -1,5 +1,5 @@
 /**
- *    Copyright 2016-2019 the original author or authors.
+ *    Copyright 2016-2020 the original author or authors.
  *
  *    Licensed under the Apache License, Version 2.0 (the "License");
  *    you may not use this file except in compliance with the License.
@@ -17,6 +17,7 @@
 
 import java.util.Collection;
 
+import org.jetbrains.annotations.NotNull;
 import org.mybatis.dynamic.sql.insert.render.BatchInsert;
 import org.mybatis.dynamic.sql.insert.render.BatchInsertRenderer;
 import org.mybatis.dynamic.sql.render.RenderingStrategy;
@@ -27,6 +28,7 @@ private BatchInsertModel(Builder<T> builder) {
         super(builder);
     }
 
+    @NotNull
     public BatchInsert<T> render(RenderingStrategy renderingStrategy) {
         return BatchInsertRenderer.withBatchInsertModel(this)
                 .withRenderingStrategy(renderingStrategy)