Documentation

Author: jeffgbutler

CHANGELOG.md

@@ -13,6 +13,7 @@ GitHub milestone: [https://github.com/mybatis/mybatis-dynamic-sql/issues?q=miles
 ### Added
 
 - Added a callback capability to the "In" conditions that will be called before rendering when the conditions are empty. Also, removed the option that forced the library to render invalid SQL in that case. ([#241](https://github.com/mybatis/mybatis-dynamic-sql/pull/241))
+- Added a utility mapper for MyBatis that allows you to run any select query without having to predefine a result mapping.
 
 ## Release 1.2.0 - August 19, 2020
 

src/main/java/org/mybatis/dynamic/sql/util/mybatis3/GeneralMapper.java

@@ -30,17 +30,19 @@
  * This is a general purpose MyBatis mapper. It allows you to execute select statements without having to
  * write a custom {@link org.apache.ibatis.annotations.ResultMap} for each statement.
  *
- * <p>This mapper contains two types of methods:
+ * <p>This mapper contains three types of methods:
  * <ul>
- *     <li>selectOneMappedRow, selectOne, selectManyMappedRows, and selectMany can be used to process result sets with
- *     any number of columns. The row values are processed by MyBatis and returned in a Map. A function can
- *     be applied to the Map to create custom objects if desired</li>
- *     <li>The other methods are for result sets with a single column. There are functions for many different
- *     data types (Integer, Long, String, etc.) and functions that return a single value, and Optional value,
- *     or a List of values</li>
+ *   <li>The selectOneMappedRow and selectManyMappedRows methods allow you to use select statements with
+ *     any number of columns. MyBatis will process the rows and return a Map of values, or a List of Maps.</li>
+ *   <li>The selectOne and selectMany methods also allow you to use select statements with any number of columns.
+ *   These methods also allow you to specify a function that will transform a Map of row values into a specific
+ *   object.</li>
+ *   <li>The other methods are for result sets with a single column. There are functions for many
+ *   data types (Integer, Long, String, etc.) There are also functions that return a single value, and Optional value,
+ *   or a List of values.</li>
  * </ul>
  *
- * <p>This mapper can be injected as-is into a MyBatis configuration, or it can be extended with existing mappers.</p>
+ * <p>This mapper can be injected as-is into a MyBatis configuration, or it can be extended with existing mappers.
  *
  * @author Jeff Butler
  */

src/site/markdown/docs/mybatis3.md

@@ -5,6 +5,124 @@ The goal of this support is to reduce the amount of boilerplate code needed for
 
 With version 1.1.3, specialized interfaces and utilities were added that can further simplify client code. This support enables the creation of methods that have similar functionality to some of the methods generated in previous versions of MyBatis generator like countByExample, deleteByExample, and selectByExample. We no longer use the "by example" terms for these methods as this library has eliminated the Example class that was generated by prior versions of MyBatis Generator.
 
+## Dynamic Result Mapping Support
+MyBatis is very good at mapping result sets to objects - this is one of its primary differentiators. MyBatis also requires
+that you predefine the mappings for every possibility. This presents a challenge if you want very dynamic column lists
+in a query. This library provides a generalized MyBatis mapper that can assist with that problem.
+
+The general mapper is `org.mybatis.dynamic.sql.util.mybatis3.GeneralMapper`. This mapper can be injected into a MyBatis configuration
+as is, or it can be extended by an existing mapper. If you are using MyBatis Spring support and auto scanning for mappers,
+you can create an extension in your application's mapper package as follows:
+
+```java
+package foo.mapper;
+
+import org.apache.ibatis.annotations.Mapper;
+import org.mybatis.dynamic.sql.util.mybatis3.GeneralMapper;
+
+@Mapper
+public interface MyGeneralMapper extends GeneralMapper {
+}
+```
+
+The mapper contains three types of methods:
+ 
+1. The `selectOneMappedRow` and `selectManyMappedRows` methods allow you to use select statements with
+any number of columns. MyBatis will process the rows and return a Map of values, or a List of Maps.
+1. The `selectOne` and `selectMany` methods also allow you to use select statements with any number of columns. These methods
+also allow you to specify a function that will transform a Map of row values into a specific object.
+1. The other methods are for result sets with a single column. There are functions for many
+data types (Integer, Long, String, etc.) There are also functions that return a single value, and Optional value,
+or a List of values.
+
+An example of using the mapped row methods follows:
+
+```java
+package foo.service;
+import static org.mybatis.dynamic.sql.SqlBuilder.*;
+
+import java.util.List;
+import java.util.Map;
+import org.mybatis.dynamic.sql.render.RenderingStrategies;
+import org.mybatis.dynamic.sql.select.render.SelectStatementProvider;
+import org.mybatis.dynamic.sql.util.mybatis3.GeneralMapper;
+
+public class MyService {
+    public List<Map<String,Object>> generalSearch() {
+        GeneralMapper mapper = getGeneralMapper(); // not shown
+
+        SelectStatementProvider selectStatement = select(id, description)
+            .from(foo)
+            .where(description. isLike("%bar%"))
+            .build()
+            .render(RenderingStrategies.MYBATIS3);
+        return  mapper.selectManyMappedRows(selectStatement);
+    }
+}
+```
+
+As you can see, the method returns a List of Maps containing the row values. The Map key will be the column name as
+returned from the database (typically in upper case), and the column value as returned from the `ResultSet.getObject()`.
+See your JDBC driver's documentation for details about how SQL types are mapped to Java types to determine the data type
+for your specific database.
+
+This method works well, but usually it is better to marshal the result set into actual objects. This can be accomplished
+as follows:
+
+```java
+package foo.service;
+import static org.mybatis.dynamic.sql.SqlBuilder.*;
+
+import java.util.List;
+import org.mybatis.dynamic.sql.render.RenderingStrategies;
+import org.mybatis.dynamic.sql.select.render.SelectStatementProvider;
+import org.mybatis.dynamic.sql.util.mybatis3.GeneralMapper;
+
+public class MyService {
+    public List<TableCode> generalSearch() {
+        GeneralMapper mapper = getGeneralMapper(); // not shown
+
+        SelectStatementProvider selectStatement = select(id, description)
+            .from(foo)
+            .where(description. isLike("%bar%"))
+            .build()
+            .render(RenderingStrategies.MYBATIS3);
+        return  mapper.selectMany(selectStatement, m -> {
+            TableCode tc = new TableCode();
+            tc.setId((Integer) m.get("ID"));
+            tc.setDescription((String) m.get("DESCRIPTION"));
+            return tc;
+        });
+    }
+}
+```
+
+With this method you can centralize all the database specific operations in a single method.
+
+If you only have a single column in the result set, the general mapper provides methods to retrieve the value directly.
+For example:
+
+```java
+package foo.service;
+import static org.mybatis.dynamic.sql.SqlBuilder.*;
+
+import org.mybatis.dynamic.sql.render.RenderingStrategies;
+import org.mybatis.dynamic.sql.select.render.SelectStatementProvider;
+import org.mybatis.dynamic.sql.util.mybatis3.GeneralMapper;
+
+public class MyService {
+    public Long getCount() {
+        GeneralMapper mapper = getGeneralMapper(); // not shown
+
+        SelectStatementProvider selectStatement = countFrom(foo)
+            .where(description. isLike("%bar%"))
+            .build()
+            .render(RenderingStrategies.MYBATIS3);
+        return  mapper.selectOneLong(selectStatement);
+    }
+}
+```
+
 ## Count Method Support
 
 The goal of count method support is to enable the creation of methods that execute a count query allowing a user to specify a where clause at runtime, but abstracting away all other details.