Add a selectOne helper

Author: jeffgbutler

src/main/java/org/mybatis/dynamic/sql/util/mybatis3/MyBatis3SelectHelper.java renamed to src/main/java/org/mybatis/dynamic/sql/util/mybatis3/MyBatis3SelectListHelper.java

@@ -73,7 +73,7 @@
  * @author Jeff Butler
  */
 @FunctionalInterface
-public interface MyBatis3SelectHelper<T> extends
+public interface MyBatis3SelectListHelper<T> extends
         Function<QueryExpressionDSL<MyBatis3SelectModelAdapter<List<T>>>,
         Buildable<MyBatis3SelectModelAdapter<List<T>>>> {
 
@@ -84,7 +84,7 @@ public interface MyBatis3SelectHelper<T> extends
      * 
      * @return the helper that will select every row in a table
      */
-    static <T> MyBatis3SelectHelper<T> allRows() {
+    static <T> MyBatis3SelectListHelper<T> allRows() {
         return h -> h;
     }
 
@@ -96,7 +96,7 @@ static <T> MyBatis3SelectHelper<T> allRows() {
      * 
      * @return the helper that will select every row in a table in the specified order
      */
-    static <T> MyBatis3SelectHelper<T> allRowsOrderdBy(SortSpecification...columns) {
+    static <T> MyBatis3SelectListHelper<T> allRowsOrderdBy(SortSpecification...columns) {
         return h -> h.orderBy(columns);
     }
 }

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

@@ -0,0 +1,58 @@
+/**
+ *    Copyright 2016-2019 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.util.mybatis3;
+
+import java.util.Optional;
+import java.util.function.Function;
+
+import org.mybatis.dynamic.sql.select.MyBatis3SelectModelAdapter;
+import org.mybatis.dynamic.sql.select.QueryExpressionDSL;
+import org.mybatis.dynamic.sql.util.Buildable;
+
+/**
+ * Represents a function that can be used to create a general select one method in the style
+ * of MyBatis Generator. When using this function, you can create a method that does not require a user to
+ * call the build().execute() methods - making client code look a bit cleaner.
+ * 
+ * <p>For example, you can create mapper interface methods like this:
+ * 
+ * <pre>
+ * &#64;SelectProvider(type=SqlProviderAdapter.class, method="select")
+ * &#64;ResultMap("SimpleTableResult")
+ * Optional&lt;SimpleTableRecord&gt; selectOne(SelectStatementProvider selectStatement);
+ *
+ * default Optional&lt;SimpleTableRecord&gt; selectOne(MyBatis3SelectOneHelper&lt;SimpleTableRecord&gt; helper) {
+ *     return helper.apply(SelectDSL.selectWithMapper(this::selectOne, simpleTable.allColumns())
+ *             .from(simpleTable))
+ *             .build()
+ *             .execute();
+ * }
+ * </pre>
+ * 
+ * <p>And then call the simplified default method like this:
+ * 
+ * <pre>
+ * Optional&lt;SimpleRecord&gt; record = mapper.selectOne(q -&gt;
+ *     q.where(id, isEqualTo(1)));
+ * </pre>
+ *  
+ * @author Jeff Butler
+ */
+@FunctionalInterface
+public interface MyBatis3SelectOneHelper<T> extends
+        Function<QueryExpressionDSL<MyBatis3SelectModelAdapter<Optional<T>>>,
+        Buildable<MyBatis3SelectModelAdapter<Optional<T>>>> {
+}

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

@@ -24,7 +24,7 @@
 import org.mybatis.dynamic.sql.update.render.UpdateStatementProvider;
 
 /**
- * Utility functions for building MyBatis3 mappers
+ * Utility functions for building MyBatis3 mappers.
  * 
  * @author Jeff Butler
  *
@@ -33,7 +33,7 @@ public class MyBatis3Utils {
     private MyBatis3Utils() {}
 
     /**
-     * Initiates a delete statement using the non-boxing adapter
+     * Initiates a delete statement using the non-boxing adapter.
      * 
      * @param mapper a MyBatis3 mapper delete method
      * @param table the table to delete from
@@ -45,7 +45,7 @@ public static DeleteDSL<MyBatis3DeleteModelToIntAdapter> deleteFrom(ToIntFunctio
     }
 
     /**
-     * Initiates an update statement using the non-boxing adapter
+     * Initiates an update statement using the non-boxing adapter.
      * 
      * @param mapper a MyBatis3 mapper update method
      * @param table the table to update

src/site/markdown/docs/mybatis3.md

@@ -99,31 +99,41 @@ Optional<SimpleTableRecord> selectOne(SelectStatementProvider selectStatement);
 
 These two methods are standard methods for MyBatis Dynamic SQL. They execute a select and return either a list of records, or a single record.
 
-The `selectOne` method can be used to implement a `selectByPrimaryKey` method:
+The `selectOne` method can be used to implement a generalized select one method:
+
+```java
+default Optional<SimpleTableRecord> selectOne(MyBatis3SelectOneHelper<SimpleTableRecord> helper) {
+    return helper.apply(SelectDSL.selectWithMapper(this::selectOne, id.as("A_ID"), firstName, lastName, birthDate, employed, occupation)
+            .from(simpleTable))
+            .build()
+            .execute();
+}
+```
+
+This method shows the use of `MyBatis3SelectOneHelper` which is a specialization of a `java.util.Function` that will allow a user to supply a where clause.
+
+The general `selectOne` method can be used to implement a `selectByPrimaryKey` method:
 
 ```java
 default Optional<SimpleTableRecord> selectByPrimaryKey(Integer id_) {
-    return SelectDSL.selectWithMapper(this::selectOne, id.as("A_ID"), firstName, lastName, birthDate,
-            employed, occupation)
-        .from(simpleTable)
-        .where(id, isEqualTo(id_))
-        .build()
-        .execute();
+    return selectOne(h ->
+        h.where(id, isEqualTo(id_))
+    );
 }
 ```
 
 The `selectMany` method can be used to implement generalized select methods where a user can specify a where clause and/or an order by clause. Typically we recommend two of these methods - for select, and select distinct: 
 
 ```java
-default List<SimpleTableRecord> select(MyBatis3SelectHelper<SimpleTableRecord> helper) {
+default List<SimpleTableRecord> select(MyBatis3SelectListHelper<SimpleTableRecord> helper) {
     return helper.apply(SelectDSL.selectWithMapper(this::selectMany, id.as("A_ID"), firstName, lastName, birthDate,
                 employed, occupation)
             .from(simpleTable))
             .build()
             .execute();
 }
 
-default List<SimpleTableRecord> selectDistinct(MyBatis3SelectHelper<SimpleTableRecord> helper) {
+default List<SimpleTableRecord> selectDistinct(MyBatis3SelectListHelper<SimpleTableRecord> helper) {
     return helper.apply(SelectDSL.selectDistinctWithMapper(this::selectMany, id.as("A_ID"), firstName, lastName,
                 birthDate, employed, occupation)
             .from(simpleTable))
@@ -133,7 +143,7 @@ default List<SimpleTableRecord> selectDistinct(MyBatis3SelectHelper<SimpleTableR
 ```
 
 
-These methods show the use of `MyBatis3SelectHelper` which is a specialization of a `java.util.Function` that will allow a user to supply a where clause and/or an order by clause.
+These methods show the use of `MyBatis3SelectListHelper` which is a specialization of a `java.util.Function` that will allow a user to supply a where clause and/or an order by clause.
 
 Clients can use the methods as follows:
 
@@ -147,14 +157,14 @@ There are utility methods that will select all rows in a table:
 
 ```java
 List<SimpleTableRecord> rows =
-    mapper.selectByExample(MyBatis3SelectHelper.allRows());
+    mapper.selectByExample(MyBatis3SelectListHelper.allRows());
 ```
 
 The following query will select all rows in a specified order:
 
 ```java
 List<SimpleTableRecord> rows =
-    mapper.selectByExample(MyBatis3SelectHelper.allRowsOrderedBy(lastName, firstName));
+    mapper.selectByExample(MyBatis3SelectListHelper.allRowsOrderedBy(lastName, firstName));
 ```
 
 ## Update Method Support

src/test/java/examples/simple/newstyle/SimpleTableMapperNewStyle.java

@@ -42,7 +42,8 @@
 import org.mybatis.dynamic.sql.util.SqlProviderAdapter;
 import org.mybatis.dynamic.sql.util.mybatis3.MyBatis3CountHelper;
 import org.mybatis.dynamic.sql.util.mybatis3.MyBatis3DeleteHelper;
-import org.mybatis.dynamic.sql.util.mybatis3.MyBatis3SelectHelper;
+import org.mybatis.dynamic.sql.util.mybatis3.MyBatis3SelectListHelper;
+import org.mybatis.dynamic.sql.util.mybatis3.MyBatis3SelectOneHelper;
 import org.mybatis.dynamic.sql.util.mybatis3.MyBatis3UpdateHelper;
 import org.mybatis.dynamic.sql.util.mybatis3.MyBatis3UpdateModelToIntAdapter;
 import org.mybatis.dynamic.sql.util.mybatis3.MyBatis3Utils;
@@ -148,26 +149,31 @@ default int insertSelective(SimpleTableRecord record) {
                 .render(RenderingStrategy.MYBATIS3));
     }
 
-    default List<SimpleTableRecord> select(MyBatis3SelectHelper<SimpleTableRecord> helper) {
+    default Optional<SimpleTableRecord> selectOne(MyBatis3SelectOneHelper<SimpleTableRecord> helper) {
+        return helper.apply(SelectDSL.selectWithMapper(this::selectOne, id.as("A_ID"), firstName, lastName, birthDate, employed, occupation)
+                .from(simpleTable))
+                .build()
+                .execute();
+    }
+    
+    default List<SimpleTableRecord> select(MyBatis3SelectListHelper<SimpleTableRecord> helper) {
         return helper.apply(SelectDSL.selectWithMapper(this::selectMany, id.as("A_ID"), firstName, lastName, birthDate, employed, occupation)
                 .from(simpleTable))
                 .build()
                 .execute();
     }
 
-    default List<SimpleTableRecord> selectDistinct(MyBatis3SelectHelper<SimpleTableRecord> helper) {
+    default List<SimpleTableRecord> selectDistinct(MyBatis3SelectListHelper<SimpleTableRecord> helper) {
         return helper.apply(SelectDSL.selectDistinctWithMapper(this::selectMany, id.as("A_ID"), firstName, lastName, birthDate, employed, occupation)
                 .from(simpleTable))
                 .build()
                 .execute();
     }
 
     default Optional<SimpleTableRecord> selectByPrimaryKey(Integer id_) {
-        return SelectDSL.selectWithMapper(this::selectOne, id.as("A_ID"), firstName, lastName, birthDate, employed, occupation)
-            .from(simpleTable)
-            .where(id, isEqualTo(id_))
-            .build()
-            .execute();
+        return selectOne(h -> 
+            h.where(id, isEqualTo(id_))
+        );
     }
 
     default int update(MyBatis3UpdateHelper helper) {

src/test/java/examples/simple/newstyle/SimpleTableMapperNewStyleTest.java

@@ -41,7 +41,7 @@
 import org.junit.jupiter.api.Test;
 import org.mybatis.dynamic.sql.util.mybatis3.MyBatis3CountHelper;
 import org.mybatis.dynamic.sql.util.mybatis3.MyBatis3DeleteHelper;
-import org.mybatis.dynamic.sql.util.mybatis3.MyBatis3SelectHelper;
+import org.mybatis.dynamic.sql.util.mybatis3.MyBatis3SelectListHelper;
 
 import examples.simple.LastName;
 import examples.simple.SimpleTableRecord;
@@ -88,7 +88,7 @@ public void testSelectAll() {
         try (SqlSession session = sqlSessionFactory.openSession()) {
             SimpleTableMapperNewStyle mapper = session.getMapper(SimpleTableMapperNewStyle.class);
 
-            List<SimpleTableRecord> rows = mapper.select(MyBatis3SelectHelper.allRows());
+            List<SimpleTableRecord> rows = mapper.select(MyBatis3SelectListHelper.allRows());
 
             assertThat(rows.size()).isEqualTo(6);
             assertThat(rows.get(0).getId()).isEqualTo(1);
@@ -102,7 +102,7 @@ public void testSelectAllOrdered() {
             SimpleTableMapperNewStyle mapper = session.getMapper(SimpleTableMapperNewStyle.class);
 
             List<SimpleTableRecord> rows = mapper
-                    .select(MyBatis3SelectHelper.allRowsOrderdBy(lastName.descending(), firstName.descending()));
+                    .select(MyBatis3SelectListHelper.allRowsOrderdBy(lastName.descending(), firstName.descending()));
 
             assertThat(rows.size()).isEqualTo(6);
             assertThat(rows.get(0).getId()).isEqualTo(5);