diff --git a/pom.xml b/pom.xml index f0b2a42b23..b5aa3018b6 100644 --- a/pom.xml +++ b/pom.xml @@ -5,7 +5,7 @@ org.springframework.data spring-data-relational-parent - 3.4.0-SNAPSHOT + 3.4.0-1841-doc-template-SNAPSHOT pom Spring Data Relational Parent diff --git a/spring-data-jdbc-distribution/pom.xml b/spring-data-jdbc-distribution/pom.xml index 84eeb178e0..387ecf2771 100644 --- a/spring-data-jdbc-distribution/pom.xml +++ b/spring-data-jdbc-distribution/pom.xml @@ -14,7 +14,7 @@ org.springframework.data spring-data-relational-parent - 3.4.0-SNAPSHOT + 3.4.0-1841-doc-template-SNAPSHOT ../pom.xml diff --git a/spring-data-jdbc/pom.xml b/spring-data-jdbc/pom.xml index 266af71b96..62abb80d07 100644 --- a/spring-data-jdbc/pom.xml +++ b/spring-data-jdbc/pom.xml @@ -6,7 +6,7 @@ 4.0.0 spring-data-jdbc - 3.4.0-SNAPSHOT + 3.4.0-1841-doc-template-SNAPSHOT Spring Data JDBC Spring Data module for JDBC repositories. @@ -15,7 +15,7 @@ org.springframework.data spring-data-relational-parent - 3.4.0-SNAPSHOT + 3.4.0-1841-doc-template-SNAPSHOT diff --git a/spring-data-r2dbc/pom.xml b/spring-data-r2dbc/pom.xml index 3168f9d4f6..26ae80a2c7 100644 --- a/spring-data-r2dbc/pom.xml +++ b/spring-data-r2dbc/pom.xml @@ -6,7 +6,7 @@ 4.0.0 spring-data-r2dbc - 3.4.0-SNAPSHOT + 3.4.0-1841-doc-template-SNAPSHOT Spring Data R2DBC Spring Data module for R2DBC @@ -15,7 +15,7 @@ org.springframework.data spring-data-relational-parent - 3.4.0-SNAPSHOT + 3.4.0-1841-doc-template-SNAPSHOT diff --git a/spring-data-relational/pom.xml b/spring-data-relational/pom.xml index 0287ece743..d5324aa1ea 100644 --- a/spring-data-relational/pom.xml +++ b/spring-data-relational/pom.xml @@ -6,7 +6,7 @@ 4.0.0 spring-data-relational - 3.4.0-SNAPSHOT + 3.4.0-1841-doc-template-SNAPSHOT Spring Data Relational Spring Data Relational support @@ -14,7 +14,7 @@ org.springframework.data spring-data-relational-parent - 3.4.0-SNAPSHOT + 3.4.0-1841-doc-template-SNAPSHOT diff --git a/src/main/antora/modules/ROOT/nav.adoc b/src/main/antora/modules/ROOT/nav.adoc index e02181cc55..d9b6057936 100644 --- a/src/main/antora/modules/ROOT/nav.adoc +++ b/src/main/antora/modules/ROOT/nav.adoc @@ -26,6 +26,7 @@ ** xref:jdbc/entity-persistence.adoc[] ** xref:jdbc/mapping.adoc[] ** xref:jdbc/query-methods.adoc[] +** xref:jdbc/template.adoc[] ** xref:jdbc/mybatis.adoc[] ** xref:jdbc/events.adoc[] ** xref:jdbc/auditing.adoc[] diff --git a/src/main/antora/modules/ROOT/pages/commons/criteria-methods.adoc b/src/main/antora/modules/ROOT/pages/commons/criteria-methods.adoc new file mode 100644 index 0000000000..8e965b2f86 --- /dev/null +++ b/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. diff --git a/src/main/antora/modules/ROOT/pages/jdbc/template.adoc b/src/main/antora/modules/ROOT/pages/jdbc/template.adoc new file mode 100644 index 0000000000..08038399ff --- /dev/null +++ b/src/main/antora/modules/ROOT/pages/jdbc/template.adoc @@ -0,0 +1,48 @@ +[[jdbc.template]] += Template API + +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] +---- +CriteriaDefinition criteria = CriteriaDefinition.from(Criteria.where("name").is("Gandalf")); +Query query = Query.query(criteria); +Optional reloadedById = template.findOne(query, Person.class); +---- + +The javadoc:org.springframework.data.relational.core.query.Query[] 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 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[] + diff --git a/src/main/antora/modules/ROOT/pages/r2dbc/entity-persistence.adoc b/src/main/antora/modules/ROOT/pages/r2dbc/entity-persistence.adoc index 04315f659d..7fd7e0a5dd 100644 --- a/src/main/antora/modules/ROOT/pages/r2dbc/entity-persistence.adoc +++ b/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]]