Documentation for multiple row inserts

Author: jeffgbutler

src/site/markdown/docs/insert.md

@@ -2,8 +2,9 @@
 The library will generate a variety of INSERT statements:
 
 1. An insert for a single record
-2. An insert for a batch of records
-3. An insert with a select statement 
+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 
 
 ## 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:
@@ -92,6 +93,95 @@ MyBatis supports returning generated values from a single record insert, or a ba
 
 The important thing is that the `keyProperty` is set correctly.  It should always be in the form `record.<attribute>` where `<attribute>` is the attribute of the record class that should be updated with the generated value.
 
+## Multiple Row Insert Support
+A multiple row insert is a single insert statement that inserts multiple rows into a table. This can be a convenient way to insert a few rows into a table, but it has some limitations:
+
+1. Since it is a single SQL statement, you could generate quite a lot of prepared statement parameters. For example, suppose you wanted to insert 1000 records into a table, and each record had 5 fields. With a multiple row insert you would generate a SQL statement with 5000 parameters. There are limits to the number of parameters allowed in a JDBC prepared statement - and this kind of insert could easily exceed those limits. If you want to insert a large number of records, you should probably use a JDBC batch insert instead (see below)
+1. The performance of a giant insert statement may be less than you expect. If you have a large number of records to insert, it will almost always be more efficient to use a JDBC batch insert (see below). With a batch insert, the JDBC driver can do some optimization that is not possible with a single large statement
+1. Retrieving generated values with multiple row inserts can be a challenge. MyBatis currently has some limitations related to retrieving generated keys in multiple row inserts that require special considerations (see below)
+
+Nevertheless, there are use cases for a multiple row insert - especially when you just want to insert a few records in a table and don't need to retrieve generated keys. In those situations, a multiple row insert will be an easy solution.
+
+A multiple row insert statement looks like this:
+
+```java
+    try (SqlSession session = sqlSessionFactory.openSession()) {
+        GeneratedAlwaysAnnotatedMapper mapper = session.getMapper(GeneratedAlwaysAnnotatedMapper.class);
+        List<GeneratedAlwaysRecord> records = getRecordsToInsert(); // not shown
+            
+        MultiRowInsertStatementProvider<GeneratedAlwaysRecord> multiRowInsert = insertMultiple(records)
+                .into(generatedAlways)
+                .map(id).toProperty("id")
+                .map(firstName).toProperty("firstName")
+                .map(lastName).toProperty("lastName")
+                .build()
+                .render(RenderingStrategy.MYBATIS3);
+            
+        int rows = mapper.insertMultiple(multiRowInsert);
+    }
+```
+
+### Annotated Mapper for Multiple Row Insert Statements
+The MultiRowInsertStatementProvider 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.MultiRowInsertStatementProvider;
+import org.mybatis.dynamic.sql.util.SqlProviderAdapter;
+
+...
+    @InsertProvider(type=SqlProviderAdapter.class, method="insertMultiple")
+    int insertMultiple(MultiRowInsertStatementProvider<SimpleTableRecord> insertStatement);
+...
+
+```
+
+### XML Mapper for Multiple Row Insert Statements
+We do not recommend using an XML mapper for insert statements, but if you want to do so the MultiRowInsertStatementProvider 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.MultiInsertStatementProvider;
+
+...
+    int insertMultiple(MultiRowInsertStatementProvider<SimpleTableRecord> insertStatement);
+...
+
+```
+
+The XML element should look like this:
+
+```xml
+  <insert id="insertMultiple">
+    ${insertStatement}
+  </insert>
+```
+
+### Generated Values
+MyBatis supports returning generated values from a multiple row insert statement with some limitations. The main limitation is that MyBatis does not support nested lists in parameter objects. Unfortunately, the `MultiRowInsertStatementProvider` relies on a nested List. It is likely this limitation in MyBatis will be removed at some point in the future, so stay tuned.
+
+Nevertheless, you can configure a mapper that will work with the `MultiRowInsertStatementProvider` as created by this library. The main idea is to decompose the statement from the parameter map and send them as separate parameters to the MyBatis mapper. For example:
+
+```java
+...
+    @Insert({
+        "${insertStatement}"
+    })
+    @Options(useGeneratedKeys=true, keyProperty="records.fullName")
+    int insertMultipleWithGeneratedKeys(@Param("insertStatement") String statement, @Param("records") List<GeneratedAlwaysRecord> records);
+
+    default int insertMultipleWithGeneratedKeys(MultiRowInsertStatementProvider<GeneratedAlwaysRecord> multiInsert) {
+        return insertMultipleWithGeneratedKeys(multiInsert.getInsertStatement(), multiInsert.getRecords());
+    }
+...
+```
+
+The first method above shows the actual MyBatis mapper method. Note the use of the `@Options` annotation to specify that we expect generated values. Further note that the `keyProperty` is set to `records.fullName` - in this case, `fullName` is a property of the objects in the `records` List.
+
+The second method above decomposes the `MultiRowInsertStatementProvider` and calls the first method.
+
 ## Batch Insert Support
 A batch insert is a collection of statements that can be used to execute a JDBC batch.  A batch is the preferred method of doing bulk inserts with JDBC.  The basic idea is that you configure the connection for a batch insert, then execute the same statement multiple times, with different values for each inserted record.  MyBatis has a nice abstraction of JDBC batches that works well with statements generated from this library.  A batch insert looks like this: