Add R2DBC Getting Started Guide

README.adoc

@@ -1,18 +1,14 @@
 :spring_version: current
-:spring_boot_version: 2.1.6.RELEASE
-:Controller: http://docs.spring.io/spring/docs/{spring_version}/javadoc-api/org/springframework/stereotype/Controller.html
-:DispatcherServlet: http://docs.spring.io/spring/docs/{spring_version}/javadoc-api/org/springframework/web/servlet/DispatcherServlet.html
-:SpringApplication: http://docs.spring.io/spring-boot/docs/{spring_boot_version}/api/org/springframework/boot/SpringApplication.html
-:ResponseBody: http://docs.spring.io/spring/docs/{spring_version}/javadoc-api/org/springframework/web/bind/annotation/ResponseBody.html
+:spring_boot_version: 2.2.2.RELEASE
 :toc:
 :icons: font
 :source-highlighter: prettify
-:project_id: draft-gs-template
-This guide walks you through the process of creating a Spring application.
+:project_id: gs-accessing-data-r2dbc
+This guide walks you through the process of building an application that uses Spring Data R2DBC to store and retrieve data in a relational database using reactive database drivers.
 
 == What you'll build
 
-You'll build a Spring application.
+You will build an application that stores `Customer` POJOs (Plain Old Java Objects) in a memory-based database.
 
 
 == What you'll need
@@ -23,60 +19,179 @@ include::https://raw.githubusercontent.com/spring-guides/getting-started-macros/
 include::https://raw.githubusercontent.com/spring-guides/getting-started-macros/master/how_to_complete_this_guide.adoc[]
 
 
-include::https://raw.githubusercontent.com/spring-guides/getting-started-macros/master/hide-show-gradle.adoc[]
+[[scratch]]
+== Starting with Spring Initializr
 
-include::https://raw.githubusercontent.com/spring-guides/getting-started-macros/master/hide-show-maven.adoc[]
+For all Spring applications, you should start with the https://start.spring.io[Spring
+Initializr]. The Initializr offers a fast way to pull in all the dependencies you need for
+an application and does a lot of the set up for you. This example needs the R2DBC and H2
+dependencies. The following image shows the Initializr set up for this sample project:
 
-include::https://raw.githubusercontent.com/spring-guides/getting-started-macros/master/hide-show-sts.adoc[]
+image::images/initializr.png[]
 
+NOTE: The preceding image shows the Initializr with Maven chosen as the build tool. You
+can also use Gradle. It also shows values of `com.example` and `accesing-data-r2dbc` as the
+Group and Artifact, respectively. You will use those values throughout the rest of this sample.
 
+The following listing shows the `pom.xml` file created when you choose Maven:
+
+====
+[src,xml]
+----
+include::complete/pom.xml[]
+----
+====
+
+The following listing shows the `build.gradle` file created when you choose Gradle:
+
+====
+[src,gradle]
+----
+include::complete/build.gradle[]
+----
+====
 
 [[initial]]
-== Create a resource controller
+== Define a Schema
+
+In this example, you store `Customer` objects, each annotated as a R2DBC entity. The
+following listing shows the SQL schema class (in `src/main/resources/schema.sql`):
+
+====
+[source,sql,indent=0]
+----
+include::complete/src/main/resources/schema.sql[]
+----
+====
+
+Here you have a `customer` table with three columns: `id`, `first_name`, and `last_name`.
+The `id` column is auto-incremented, the other columns follow the default snake case naming scheme.
+Spring Boot's auto-configuration picks up the `schema.sql` file during application startup to initialize the database schema.
+
+[[entity]]
+== Define a Simple Entity
+
+In this example, you store `Customer` objects, each annotated as a R2DBC entity. The
+following listing shows the Customer class (in
+	`src/main/java/com/example/accessingdatar2dbc/Customer.java`):
+
+====
+[source,java,indent=0]
+----
+include::complete/src/main/java/com/example/accessingdatar2dbc/Customer.java[]
+----
+====
 
-Create a new controller for your Spring application:
+Here you have a `Customer` class with three attributes: `id`, `firstName`, and `lastName`.
+The `Customer` class is minimally annotated. The `id` property is annotated with `@Id` so that Spring Data R2DBC can identify the primary key.
+By default, primary keys are assumed to be generated by the database on `INSERT`.
 
-`src/main/java/hello/GreetingController.java`
+The other two properties, `firstName` and `lastName`, are left unannotated. It is assumed
+that they are mapped to columns that share the same names as the properties themselves.
+
+The convenient `toString()` method print outs the customer's properties.
+
+
+== Create Simple Queries
+
+Spring Data R2DBC focuses on using R2DBC as underlying technology to store data in a relational database.
+Its most compelling feature is the ability to create repository implementations, at runtime, from a repository interface.
+
+To see how this works, create a repository interface that works with `Customer` entities
+as the following listing (in `src/main/java/com/example/accessingdatar2dbc/CustomerRepository.java`) shows:
+
+====
 [source,java]
 ----
-include::complete/src/main/java/hello/GreetingController.java[]
+include::complete/src/main/java/com/example/accessingdatar2dbc/CustomerRepository.java[]
 ----
+====
 
-NOTE: The above example does not specify `GET` vs. `PUT`, `POST`, and so forth, because `@RequestMapping` maps all HTTP operations by default. Use `@RequestMapping(method=GET)` to narrow this mapping.
+`CustomerRepository` extends the `ReactiveCrudRepository` interface. The type of entity and ID  that it works with, `Customer` and `Long`, are specified in the generic parameters on `ReactiveCrudRepository`.
+By extending `ReactiveCrudRepository`, `CustomerRepository` inherits several methods for working with `Customer` persistence, including methods for saving, deleting, and finding `Customer` entities using reactive types.
 
+Spring Data R2DBC also lets you define other query methods by annotating these with `@Query`.
+For example, `CustomerRepository` includes the `findByLastName()` method.
 
-== Make the application executable
+In a typical Java application, you might expect to write a class that implements `CustomerRepository`.
+However, that is what makes Spring Data R2DBC so powerful: You need not write an implementation of the repository interface.
+Spring Data R2DBC creates an implementation when you run the application.
 
-Although it is possible to package this service as a traditional link:/understanding/WAR[WAR] file for deployment to an external application server, the simpler approach demonstrated below creates a standalone application. You package everything in a single, executable JAR file, driven by a good old Java `main()` method. Along the way, you use Spring's support for embedding the link:/understanding/Tomcat[Tomcat] servlet container as the HTTP runtime, instead of deploying to an external instance.
+Now you can wire up this example and see what it looks like!
 
+== Create an Application Class
 
-`src/main/java/hello/Application.java`
+Spring Initializr creates a simple class for the application. The following listing shows
+the class that Initializr created for this example (in
+`src/main/java/com/example/accessingdatar2dbc/AccessingDataR2dbcApplication.java`):
+
+====
 [source,java]
 ----
-include::complete/src/main/java/hello/Application.java[]
+include::initial/src/main/java/com/example/accessingdatar2dbc/AccessingDataR2dbcApplication.java[]
 ----
+====
 
-include::https://raw.githubusercontent.com/spring-guides/getting-started-macros/master/spring-boot-application.adoc[]
+include::https://raw.githubusercontent.com/spring-guides/getting-started-macros/master/spring-boot-application-new-path.adoc[]
 
-include::https://raw.githubusercontent.com/spring-guides/getting-started-macros/master/build_an_executable_jar_subhead.adoc[]
+Now you need to modify the simple class that the Initializr created for you.
+To get output (to the console, in this example), you need to set up a logger.
+Then you need to set up some data and use it to generate output.
+The following listing shows the finished `AccessingDataR2dbcApplication` class (in `src/main/java/com/example/accessingdatar2dbc/AccessingDataR2dbcApplication.java`):
 
-include::https://raw.githubusercontent.com/spring-guides/getting-started-macros/master/build_an_executable_jar_with_both.adoc[]
+====
+[source,java]
+----
+include::complete/src/main/java/com/example/accessingdatar2dbc/AccessingDataR2dbcApplication.java[]
+----
+====
+
+The `AccessingDataR2dbcApplication` class includes a `main()` method that puts the `CustomerRepository` through a few tests.
+First, it fetches the `CustomerRepository` from the Spring application context.
+Then it saves a handful of `Customer` objects, demonstrating the `save()` method and setting up some data to use.
+Next, it calls `findAll()` to fetch all `Customer` objects from the database.
+Then it calls `findById()` to fetch a single `Customer` by its ID.
+Finally, it calls `findByLastName()` to find all customers whose last name is "Bauer".
 
+R2DBC is a reactive programming technology.
+At the same time we're using it in a synchronized, imperative flow and that is why we're required to synchronize each call with a variant of the `block(…)` method.
+In a typical reactive application, the resulting `Mono` or `Flux` would represent a pipeline of operators that is handed back to a web controller or event processor that subscribes to the reactive sequence without blocking the calling thread.
 
-Logging output is displayed. The service should be up and running within a few seconds.
+NOTE: By default, Spring Boot enables R2DBC repository support and looks in the package (and its subpackages) where `@SpringBootApplication` is located.
+If your configuration has R2DBC repository interface definitions located in a package that is not visible, you can point out alternate packages by using `@EnableR2dbcRepositories` and its type-safe `basePackageClasses=MyRepository.class` parameter.
 
+include::https://raw.githubusercontent.com/spring-guides/getting-started-macros/master/build_an_executable_jar_mainhead.adoc[]
 
-== Test the application
+include::https://raw.githubusercontent.com/spring-guides/getting-started-macros/master/build_an_executable_jar_with_both.adoc[]
 
-Now that the application is running, you can test it.
+When you run your application, you should see output similar to the following:
 
+====
+----
+== Customers found with findAll():
+Customer[id=1, firstName='Jack', lastName='Bauer']
+Customer[id=2, firstName='Chloe', lastName='O'Brian']
+Customer[id=3, firstName='Kim', lastName='Bauer']
+Customer[id=4, firstName='David', lastName='Palmer']
+Customer[id=5, firstName='Michelle', lastName='Dessler']
+
+== Customer found with findOne(1L):
+Customer[id=1, firstName='Jack', lastName='Bauer']
+
+== Customer found with findByLastName('Bauer'):
+Customer[id=1, firstName='Jack', lastName='Bauer']
+Customer[id=3, firstName='Kim', lastName='Bauer']
+----
+====
 
 == Summary
 
-Congratulations! You've just developed a Spring application! 
+Congratulations! You have written a simple application that uses Spring Data R2DBC to save objects to and fetch them from a database, all without writing a concrete repository implementation.
 
+== See Also
 
+The following guides may also be helpful:
 
+* https://spring.io/guides/gs/gs-spring-data-reactive-redis[Accessing Data Reactively with Redis]
 
 include::https://raw.githubusercontent.com/spring-guides/getting-started-macros/master/footer.adoc[]
-

complete/build.gradle

@@ -1,32 +1,35 @@
-buildscript {
-    repositories {
-        mavenCentral()
-    }
-    dependencies {
-        classpath("org.springframework.boot:spring-boot-gradle-plugin:2.1.6.RELEASE")
-    }
+plugins {
+	id 'org.springframework.boot' version '2.2.2.RELEASE'
+	id 'io.spring.dependency-management' version '1.0.8.RELEASE'
+	id 'java'
 }
 
-apply plugin: 'java'
-apply plugin: 'eclipse'
-apply plugin: 'idea'
-apply plugin: 'org.springframework.boot'
-apply plugin: 'io.spring.dependency-management'
-
-bootJar {
-    baseName = 'draft-gs-template'
-    version =  '0.1.0'
-}
+group = 'com.example'
+version = '0.0.1-SNAPSHOT'
+sourceCompatibility = '1.8'
 
 repositories {
-    mavenCentral()
+	mavenCentral()
+	maven { url 'https://repo.spring.io/milestone' }
 }
 
-sourceCompatibility = 1.8
-targetCompatibility = 1.8
-
 dependencies {
-    compile("org.springframework.boot:spring-boot-starter-web")
-    testCompile("org.springframework.boot:spring-boot-starter-test")
+	implementation 'org.springframework.boot.experimental:spring-boot-starter-data-r2dbc'
+	runtimeOnly 'com.h2database:h2'
+	runtimeOnly 'io.r2dbc:r2dbc-h2'
+	testImplementation('org.springframework.boot:spring-boot-starter-test') {
+		exclude group: 'org.junit.vintage', module: 'junit-vintage-engine'
+	}
+	testImplementation 'org.springframework.boot.experimental:spring-boot-test-autoconfigure-r2dbc'
+	testImplementation 'io.projectreactor:reactor-test'
 }
 
+dependencyManagement {
+	imports {
+		mavenBom 'org.springframework.boot.experimental:spring-boot-bom-r2dbc:0.1.0.M3'
+	}
+}
+
+test {
+	useJUnitPlatform()
+}

complete/gradle/wrapper/gradle-wrapper.properties

@@ -3,4 +3,4 @@ distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-4.6-bin.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-4.10.3-bin.zip

complete/pom.xml

@@ -4,27 +4,60 @@
     <modelVersion>4.0.0</modelVersion>
 
     <groupId>org.springframework</groupId>
-    <artifactId>draft-gs-template</artifactId>
+    <artifactId>accessing-data-r2dbc</artifactId>
     <version>0.1.0</version>
 
     <parent>
         <groupId>org.springframework.boot</groupId>
         <artifactId>spring-boot-starter-parent</artifactId>
-        <version>2.1.6.RELEASE</version>
+        <version>2.2.2.RELEASE</version>
     </parent>
 
     <dependencies>
         <dependency>
-            <groupId>org.springframework.boot</groupId>
-            <artifactId>spring-boot-starter-web</artifactId>
+            <groupId>org.springframework.boot.experimental</groupId>
+            <artifactId>spring-boot-starter-data-r2dbc</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>io.r2dbc</groupId>
+            <artifactId>r2dbc-h2</artifactId>
+            <scope>runtime</scope>
         </dependency>
         <dependency>
             <groupId>org.springframework.boot</groupId>
             <artifactId>spring-boot-starter-test</artifactId>
             <scope>test</scope>
+            <exclusions>
+                <exclusion>
+                    <groupId>org.junit.vintage</groupId>
+                    <artifactId>junit-vintage-engine</artifactId>
+                </exclusion>
+            </exclusions>
+        </dependency>
+        <dependency>
+            <groupId>org.springframework.boot.experimental</groupId>
+            <artifactId>spring-boot-test-autoconfigure-r2dbc</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>io.projectreactor</groupId>
+            <artifactId>reactor-test</artifactId>
+            <scope>test</scope>
         </dependency>
     </dependencies>
 
+    <dependencyManagement>
+        <dependencies>
+            <dependency>
+                <groupId>org.springframework.boot.experimental</groupId>
+                <artifactId>spring-boot-bom-r2dbc</artifactId>
+                <version>0.1.0.M3</version>
+                <type>pom</type>
+                <scope>import</scope>
+            </dependency>
+        </dependencies>
+    </dependencyManagement>
+
     <properties>
         <java.version>1.8</java.version>
     </properties>
@@ -38,4 +71,12 @@
         </plugins>
     </build>
 
+    <repositories>
+        <repository>
+            <id>spring-milestones</id>
+            <name>Spring Milestones</name>
+            <url>https://repo.spring.io/milestone</url>
+        </repository>
+    </repositories>
+
 </project>