diff --git a/pom.xml b/pom.xml index 62715933..9ff59187 100644 --- a/pom.xml +++ b/pom.xml @@ -35,6 +35,7 @@ 1.0.0.M6 1.0.0.M6 1.0.0.M6 + 1.0.1 1.10.1 @@ -343,6 +344,25 @@ org.asciidoctor asciidoctor-maven-plugin + + ${project.root}/src/main/asciidoc + index.adoc + book + + ${project.version} + ${project.name} + ${project.version} + ${aspectj} + ${querydsl} + ${spring} + ${r2dbc-spi.version} + ${reactive-streams.version} + ${releasetrain} + true + 3 + true + + diff --git a/src/main/asciidoc/index.adoc b/src/main/asciidoc/index.adoc index aa60b705..f9ad3d6c 100644 --- a/src/main/asciidoc/index.adoc +++ b/src/main/asciidoc/index.adoc @@ -12,8 +12,6 @@ :imagesdir: images ifdef::backend-epub3[:front-cover-image: image:epub-cover.png[Front Cover,1050,1600]] :spring-data-commons-docs: ../../../../spring-data-commons/src/main/asciidoc -:rr2dbcVersion: 1.0.0.M6 -:reactiveStreamsVersion: 1.0.1 :reactiveStreamsJavadoc: http://www.reactive-streams.org/reactive-streams-{reactiveStreamsVersion}-javadoc (C) 2018 The original authors. diff --git a/src/main/asciidoc/preface.adoc b/src/main/asciidoc/preface.adoc index 95a956d5..78a28fbd 100644 --- a/src/main/asciidoc/preface.adoc +++ b/src/main/asciidoc/preface.adoc @@ -50,13 +50,13 @@ While the open source ecosystem hosts various non-blocking relational database d The term, reactive refers to programming models that are built around reacting to change, availability, and processability — network components reacting to I/O events, UI controllers reacting to mouse events, resources being made available and others. In that sense, non-blocking is reactive, because, instead of being blocked, we are now in the mode of reacting to notifications as operations complete or data becomes available. -There is also another important mechanism that we on the Spring team associate with reactive and that is non-blocking back pressure. +There is also another important mechanism that we on the Spring team associated with reactive and that is non-blocking back pressure. In synchronous, imperative code, blocking calls serve as a natural form of back pressure that forces the caller to wait. -In non-blocking code, it becomes important to control the rate of events so that a fast producer does not overwhelm its destination. +In non-blocking code, it becomes essential to control the rate of events so that a fast producer does not overwhelm its destination. -Reactive Streams is a https://github.com/reactive-streams/reactive-streams-jvm/blob/v{reactiveStreamsVersion}/README.md#specification[small spec] (also https://docs.oracle.com/javase/9/docs/api/java/util/concurrent/Flow.html[adopted] in Java 9) that defines the interaction between asynchronous components with back pressure. -For example a data repository (acting as {reactiveStreamsJavadoc}/org/reactivestreams/Publisher.html[`Publisher`]) can produce data that an HTTP server (acting as {reactiveStreamsJavadoc}/org/reactivestreams/Subscriber.html`[`Subscriber`]) can then write to the response. -The main purpose of Reactive Streams is to let the subscriber to control how quickly or how slowly the publisher produces data. +https://github.com/reactive-streams/reactive-streams-jvm/blob/v{reactiveStreamsVersion}/README.md#specification[Reactive Streams is a small spec] (also https://docs.oracle.com/javase/9/docs/api/java/util/concurrent/Flow.html[adopted in Java 9]) that defines the interaction between asynchronous components with back pressure. +For example, a data repository (acting as {reactiveStreamsJavadoc}/org/reactivestreams/Publisher.html[`Publisher`]) can produce data that an HTTP server (acting as {reactiveStreamsJavadoc}/org/reactivestreams/Subscriber.html`[`Subscriber`]) can then write to the response. +The main purpose of Reactive Streams is to let the subscriber control how quickly or how slowly the publisher produces data. [[get-started:first-steps:reactive-api]] == Reactive API @@ -81,8 +81,8 @@ Whenever feasible, Spring Data adapts transparently to the use of RxJava or anot The Spring Data R2DBC 1.x binaries require: * JDK level 8.0 and above -* http://spring.io/docs[Spring Framework] {springVersion} and above -* R2DBC {r2dbcVersion} and above +* https://spring.io/docs[Spring Framework] {springVersion} and above +* https://r2dbc.io[R2DBC] {r2dbcVersion} and above [[get-started:help]] == Additional Help Resources @@ -101,12 +101,15 @@ Professional Support :: Professional, from-the-source support, with guaranteed r [[get-started:up-to-date]] == Following Development -For information on the Spring Data R2DBC source code repository, nightly builds, and snapshot artifacts, see the Spring Data R2DBC http://projects.spring.io/spring-data-r2dbc/[homepage]. -You can help make Spring Data best serve the needs of the Spring community by interacting with developers through the Community on http://stackoverflow.com/questions/tagged/spring-data[Stack Overflow]. -To follow developer activity, look for the mailing list information on the Spring Data R2DBC https://projects.spring.io/spring-data-r2dbc/[homepage]. -If you encounter a bug or want to suggest an improvement, please create a ticket on the Spring Data R2DBC https://github.com/spring-projects/spring-data-r2dbc/issues[issue tracker]. -To stay up to date with the latest news and announcements in the Spring eco system, subscribe to the Spring Community http://spring.io[Portal]. -You can also follow the Spring http://spring.io/blog[blog] or the Spring Data project team on Twitter (http://twitter.com/SpringData[SpringData]). +* For information on the Spring Data R2DBC source code repository, nightly builds, and snapshot artifacts, see the Spring Data R2DBC http://projects.spring.io/spring-data-r2dbc/[homepage]. + +* You can help make Spring Data best serve the needs of the Spring community by interacting with developers through the Community on http://stackoverflow.com/questions/tagged/spring-data[Stack Overflow]. + +* If you encounter a bug or want to suggest an improvement, please create a ticket on the Spring Data R2DBC https://github.com/spring-projects/spring-data-r2dbc/issues[issue tracker]. + +* To stay up to date with the latest news and announcements in the Spring ecosystem, subscribe to the Spring Community http://spring.io[Portal]. + +* You can also follow the Spring http://spring.io/blog[blog] or the Spring Data project team on Twitter (http://twitter.com/SpringData[SpringData]). == Project Metadata diff --git a/src/main/asciidoc/reference/mapping.adoc b/src/main/asciidoc/reference/mapping.adoc index 6b10dcaf..138ac9a4 100644 --- a/src/main/asciidoc/reference/mapping.adoc +++ b/src/main/asciidoc/reference/mapping.adoc @@ -72,7 +72,7 @@ The `MappingR2dbcConverter` can use metadata to drive the mapping of objects to * `@PersistenceConstructor`: Marks a given constructor - even a package protected one - to use when instantiating the object from the database. Constructor arguments are mapped by name to the key values in the retrieved row. * `@Column`: Applied at the field level and described the name of the column as it will be represented in the row thus allowing the name to be different than the fieldname of the class. -The mapping metadata infrastructure is defined in a separate spring-data-commons project that is technology agnostic. Specific subclasses are using in the R2DBC support to support annotation based metadata. Other strategies are also possible to put in place if there is demand. +The mapping metadata infrastructure is defined in the separate spring-data-commons project that is technology agnostic. Specific subclasses are using in the R2DBC support to support annotation based metadata. Other strategies are also possible to put in place if there is demand. [[mapping-custom-object-construction]] @@ -81,7 +81,7 @@ The mapping metadata infrastructure is defined in a separate spring-data-commons The mapping subsystem allows the customization of the object construction by annotating a constructor with the `@PersistenceConstructor` annotation. The values to be used for the constructor parameters are resolved in the following way: * If a parameter is annotated with the `@Value` annotation, the given expression is evaluated and the result is used as the parameter value. -* If the Java type has a property whose name matches the given field of the input row, then it's property information is used to select the appropriate constructor parameter to pass the input field value to. This works only if the parameter name information is present in the java `.class` files which can be achieved by compiling the source with debug information or using the new `-parameters` command-line switch for javac in Java 8. +* If the Java type has a property whose name matches the given field of the input row, then it's property information is used to select the appropriate constructor parameter to pass the input field value to. This works only if the parameter name information is present in the java `.class` files which can be achieved by compiling the source with debug information or using the `-parameters` command-line switch for javac in Java 8. * Otherwise a `MappingException` will be thrown indicating that the given constructor parameter could not be bound. [source,java] diff --git a/src/main/asciidoc/reference/r2dbc-repositories.adoc b/src/main/asciidoc/reference/r2dbc-repositories.adoc index 42aaa712..7a46cf07 100644 --- a/src/main/asciidoc/reference/r2dbc-repositories.adoc +++ b/src/main/asciidoc/reference/r2dbc-repositories.adoc @@ -77,7 +77,7 @@ public class PersonRepositoryTests { @Autowired PersonRepository repository; @Test - public void readsallEntitiesCorrectly() { + public void readsAllEntitiesCorrectly() { repository.findAll() .as(StepVerifier::create) @@ -119,3 +119,5 @@ The annotated query uses native bind markers, which are Postgres bind markers in ==== NOTE: R2DBC repositories do not support query derivation. + +NOTE: R2DBC repositories require native parameter bind markers that are bound by index. diff --git a/src/main/asciidoc/reference/r2dbc.adoc b/src/main/asciidoc/reference/r2dbc.adoc index 09aa6bfd..b5d47cea 100644 --- a/src/main/asciidoc/reference/r2dbc.adoc +++ b/src/main/asciidoc/reference/r2dbc.adoc @@ -18,7 +18,7 @@ For most tasks, you should use `DatabaseClient` or the Repository support, which An easy way to bootstrap setting up a working environment is to create a Spring-based project through https://start.spring.io[start.spring.io]. -.Add the following to the pom.xml files `dependencies` element: +. Add the following to the pom.xml files `dependencies` element: + [source,xml,subs="+attributes"] ---- @@ -35,7 +35,7 @@ An easy way to bootstrap setting up a working environment is to create a Spring- io.r2dbc - … + r2dbc-h2 {r2dbcVersion} @@ -127,16 +127,16 @@ public class R2dbcApp { public static void main(String[] args) throws Exception { ConnectionFactory connectionFactory = new H2ConnectionFactory(H2ConnectionConfiguration.builder() - .url("mem:test;DB_CLOSE_DELAY=10") - .build()); + .url("mem:test;DB_CLOSE_DELAY=10") + .build()); DatabaseClient client = DatabaseClient.create(connectionFactory); client.execute() .sql("CREATE TABLE person" + - " (id VARCHAR(255) PRIMARY KEY," + - " name VARCHAR(255)," + - " age INT)") + "(id VARCHAR(255) PRIMARY KEY," + + "name VARCHAR(255)," + + "age INT)") .fetch() .rowsUpdated() .as(StepVerifier::create) @@ -162,7 +162,7 @@ public class R2dbcApp { } ---- -When you run the main program, the preceding examples produce the following output: +When you run the main program, the preceding examples produce output similar to the following: [source] ---- @@ -364,7 +364,7 @@ NOTE: `execute().sql(…)` accepts either the SQL query string or a query `Suppl === Running Queries SQL queries can return values or the number of affected rows. -`DatabaseClient` can return the number of updated rows or the rows themself, depending on the issued query. +`DatabaseClient` can return the number of updated rows or the rows themselves, depending on the issued query. The following example shows an `UPDATE` statement that returns the number of updated rows: @@ -409,7 +409,7 @@ Flux all = client.execute() [[r2dbc.datbaseclient.mapping]] === Mapping Results -You can customize result extraction beyong `Map` and POJO result extraction by providing an extractor `BiFunction`. +You can customize result extraction beyond `Map` and POJO result extraction by providing an extractor `BiFunction`. The extractor function interacts directly with R2DBC's `Row` and `RowMetadata` objects and can return arbitrary values (singular values, collections/maps, objects). The following example extracts the `id` column and emits its value: @@ -418,8 +418,7 @@ The following example extracts the `id` column and emits its value: ---- Flux names= client.execute() .sql("SELECT name FROM person") - .fetch() - .extract((row, rowMetadata) -> row.get("id", String.class)) + .map((row, rowMetadata) -> row.get("id", String.class)) .all(); ---- @@ -435,11 +434,11 @@ You must wrap any `null` values in an object (e.g. `Optional` for singular value [[r2dbc.datbaseclient.binding]] === Binding Values to Queries -A typical application requires parametrized SQL statements to select or update rows according to some input. +A typical application requires parameterized SQL statements to select or update rows according to some input. These are typically `SELECT` statements constrained by a `WHERE` clause or `INSERT`/`UPDATE` statements accepting input parameters. -Parametrized statements bear the risk of SQL injection if parameters are not escaped properly. +Parameterized statements bear the risk of SQL injection if parameters are not escaped properly. `DatabaseClient` leverages R2DBC's Bind API to eliminate the risk of SQL injection for query parameters. -You can provide a parametrized SQL statement with the `sql(…)` operator and bind parameters to the actual `Statement`. +You can provide a parameterized SQL statement with the `sql(…)` operator and bind parameters to the actual `Statement`. Your R2DBC driver then executes the statement using prepared statements and parameter substitution. Parameter binding supports various binding strategies: @@ -458,8 +457,8 @@ db.execute() .bind(2, 34); ---- -NOTE: If you are familiar with JDBC, then you're also familiar with `?` (questionmark) bind markers. -JDBC drivers translate questionmark bindmarkers to database-native markers as part of statement execution. +NOTE: If you are familiar with JDBC, then you're also familiar with `?` (question mark) bind markers. +JDBC drivers translate question mark bind markers to database-native markers as part of statement execution. Make sure to use the appropriate bind markers that are supported by your database as R2DBC requires database-native parameter bind markers. [[r2dbc.datbaseclient.transactions]]