Add documentation for JdbcAggregateTemplate.

Closes #1841
Original pull request #1854

Author: schauder

src/main/antora/modules/ROOT/pages/commons/criteria-methods.adoc

@@ -0,0 +1,19 @@
+=== Methods for the Criteria Class
+
+The `Criteria` class provides the following methods, all of which correspond to SQL operators:
+
+* `Criteria` *and* `(String column)`: Adds a chained `Criteria` with the specified `property` to the current `Criteria` and returns the newly created one.
+* `Criteria` *or* `(String column)`: Adds a chained `Criteria` with the specified `property` to the current `Criteria` and returns the newly created one.
+* `Criteria` *greaterThan* `(Object o)`: Creates a criterion by using the `>` operator.
+* `Criteria` *greaterThanOrEquals* `(Object o)`: Creates a criterion by using the `>=` operator.
+* `Criteria` *in* `(Object... o)`: Creates a criterion by using the `IN` operator for a varargs argument.
+* `Criteria` *in* `(Collection<?> collection)`: Creates a criterion by using the `IN` operator using a collection.
+* `Criteria` *is* `(Object o)`: Creates a criterion by using column matching (`property = value`).
+* `Criteria` *isNull* `()`: Creates a criterion by using the `IS NULL` operator.
+* `Criteria` *isNotNull* `()`: Creates a criterion by using the `IS NOT NULL` operator.
+* `Criteria` *lessThan* `(Object o)`: Creates a criterion by using the `<` operator.
+* `Criteria` *lessThanOrEquals* `(Object o)`: Creates a criterion by using the `<=` operator.
+* `Criteria` *like* `(Object o)`: Creates a criterion by using the `LIKE` operator without escape character processing.
+* `Criteria` *not* `(Object o)`: Creates a criterion by using the `!=` operator.
+* `Criteria` *notIn* `(Object... o)`: Creates a criterion by using the `NOT IN` operator for a varargs argument.
+* `Criteria` *notIn* `(Collection<?> collection)`: Creates a criterion by using the `NOT IN` operator using a collection.

src/main/antora/modules/ROOT/pages/jdbc/entity-persistence.adoc

@@ -53,6 +53,52 @@ NOTE: While Single Query Loading can be abbreviated as SQL, but we highly discou
 
 include::partial$id-generation.adoc[]
 
+[[jdbc.template]]
+== Template API
+
+As an alternative to repositories Spring Data JDBC offers the javadoc:org.springframework.data.jdbc.core.JdbcAggregateTemplate[] as a more direct means to load and persist entities in a relational database.
+To a large extent, repositories use `JdbcAggregateTemplate` to implement their features.
+
+This section highlights only the most interesting parts of the `JdbcAggregateTemplate`.
+For a more complete overview, see the JavaDoc of `JdbcAggregateTemplate`.
+
+=== Accessing the JdbcAggregateTemplate
+
+`JdbcAggregateTemplate` is intended to be used as a Spring bean.
+If you have set up your application to include Spring Data JDBC, you can configure a dependency on `JdbcAggregateTemplate` in any Spring bean, and the Spring Framework injects a properly configured instance.
+
+This includes fragments you use to implement custom methods for your Spring Data Repositories, letting you to use `JdbcAggregateTemplate` to customize and extend your repositories.
+
+=== Persisting
+
+`JdbcAggregateTemplate offers three types of methods for persisting entities: `save`, `insert`, and `update`.
+Each comes in two flavors:
+Operating on single aggregates, named exactly as mentioned above, and with an `All` suffix operation on an `Iterable`.
+
+`save` does the same as the method of same name in a repository.
+
+`insert` and `update` skip the test if the entity is new and assume a new or existing aggregate as indicated by their name.
+
+=== Querying
+
+`JdbcAggregateTemplate` offers a considerable array of methods for querying aggregates and about collections of aggregates.
+There is one type of method that requires special attention.
+That's the methods taking a `Query` as an argument.
+They allow the execution of programmatically constructed queries, as follows:
+
+[source,java]
+----
+template.findOne(query(where("name").is("Gandalf")), Person.class);
+----
+
+The javadoc:org.springframework.data.relational.core.query.Query[] returned by the `query` method defines the list of columns to select, a where clause (through a CriteriaDefinition), and specification of limit and offset clauses.
+For details of the `Query` class, see its JavaDoc.
+
+The javadoc:org.springframework.data.relational.core.query.Criteria[] class, of which `where` is a static member, provides implementations of org.springframework.data.relational.core.query.CriteriaDefinition[], which represent the where-clause of the query.
+
+[[jdbc.criteria]]
+include::../commons/criteria-methods.adoc[]
+
 [[jdbc.entity-persistence.optimistic-locking]]
 == Optimistic Locking
 

src/main/antora/modules/ROOT/pages/r2dbc/entity-persistence.adoc

@@ -103,26 +103,7 @@ The fluent API style let you chain together multiple methods while having easy-t
 To improve readability, you can use static imports that let you avoid using the 'new' keyword for creating `Criteria` instances.
 
 [[r2dbc.datbaseclient.fluent-api.criteria]]
-=== Methods for the Criteria Class
-
-The `Criteria` class provides the following methods, all of which correspond to SQL operators:
-
-* `Criteria` *and* `(String column)`: Adds a chained `Criteria` with the specified `property` to the current `Criteria` and returns the newly created one.
-* `Criteria` *or* `(String column)`: Adds a chained `Criteria` with the specified `property` to the current `Criteria` and returns the newly created one.
-* `Criteria` *greaterThan* `(Object o)`: Creates a criterion by using the `>` operator.
-* `Criteria` *greaterThanOrEquals* `(Object o)`: Creates a criterion by using the `>=` operator.
-* `Criteria` *in* `(Object... o)`: Creates a criterion by using the `IN` operator for a varargs argument.
-* `Criteria` *in* `(Collection<?> collection)`: Creates a criterion by using the `IN` operator using a collection.
-* `Criteria` *is* `(Object o)`: Creates a criterion by using column matching (`property = value`).
-* `Criteria` *isNull* `()`: Creates a criterion by using the `IS NULL` operator.
-* `Criteria` *isNotNull* `()`: Creates a criterion by using the `IS NOT NULL` operator.
-* `Criteria` *lessThan* `(Object o)`: Creates a criterion by using the `<` operator.
-* `Criteria` *lessThanOrEquals* `(Object o)`: Creates a criterion by using the `<=` operator.
-* `Criteria` *like* `(Object o)`: Creates a criterion by using the `LIKE` operator without escape character processing.
-* `Criteria` *not* `(Object o)`: Creates a criterion by using the `!=` operator.
-* `Criteria` *notIn* `(Object... o)`: Creates a criterion by using the `NOT IN` operator for a varargs argument.
-* `Criteria` *notIn* `(Collection<?> collection)`: Creates a criterion by using the `NOT IN` operator using a collection.
-
+include::../commons/criteria-methods.adoc[]
 You can use `Criteria` with `SELECT`, `UPDATE`, and `DELETE` queries.
 
 [[r2dbc.entityoperations.fluent-api.insert]]