Documentation for General Insert

Author: jeffgbutler

CHANGELOG.md

@@ -2,6 +2,14 @@
 
 This log will detail notable changes to MyBatis Dynamic SQL. Full details are available on the GitHub milestone pages.
 
+## Release 1.1.5 - Unreleased
+
+GitHub milestone: [https://github.com/mybatis/mybatis-dynamic-sql/issues?q=milestone%3A1.1.5+](https://github.com/mybatis/mybatis-dynamic-sql/issues?q=milestone%3A1.1.5+)
+
+### 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))
+
 ## Release 1.1.4 - November 23, 2019
 
 GitHub milestone: [https://github.com/mybatis/mybatis-dynamic-sql/issues?q=milestone%3A1.1.4+](https://github.com/mybatis/mybatis-dynamic-sql/issues?q=milestone%3A1.1.4+)

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

@@ -59,35 +59,35 @@ public SetClauseFinisher(SqlColumn<T> column) {
             this.column = column;
         }
 
-        public GeneralInsertDSL equalToNull() {
+        public GeneralInsertDSL toNull() {
             insertMappings.add(NullMapping.of(column));
             return GeneralInsertDSL.this;
         }
 
-        public GeneralInsertDSL equalToConstant(String constant) {
+        public GeneralInsertDSL toConstant(String constant) {
             insertMappings.add(ConstantMapping.of(column, constant));
             return GeneralInsertDSL.this;
         }
 
-        public GeneralInsertDSL equalToStringConstant(String constant) {
+        public GeneralInsertDSL toStringConstant(String constant) {
             insertMappings.add(StringConstantMapping.of(column, constant));
             return GeneralInsertDSL.this;
         }
 
-        public GeneralInsertDSL equalTo(T value) {
-            return equalTo(() -> value);
+        public GeneralInsertDSL toValue(T value) {
+            return toValue(() -> value);
         }
 
-        public GeneralInsertDSL equalTo(Supplier<T> valueSupplier) {
+        public GeneralInsertDSL toValue(Supplier<T> valueSupplier) {
             insertMappings.add(ValueMapping.of(column, valueSupplier));
             return GeneralInsertDSL.this;
         }
 
-        public GeneralInsertDSL equalToWhenPresent(T value) {
-            return equalToWhenPresent(() -> value);
+        public GeneralInsertDSL toValueWhenPresent(T value) {
+            return toValueWhenPresent(() -> value);
         }
 
-        public GeneralInsertDSL equalToWhenPresent(Supplier<T> valueSupplier) {
+        public GeneralInsertDSL toValueWhenPresent(Supplier<T> valueSupplier) {
             if (valueSupplier.get() != null) {
                 insertMappings.add(ValueMapping.of(column, valueSupplier));
             }

src/site/markdown/docs/insert.md

@@ -4,7 +4,8 @@ The library will generate a variety of INSERT statements:
 1. An insert for a single record
 1. An insert for multiple records with a single statement
 1. An insert for multiple records with a JDBC batch
-2. An insert with a select statement 
+1. A general insert statement
+1. An insert with a select statement 
 
 ## Single Record Insert
 A single record insert is a statement that inserts a single record into a table.  This statement is configured differently than other statements in the library so that MyBatis' support for generated keys will work properly.  To use the statement, you must first create an object that will map to the database row, then map object attributes to fields in the database.  For example:
@@ -213,6 +214,66 @@ It is important to open a MyBatis session by setting the executor type to BATCH.
 
 Notice that the same mapper method that is used to insert a single record is now executed multiple times.  The `map` methods are the same with the exception that the `toPropertyWhenPresent` mapping is not supported for batch inserts. 
 
+## General Insert Statement
+A general insert is used to build arbitrary insert statements. The general insert does not require a separate record object o hold values for the statement - any value can be passed into the statement. This version of the insert is not convienient for retriving generated keys with MyBatis - for that use case we recommend the "single record insert". However the general insert is perfectly acceptible for Spring JDBC template or MyBatis inserts that do not return generated keys. For example
+
+```java
+    GeneralInsertStatementProvider insertStatement = insertInto(animalData)
+            .set(id).toValue(101)
+            .set(animalName).toStringConstant("Fred")
+            .set(brainWeight).toConstant("2.2")
+            .set(bodyWeight).toValue(4.5)
+            .build()
+            .render(RenderingStrategies.MYBATIS3);
+```
+
+Notice the `set` method.  It is used to set the value for a database column.  There are several different possibilities:
+
+1. `set(column).toNull()` will insert a null into a column
+2. `set(column).toConstant(constant_value)` will insert a constant into a column.  The constant_value will be written into the generated insert statement exactly as entered
+3. `set(column).toStringConstant(constant_value)` will insert a constant into a column.  The constant_value will be written into the generated insert statement surrounded by single quote marks (as an SQL String)
+4. `set(column).toValue(value)` will insert a value into a column.  The value of the property will be bound to the SQL statement as a prepared statement parameter
+5. `set(column).toValueWhenPresent(property, Supplier<?> valueSupplier)` will insert a value into a column if the value is non-null.  The value of the property will be bound to the SQL statement as a prepared statement parameter.
+
+### Annotated Mapper for General Insert Statements
+The GeneralInsertStatementProvider object can be used as a parameter to a MyBatis mapper method directly.  If you
+are using an annotated mapper, the insert method should look like this:
+
+```java
+import org.apache.ibatis.annotations.InsertProvider;
+import org.mybatis.dynamic.sql.insert.render.GeneralInsertStatementProvider;
+import org.mybatis.dynamic.sql.util.SqlProviderAdapter;
+
+...
+    @InsertProvider(type=SqlProviderAdapter.class, method="generalInsert")
+    int generalInsert(GeneralInsertStatementProvider insertStatement);
+...
+
+```
+
+### XML Mapper for General Insert Statements
+We do not recommend using an XML mapper for insert statements, but if you want to do so the GeneralInsertStatementProvider object can be used as a parameter to a MyBatis mapper method directly.
+
+If you are using an XML mapper, the insert method should look like this in the Java interface:
+  
+```java
+import org.mybatis.dynamic.sql.insert.render.GeneralInsertStatementProvider;
+
+...
+    int generalInsert(GeneralInsertStatementProvider insertStatement);
+...
+
+```
+
+The XML element should look like this:
+
+```xml
+  <insert id="generalInsert">
+    ${insertStatement}
+  </insert>
+```
+
+
 ## Insert with Select
 An insert select is an SQL insert statement the inserts the results of a select.  For example:
 

src/site/markdown/docs/kotlinMyBatis3.md

@@ -152,14 +152,17 @@ val rows = mapper.delete { allRows() }
 
 Insert method support enables the removal of some of the boilerplate code from insert methods in a mapper interfaces.
 
-To use this support, we envision creating several methods - two standard mapper methods, and other extension methods. The standard mapper methods are standard MyBatis Dynamic SQL methods that will execute a delete:
+To use this support, we envision creating several methods - both standard mapper methods, and other extension methods. The standard mapper methods are standard MyBatis Dynamic SQL methods that will execute an insert:
 
 ```kotlin
 @Mapper
 interface PersonMapper {
     @InsertProvider(type = SqlProviderAdapter::class, method = "insert")
     fun insert(insertStatement: InsertStatementProvider<PersonRecord>): Int
 
+    @InsertProvider(type = SqlProviderAdapter::class, method = "generalInsert")
+    fun generalInsert(insertStatement: GeneralInsertStatementProvider): Int
+
     @InsertProvider(type = SqlProviderAdapter::class, method = "insertMultiple")
     fun insertMultiple(insertStatement: MultiRowInsertStatementProvider<PersonRecord>): Int
 }
@@ -179,6 +182,9 @@ fun PersonMapper.insert(record: PersonRecord) =
         map(addressId).toProperty("addressId")
     }
 
+fun PersonMapper.insert(completer: GeneralInsertCompleter) =
+    insertInto(this::generalInsert, Person, completer)
+
 fun PersonMapper.insertMultiple(vararg records: PersonRecord) =
     insertMultiple(records.toList())
 
@@ -205,7 +211,7 @@ fun PersonMapper.insertSelective(record: PersonRecord) =
     }
 ```
 
-Note these methods use Kotlin utility methods named `insert` and `insertMultiple`. Both methods accept a function with a receiver that will allow column mappings. The methods will build and execute insert statements.= with the supplied column mappings.
+Note these methods use Kotlin utility methods named `insert`, `insertInto`, and `insertMultiple`. Those methods accept a function with a receiver that will allow column mappings. The methods will build and execute insert statements with the supplied column mappings.
 
 Clients use these methods as follows:
 
@@ -214,6 +220,17 @@ Clients use these methods as follows:
 val record = PersonRecord(100, "Joe", LastName("Jones"), Date(), true, "Developer", 1)
 val rows = mapper.insert(record)
 
+// general insert...
+val rows = mapper.insert {
+    set(id).toValue(100)
+    set(firstName).toValue("Joe")
+    set(lastName).toValue(LastName("Jones"))
+    set(employed).toValue(true)
+    set(occupation).toValue("Developer")
+    set(addressId).toValue(1)
+    set(birthDate).toValue(Date())
+}
+
 // multiple insert...
 val record1 = PersonRecord(100, "Joe", LastName("Jones"), Date(), true, "Developer", 1)
 val record2 = PersonRecord(101, "Sarah", LastName("Smith"), Date(), true, "Architect", 2)

src/site/markdown/docs/kotlinSpring.md

@@ -101,9 +101,9 @@ There is also an extention method that can be used to count all rows in a table:
     }
 ```
 
-## Insert Method Support
+## Insert Record Method Support
 
-Insert method support enables the creation of arbitrary insert statements.
+Insert method support enables the creation of arbitrary insert statements given a class that matches a database row. If you do not with to create such a class, then see the general insert support following this section.
 
 The DSL for insert methods looks like this:
 
@@ -128,7 +128,7 @@ This code creates an `InsertStatementProvider` that can be executed with an exte
     val rows = template.insert(insertStatement)  // rows is an Int
 ```
 
-This is the two step execution process. This can be combined into a single step with code like the following:
+This is the two step execution process. These steps can be combined into a single step with code like the following:
 
 ```kotlin
     val record = PersonRecord(100, "Joe", "Jones", Date(), "Yes", "Developer", 1)
@@ -146,6 +146,49 @@ This is the two step execution process. This can be combined into a single step
 
 Note the use of the `toPropertyWhenPresent` mapping - this will only set the insert value if the value of the property is non null. Also note that you can use the mapping methods to map insert fields to nulls and constants if desired.
 
+## General Insert Method Support
+
+General insert method support enables the creation of arbitrary insert statements and does not require the creation of a class matching the database row.
+
+The DSL for general insert methods looks like this:
+
+```kotlin
+    val insertStatement = insertInto(Person) {  // insertStatement is a GeneralInsertStatementProvider
+        set(id).toValue(100)
+        set(firstName).toValue("Joe")
+        set(lastName).toValue("Jones")
+        set(birthDate).toValue(Date())
+        set(employed).toValue("Yes")
+        set(occupation).toValue("Developer")
+        set(addressId).toValue(1)
+    }
+```
+
+This code creates a `GeneralInsertStatementProvider` that can be executed with an extension method for `NamedParameterJdbcTemplate` like this:
+
+```kotlin
+    val template: NamedParameterJdbcTemplate = getTemplate() // not shown
+    val rows = template.insert(insertStatement)  // rows is an Int
+```
+
+This is the two step execution process. These steps can be combined into a single step with code like the following:
+
+```kotlin
+    val myOccupation = "Developer"
+
+    val rows = template.insertInto(Person) {
+        set(id).toValue(100)
+        set(firstName).toValue("Joe")
+        set(lastName).toValue("Jones")
+        set(birthDate).toValue(Date())
+        set(employed).toValue("Yes")
+        set(occupation).toValueWhenPresent(myOccupation)
+        set(addressId).toValue(1)
+    }
+```
+
+Note the use of the `toValueWhenPresent` mapping - this will only set the insert value if the value of the property is non null. Also note that you can use the mapping methods to map insert fields to nulls and constants if desired.
+
 ## Select Method Support
 
 Select method support enables the creation of methods that execute a query allowing a user to specify a where clause and/or an order by clause and/or pagination clauses at runtime, but abstracting away all other details.

src/site/markdown/docs/mybatis3.md

@@ -73,21 +73,28 @@ int rows = mapper.delete(DeleteDSLCompleter.allRows());
 
 The goal of insert method support is to remove some of the boilerplate code from insert methods in a mapper interfaces.
 
-To use this support, we envision creating several methods on a MyBatis mapper interface. The first two methods are the standard MyBatis Dynamic SQL method that will execute an insert:
+To use this support, we envision creating several methods on a MyBatis mapper interface. The first methods are the standard MyBatis methods that will execute an insert:
 
 ```java
 @InsertProvider(type=SqlProviderAdapter.class, method="insert")
 int insert(InsertStatementProvider<PersonRecord> insertStatement);
 
+@InsertProvider(type=SqlProviderAdapter.class, method="generalInsert")
+int generalInsert(GeneralInsertStatementProvider insertStatement);
+
 @InsertProvider(type=SqlProviderAdapter.class, method="insertMultiple")
 int insertMultiple(MultiRowInsertStatementProvider<PersonRecord> insertStatement);
 ```
 
-These two methods are standard methods for MyBatis Dynamic SQL. They execute a single row insert and a multiple row insert.
+These methods are standard methods for MyBatis Dynamic SQL. They execute a single row insert, a general insert, and a multiple row insert.
 
 These methods can be used to implement simplified insert methods:
 
 ```java
+default int insert(UnaryOperator<GeneralInsertDSL> completer) {
+    return MyBatis3Utils.insert(this::generalInsert, person, completer);
+}
+
 default int insert(PersonRecord record) {
     return MyBatis3Utils.insert(this::insert, record, person, c -> 
         c.map(id).toProperty("id")
@@ -117,7 +124,7 @@ default int insertMultiple(Collection<PersonRecord> records) {
 }
 ```
 
-In the mapper, only the column mappings need to be specified and no other boilerplate code is needed.
+The first insert method is a general insert and can be used to create arbitrary inserts with different combinations of columns specified. The other methods have the insert statements mapped to a POJO "record" class that holds values for the insert statement.
 
 ## Select Method Support
 

src/site/markdown/docs/spring.md

@@ -23,7 +23,7 @@ MyBatis3 is a higher level abstraction over JDBC than Spring JDBC templates. Whi
 The Spring Named Parameter JDBC template expects an SQL statement with parameter markers in the Spring format, and a set of matched parameters.  MyBatis Dynamic SQL will generate both.  The parameters returned from the generated SQL statement can be wrapped in a Spring `MapSqlParameterSource`.  Spring also expects you to provide a row mapper for creating the returned objects.  The following code shows a complete example:
 
 ```java
-    NamedParameterJdbcTemplate template = getTemplate();
+    NamedParameterJdbcTemplate template = getTemplate();  // not shown
 
     SelectStatementProvider selectStatement = select(id, firstName, lastName, fullName)
             .from(generatedAlways)
@@ -47,11 +47,46 @@ The Spring Named Parameter JDBC template expects an SQL statement with parameter
             });
 ```
 
-## Executing Insert Statements
-Insert statements are a bit different - MyBatis Dynamic SQL generates a properly formatted SQL string for Spring, but instead of a map of parameters, the parameter mappings are created for the inserted record itself.  So the parameters for the Spring template are created by a `BeanPropertySqlParameterSource`.  Generated keys in Spring are supported with a `GeneratedKeyHolder`.  The following is a complete example:
+## Executing General Insert Statements
+General insert statements do not require a POJO object matching a table row. Following is a complete example:
 
 ```java
-    NamedParameterJdbcTemplate template = getTemplate();
+    NamedParameterJdbcTemplate template = getTemplate();  // not shown
+
+    GeneralInsertStatementProvider insertStatement = insertInto(generatedAlways)
+            .set(id).toValue(100)
+            .set(firstName).toValue("Bob")
+            .set(lastName).toValue("Jones")
+            .build()
+            .render(RenderingStrategies.SPRING_NAMED_PARAMETER);
+
+    int rows = template.update(insertStatement.getInsertStatement(), insertStatement.getParameters());
+```
+
+If you want to retrieve generated keys for a general insert statement the steps are similar except that you must wrap the parameters in a `MapSqlParameterSource` object and use a `GeneratedKeyHolder`. Following is a complete example of this usage:
+
+```java
+    NamedParameterJdbcTemplate template = getTemplate();  // not shown
+
+    GeneralInsertStatementProvider insertStatement = insertInto(generatedAlways)
+            .set(id).toValue(100)
+            .set(firstName).toValue("Bob")
+            .set(lastName).toValue("Jones")
+            .build()
+            .render(RenderingStrategies.SPRING_NAMED_PARAMETER);
+
+    MapSqlParameterSource parameterSource = new MapSqlParameterSource(insertStatement.getParameters());
+    KeyHolder keyHolder = new GeneratedKeyHolder();
+
+    int rows = template.update(insertStatement.getInsertStatement(), parameterSource, keyHolder);
+    String generatedKey = (String) keyHolder.getKeys().get("FULL_NAME");
+```
+
+## Executing Insert Record Statements
+Insert record statements are a bit different - MyBatis Dynamic SQL generates a properly formatted SQL string for Spring, but instead of a map of parameters, the parameter mappings are created for the inserted record itself.  So the parameters for the Spring template are created by a `BeanPropertySqlParameterSource`.  Generated keys in Spring are supported with a `GeneratedKeyHolder`.  The following is a complete example:
+
+```java
+    NamedParameterJdbcTemplate template = getTemplate();  // not shown
 
     GeneratedAlwaysRecord record = new GeneratedAlwaysRecord();
     record.setId(100);
@@ -77,7 +112,7 @@ Insert statements are a bit different - MyBatis Dynamic SQL generates a properly
 Batch insert support in Spring is a bit different than batch support in MyBatis3 and Spring does not support returning generated keys from a batch insert.  The following is a complete example of a batch insert (note the use of `SqlParameterSourceUtils` to create an array of parameter sources from an array of input records):
 
 ```java
-    NamedParameterJdbcTemplate template = getTemplate();
+    NamedParameterJdbcTemplate template = getTemplate();  // not shown
 
     List<GeneratedAlwaysRecord> records = new ArrayList<>();
     GeneratedAlwaysRecord record = new GeneratedAlwaysRecord();
@@ -109,11 +144,11 @@ Batch insert support in Spring is a bit different than batch support in MyBatis3
 Updates and deletes use the `MapSqlParameterSource` as with select statements, but use the `update` method in the template.  For example:
 
 ```java
-    NamedParameterJdbcTemplate template = getTemplate();
+    NamedParameterJdbcTemplate template = getTemplate();  // not shown
 
     UpdateStatementProvider updateStatement = update(generatedAlways)
             .set(firstName).equalToStringConstant("Rob")
-            .where(id,  isIn(1, 5, 22))
+            .where(id, isIn(1, 5, 22))
             .build()
             .render(RenderingStrategies.SPRING_NAMED_PARAMETER);