JavaDoc for new *ByExample helper interfaces

Author: jeffgbutler

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

@@ -21,6 +21,40 @@
 import org.mybatis.dynamic.sql.select.QueryExpressionDSL;
 import org.mybatis.dynamic.sql.util.Buildable;
 
+/**
+ * Represents a function that can be used to create a "CountByExample" 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")
+ * long count(SelectStatementProvider selectStatement);
+ *   
+ * default long countByExample(MyBatis3CountByExampleHelper helper) {
+ *     return helper.apply(SelectDSL.selectWithMapper(this::count, SqlBuilder.count())
+ *             .from(simpleTable))
+ *             .build()
+ *             .execute();
+ * }
+ * </pre>
+ * 
+ * <p>And then call the simplified default method like this:
+ * 
+ * <pre>
+ * long rows = mapper.countByExample(q -&gt;
+ *         q.where(occupation, isNull()));
+ * </pre>
+ * 
+ * <p>You can also do a "count all" with the following code:
+ * 
+ * <pre>
+ * long rows = mapper.countByExample(q -&gt; q);
+ * </pre>
+ *  
+ * @author Jeff Butler
+ */
 @FunctionalInterface
 public interface MyBatis3CountByExampleHelper extends
         Function<QueryExpressionDSL<MyBatis3SelectModelAdapter<Long>>, Buildable<MyBatis3SelectModelAdapter<Long>>> {

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

@@ -25,9 +25,34 @@
  * Represents a function that can be used to create a "DeleteByExample" 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;DeleteProvider(type=SqlProviderAdapter.class, method="delete")
+ * int delete(DeleteStatementProvider deleteStatement);
+ *   
+ * default int deleteByExample(MyBatis3DeleteByExampleHelper helper) {
+ *     return helper.apply(DeleteDSL.deleteFromWithMapper(this::delete, simpleTable))
+ *           .build()
+ *           .execute();
+ * }
+ * </pre>
+ * 
+ * <p>And then call the simplified default method like this:
+ * 
+ * <pre>
+ * int rows = mapper.deleteByExample(q -&gt;
+ *           q.where(occupation, isNull()));
+ * </pre>
  *  
+ * <p>You can also do a "delete all" with the following code:
+ * 
+ * <pre>
+ * int rows = mapper.deleteByExample(q -&gt; q);
+ * </pre>
+ * 
  * @author Jeff Butler
- *
  */
 @FunctionalInterface
 public interface MyBatis3DeleteByExampleHelper extends

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

@@ -22,6 +22,49 @@
 import org.mybatis.dynamic.sql.select.QueryExpressionDSL;
 import org.mybatis.dynamic.sql.util.Buildable;
 
+/**
+ * Represents a function that can be used to create a "SelectByExample" 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;Results(id="SimpleTableResult", value= {
+ *         &#64;Result(column="id", property="id", jdbcType=JdbcType.INTEGER, id=true),
+ *         &#64;Result(column="first_name", property="firstName", jdbcType=JdbcType.VARCHAR),
+ *         &#64;Result(column="last_name", property="lastName", jdbcType=JdbcType.VARCHAR),
+ *         &#64;Result(column="birth_date", property="birthDate", jdbcType=JdbcType.DATE),
+ *         &#64;Result(column="employed", property="employed", jdbcType=JdbcType.VARCHAR),
+ *         &#64;Result(column="occupation", property="occupation", jdbcType=JdbcType.VARCHAR)
+ * })
+ * List&lt;SimpleTableRecord&gt; selectMany(SelectStatementProvider selectStatement);
+ *
+ * default List&lt;SimpleTableRecord&gt; selectByExample(MyBatis3SelectByExampleHelper&lt;SimpleTableRecord&gt; helper) {
+ *     return helper.apply(SelectDSL.selectWithMapper(this::selectMany, simpleTable.allColumns())
+ *             .from(simpleTable))
+ *             .build()
+ *             .execute();
+ * }
+ * </pre>
+ * 
+ * <p>And then call the simplified default method like this:
+ * 
+ * <pre>
+ * List&lt;SimpleTableRecord&gt; rows = mapper.selectByExample(q -&gt;
+ *     q.where(id, isEqualTo(1))
+ *     .or(occupation, isNull()));
+ * </pre>
+ *  
+ * <p>You can also do a "select all" with the following code:
+ * 
+ * <pre>
+ * List&lt;SimpleTableRecord&gt; rows = mapper.selectByExample(q -&gt; q);
+ * </pre>
+ * 
+ * @author Jeff Butler
+ */
 @FunctionalInterface
 public interface MyBatis3SelectByExampleHelper<T> extends
         Function<QueryExpressionDSL<MyBatis3SelectModelAdapter<List<T>>>,

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

@@ -21,6 +21,46 @@
 import org.mybatis.dynamic.sql.update.UpdateDSL;
 import org.mybatis.dynamic.sql.util.Buildable;
 
+/**
+ * Represents a function that can be used to create an "UpdateByExample" 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;UpdateProvider(type=SqlProviderAdapter.class, method="update")
+ * int update(UpdateStatementProvider updateStatement);
+ *   
+ * default int updateByExampleSelective(SimpleTableRecord record, MyBatis3UpdateByExampleHelper helper) {
+ *     return helper.apply(UpdateDSL.updateWithMapper(this::update, simpleTable)
+ *             .set(id).equalToWhenPresent(record.getId())
+ *             .set(firstName).equalToWhenPresent(record::getFirstName)
+ *             .set(lastName).equalToWhenPresent(record::getLastName)
+ *             .set(birthDate).equalToWhenPresent(record::getBirthDate)
+ *             .set(employed).equalToWhenPresent(record::getEmployed)
+ *             .set(occupation).equalToWhenPresent(record::getOccupation))
+ *             .build()
+ *             .execute();
+ * }
+ * </pre>
+ * 
+ * <p>And then call the simplified default method like this:
+ * 
+ * <pre>
+ * int rows = mapper.updateByExampleSelective(record, q -&gt;
+ *                q.where(id, isEqualTo(100))
+ *                .and(firstName, isEqualTo("Joe")));
+ * </pre>
+ *  
+ * <p>You can also do an "update all" with the following code:
+ * 
+ * <pre>
+ * int rows = mapper.updateByExampleSelective(record, q -&gt; q);
+ * </pre>
+ * 
+ * @author Jeff Butler
+ */
 @FunctionalInterface
 public interface MyBatis3UpdateByExampleHelper extends
         Function<UpdateDSL<MyBatis3UpdateModelAdapter<Integer>>, Buildable<MyBatis3UpdateModelAdapter<Integer>>> {