Documentation updates

Author: jeffgbutler

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/site/markdown/docs/codingStandards.md

@@ -20,8 +20,8 @@ these general principles for functional style coding in Java:
     - Classes never expose a modifiable Map. A Map may be exposed with an unmodifiable Map.
 - Avoid direct use of null. Any Class attribute that could be null in normal use should be wrapped in a `java.util.Optional`
 - Avoid for loops (imperative) - use map/filter/reduce/collect (declarative) instead
-- Avoid Stream.forEach() - this method is only used for side effects, and we want no side-effects
-- Avoid Optional.ifPresent() - this method is only used for side effects, and we want no side-effects
+- Avoid Stream.forEach() - this method is only used for side effects, and we want no side effects
+- Avoid Optional.ifPresent() - this method is only used for side effects, and we want no side effects
 - The only good function is a pure function.  Some functions in the library accept an AtomicInteger which is a necessary evil
 - Classes with no internal attributes are usually a collection of utility functions. Use static methods in an interface instead.
 - Remember the single responsibility principle - methods do one thing, classes have one responsibility
@@ -43,7 +43,7 @@ We are committed to clean code.  This means:
 Remember the three rules of TDD:
 
 1. You may not write production code until you have written a failing unit test.
-2. You may not write more of a unit test that is sufficient to fail, and not compiling is failing. 
+2. You may not write more of a unit test than is sufficient to fail, and not compiling is failing. 
 3. You may not write more production code than is sufficient to passing the currently failing test.
 
 

src/site/markdown/docs/complexQueries.md

@@ -1,5 +1,5 @@
 # Complex Queries
-Enhancements in version 1.1.2 make it easier to code complex queries. The Select DSL is implemented as a set of related objects. As the select statement is built, intermediate objects of various types are returned from the various methods that implement the DSL. The select statement can be completed by calling the `build()` method many of the intermediate objects. Prior to version 1.1.2, it was necessary to call `build()` on the **last** intermediate object. This restriction has been removed and it is now possible to call `build()` on **any** intermediate object. This, along with several other enhancements, has simplified the coding of complex queries.
+Enhancements in version 1.1.2 make it easier to code complex queries. The Select DSL is implemented as a set of related objects. As the select statement is built, intermediate objects of various types are returned from the various methods that implement the DSL. The select statement can be completed by calling the `build()` method many of the intermediate objects. Prior to version 1.1.2, it was necessary to call `build()` on the **last** intermediate object. This restriction has been removed, and it is now possible to call `build()` on **any** intermediate object. This, along with several other enhancements, has simplified the coding of complex queries.
 
 For example, suppose you want to code a complex search on a Person table. The search parameters are id, first name, and last name. The rules are:
 
@@ -39,7 +39,7 @@ Notes:
 
 1. Note the use of the `var` keyword here. If you are using an older version of Java, the actual type is `QueryExpressionDSL<SelectModel>.QueryExpressionWhereBuilder`
 1. Here we are calling `where()` with no parameters. This sets up the builder to accept conditions further along in the code. If no conditions are added, then the where clause will not be rendered
-1. This `if` statement implements the rules of the search. If an ID is entered , use it. Otherwise do a fuzzy search based on first name and last name.
+1. This `if` statement implements the rules of the search. If an ID is entered , use it. Otherwise, do a fuzzy search based on first name and last name.
 1. The `then` statement on this line allows you to change the parameter value before it is placed in the parameter Map. In this case we are adding SQL wildcards to the start and end of the search String - but only if the search String is not null. If the search String is null, the lambda will not be called and the condition will not render
 1. This shows using a method reference instead of a lambda on the `then`. Method references allow you to more clearly express intent. Note also the use of the `isLikeWhenPresent` condition which is a built in condition that checks for nulls
 1. It is a good idea to limit the number of rows returned from a search. The library now supports `fetch first` syntax for limiting rows

src/site/markdown/docs/conditions.md

@@ -135,11 +135,11 @@ The following table shows the different supplied In conditions and how they will
 | IsIn| No | No| name in ('foo', null, 'bar') | name in (null) |
 | IsInWhenPresent | Yes | No | name in ('foo', 'bar') | No Render |
 | IsInCaseInsensitive | No | Yes | upper(name) in ('FOO', null, 'BAR') | upper(name) in (null) |
-| IsInCaseInsensiteveWhenPresent | Yes | Yes | upper(name) in ('FOO', 'BAR') | No Render |
+| IsInCaseInsensitiveWhenPresent | Yes | Yes | upper(name) in ('FOO', 'BAR') | No Render |
 | IsNotIn| No | No| name not in ('foo', null, 'bar') | name not in (null) |
 | IsNotInWhenPresent | Yes | No | name not in ('foo', 'bar') | No render |
 | IsNotInCaseInsensitive | No | Yes | upper(name) not in ('FOO', null, 'BAR') | upper(name) not in (null) |
-| IsNotInCaseInsensiteveWhenPresent | Yes | Yes | upper(name) not in ('FOO', 'BAR') | No Render |
+| IsNotInCaseInsensitiveWhenPresent | Yes | Yes | upper(name) not in ('FOO', 'BAR') | No Render |
 
 If none of these options meet your needs, there is an extension point where you can add your own filter and/or map conditions to the value stream. This gives you great flexibility to alter or filter the value list before the condition is rendered.
 
@@ -184,4 +184,4 @@ Then the condition could be used in a query as follows:
                     .render(RenderingStrategies.MYBATIS3);
 ```
 
-You can apply value stream operations to the conditions `IsIn`, `IsInCaseInsensitive`, `IsNotIn`, and `IsNotInCaseInsensitive`. With the case insensitive conditions, the library will automatically convert non-null strings to upper case after any value stream operation you specify.
+You can apply value stream operations to the conditions `IsIn`, `IsInCaseInsensitive`, `IsNotIn`, and `IsNotInCaseInsensitive`. With the case-insensitive conditions, the library will automatically convert non-null strings to upper case after any value stream operation you specify.

src/site/markdown/docs/databaseObjects.md

@@ -130,9 +130,9 @@ Whenever the table is referenced for rendering SQL, the name will be calculated
 
 ## Column Representation
 
-The class `org.mybatis.dynamic.sql.SqlColumn` is used to represent a column in a table or view. An `SqlColumn` is always associated with a `SqlTable`. In it's most basic form, the `SqlColumn` class holds a name and a reference to the `SqlTable` it is associated with. The table reference is required so that table aliases can be applied to columns in the rendering phase.
+The class `org.mybatis.dynamic.sql.SqlColumn` is used to represent a column in a table or view. An `SqlColumn` is always associated with a `SqlTable`. In its most basic form, the `SqlColumn` class holds a name and a reference to the `SqlTable` it is associated with. The table reference is required so that table aliases can be applied to columns in the rendering phase.
 
-The `SqlColumn` will be rendered in SQL based on the `RenderingStrategy` applied to the SQL statement. Typically the rendering strategy generates a string that represents a parameter marker in whatever SQL engine you are using. For example, MyBatis3 parameter markers are formatted as "#{some_attribute}". By default all columns are rendered with the same strategy. The library supplies rendering strategies that are appropriate for several SQL execution engines including MyBatis3 and Spring JDBC template.
+The `SqlColumn` will be rendered in SQL based on the `RenderingStrategy` applied to the SQL statement. Typically the rendering strategy generates a string that represents a parameter marker in whatever SQL engine you are using. For example, MyBatis3 parameter markers are formatted as "#{some_attribute}". By default, all columns are rendered with the same strategy. The library supplies rendering strategies that are appropriate for several SQL execution engines including MyBatis3 and Spring JDBC template.
 
 In some cases it is necessary to override the rendering strategy for a particular column - so the `SqlColumn` class supports specifying a rendering strategy for a column that will override the rendering strategy applied to a statement. A good example of this use case is with PostgreSQL. In that database it is required to add the string "::jsonb" to a prepared statement parameter marker when inserting or updating JSON fields, but not for other fields. A column based rendering strategy enables this.
 

src/site/markdown/docs/extending.md

@@ -48,15 +48,15 @@ public class CountAll implements BasicColumn {
 
 This class is used to implement the `count(*)` function in a SELECT list.  There are only three methods to implement:
 
-1. `renderWithTableAlias` - the default renderers will write the value returned from this function into the select list - or the GROUP BY expression.  If your item can be altered by a table alias, then here is where you change the return value based on the alias specified by the user.  For a `count(*)` expression, a table alias never applies, so we just return the same value whether or not an alias has been specified by the user.
+1. `renderWithTableAlias` - the default renderers will write the value returned from this function into the select list - or the GROUP BY expression.  If your item can be altered by a table alias, then here is where you change the return value based on the alias specified by the user.  For a `count(*)` expression, a table alias never applies, so we just return the same value regardless of whether an alias has been specified by the user.
 2.  `as` - this method can be called by the user to add an alias to the column expression.  In the method you should return a new instance of the object, with the alias passed by the user.
 3. `alias` - this method is called by the default renderer to obtain the column alias for the select list.  If there is no alias, then returning Optional.empty() will disable setting a column alias.
 
 ## Writing Custom Functions
 
 Relational database vendors provide hundreds of functions in their SQL dialects to aid with queries and offload processing to the database servers. This library does not try to implement every function that exists. This library also does not provide any abstraction over the different functions on different databases. For example, bitwise operator support is non-standard and it would be difficult to provide a function in this library that worked on every database. So we take the approach of supplying examples for a few very common functions, and making it relatively easy to write your own functions.
 
-The supplied functions are all in the `org.mybatis.dynamic.sql.select.function` package. They are all implemented as `BindableColumn` - meaning that they can appear in a select list or a where clause.
+The supplied functions are all in the `org.mybatis.dynamic.sql.select.function` package. They are all implemented as `BindableColumn` - meaning they can appear in a select list or a where clause.
 
 We provide some base classes that you can easily extend to write functions of your own. Those classes are as follows:
 
@@ -190,10 +190,10 @@ The library will pass the following parameters to the `getFormattedJdbcPlacehold
 
 1. `column` - the column definition for the current placeholder
 2. `prefix` - For INSERT statements the value will be "record", for all other statements (including inserts with selects) the value will be "parameters"
-3. `parameterName` - this will be the unique name for the the parameter.  For INSERT statements, the name will be the property of the inserted record that is mapped to this parameter.  For all other statements (including inserts with selects) a unique name will be generated by the library.  That unique name will also be used to place the value of the parameter into the parameters Map.
+3. `parameterName` - this will be the unique name for the parameter.  For INSERT statements, the name will be the property of the inserted record mapped to this parameter.  For all other statements (including inserts with selects) a unique name will be generated by the library.  That unique name will also be used to place the value of the parameter into the parameters Map.
 
 ## Writing Custom Renderers
 
-SQL rendering is accomplished by classes that are decoupled from the SQL model classes.  All the model classes have a `render` method that calls the built-in default renderers, but this is completely optional and you do not need to use it.  You can write your own rendering support if you are dissatisfied with the SQL produced by the default renderers.
+SQL rendering is accomplished by classes that are decoupled from the SQL model classes.  All the model classes have a `render` method that calls the built-in default renderers, but this is completely optional, and you do not need to use it.  You can write your own rendering support if you are dissatisfied with the SQL produced by the default renderers.
 
-Writing a custom renderer is quite complex.  If you want to undertake that task, we suggest that you take the time to understand how the default renderers work first.  And feel free to ask questions about this topic on the MyBatis mailing list.
+Writing a custom renderer is quite complex.  If you want to undertake that task, we suggest that you take the time to understand how the default renderers work first.  Feel free to ask questions about this topic on the MyBatis mailing list.