Minor updates to the quickstart guide

Author: adutra

quickstart/README.adoc

@@ -58,7 +58,7 @@ We recommend that you follow the instructions in the next sections and create th
 by step. However, you can go right to the completed example.
 
 The solution is located in the
-link:https://github.com/datastax/cassandra-quarkus/tree/master/quickstart[quickstart directory] of
+link:https://github.com/datastax/cassandra-quarkus/tree/main/quickstart[quickstart directory] of
 the Cassandra Quarkus extension GitHub repository.
 
 == Creating a Blank Maven Project
@@ -95,7 +95,7 @@ public class Fruit {
 
 As stated above, we are using the DataStax Object Mapper. In other words, we are not going to write
 our CQL queries manually; instead, we will annotate our data model with a few annotations, and the
-mapper will generate proper CQL queries for us underneath.
+mapper will generate proper CQL queries underneath.
 
 This is why the `Fruit` class is annotated with `@Entity`: this annotation marks it as an _entity
 class_ that is mapped to a Cassandra table. Its instances are meant to be automatically persisted
@@ -143,11 +143,11 @@ public interface FruitMapper {
 ----
 
 The `@Mapper` annotation is yet another annotation recognized by the DataStax Object Mapper. A
-mapper is responsible for constructing instances of DAOs – in this case, out mapper is constructing
+mapper is responsible for constructing DAO instances – in this case, out mapper is constructing
 an instance of our only DAO, `FruitDao`.
 
-Think of the mapper interface as a factory for DAO beans: if you intend to construct and inject a
-specific DAO bean in your own code, then you first need to add a `@DaoFactory` method for it in a
+Think of the mapper interface as a factory for DAO beans. If you intend to construct and inject a
+specific DAO bean in your own code, then you first must add a `@DaoFactory` method for it in a
 `@Mapper` interface.
 
 TIP: `@DaoFactory` method names are irrelevant.
@@ -161,15 +161,15 @@ TIP: `@DaoFactory` method names are irrelevant.
 TIP: `Uni` is a type from the Mutiny library, which is the reactive programming library used by
 Quarkus. This will be explained in more detail in the "Reactive Programming" section below.
 
-== Generating the DAO and Mapper Implementations
+== Generating the DAO and mapper implementations
 
 As you probably guessed already, we are not going to implement the interfaces above. Instead, the
 Object Mapper will generate such implementations for us.
 
 The Object Mapper is composed of 2 pieces:
 
 1. A (compile-time) annotation processor that scans the classpath for classes annotated with
-`@Entity`, and generates code for them; and
+`@Mapper`, `@Dao` or `@Entity`, and generates code and CQL queries for them; and
 2. A runtime module that contains the logic to execute the generated queries.
 
 Therefore, enabling the Object Mapper requires two steps:
@@ -203,40 +203,33 @@ With Gradle, this is done by adding the following line to the `build.gradle` fil
 annotationProcessor "com.datastax.oss.quarkus:cassandra-quarkus-mapper-processor:${cassandra-quarkus.version}"
 ----
 
-IMPORTANT: make sure you are enabling the right annotation processor! The Cassandra Quarkus
-extension requires the `cassandra-quarkus-mapper-processor` annotation processor, and not the Java
-driver's `java-driver-mapper-processor`. The former has more capabilities than the latter, and is
-the only one suitable for use in a Quarkus application.
+IMPORTANT: Verify that you are enabling the right annotation processor! The Cassandra driver ships
+with its Object Mapper annotation processor, called `java-driver-mapper-processor`. But the
+Cassandra Quarkus extension also ships with its own annotation processor:
+`cassandra-quarkus-mapper-processor`, which has more capabilities than the driver's. This annotation
+processor is the only one suitable for use in a Quarkus application, so check that this is the one
+in use. Also, never use both annotation processors together.
 
 [start=2]
-1. Declare the `cassandra-quarkus-mapper-runtime` dependency in compile scope in the project's
-`pom.xml` file as follows:
+1. Declare the `java-driver-mapper-runtime` dependency in compile scope in the project's `pom.xml`
+file as follows:
 
 [source,xml]
 ----
 <dependency>
-  <groupId>com.datastax.oss.quarkus</groupId>
-  <artifactId>cassandra-quarkus-mapper-runtime</artifactId>
-  <version>${project.version}</version>
-  <scope>compile</scope>
+  <groupId>com.datastax.oss</groupId>
+  <artifactId>java-driver-mapper-runtime</artifactId>
 </dependency>
 ----
 
-With Gradle, this is done by adding the following line to the `build.gradle` file:
-
-[source,groovy]
-----
-compile "com.datastax.oss.quarkus:cassandra-quarkus-mapper-runtime:${cassandra-quarkus.version}"
-----
-
 IMPORTANT: Although this module is called "runtime", it must be declared in compile scope.
 
 If your project is correctly set up, you should now be able to compile it without errors, and you
 should see the generated code in the `target/generated-sources/annotations` directory (if you are
-using Maven). You don't need to get familiar with the generated code though, as it is mostly
+using Maven). It's not required to get familiar with the generated code though, as it is mostly
 internal machinery to interact with the database.
 
-== Creating a Service & JSON REST Endpoint
+== Creating a service & JSON REST endpoint
 
 Now let's create a `FruitService` that will be the business layer of our application and store/load
 the fruits from the Cassandra database.
@@ -333,19 +326,19 @@ public class FruitDto {
 }
 ----
 
-The translation to and from JSON is done automatically by the Quarkus RestEasy extension, which is
-included in this guide's pom.xml file. If you want to add it manually to your application, add the
-below snippet to your application's ppm.xml file:
+The translation to and from JSON is done automatically by the Quarkus RESTEasy Reactive extension,
+which is included in this guide's pom.xml file. If you want to add it manually to your application,
+add the below snippet to your application's ppm.xml file:
 
 [source,xml]
 ----
 <dependency>
   <groupId>io.quarkus</groupId>
-  <artifactId>quarkus-resteasy</artifactId>
+  <artifactId>quarkus-resteasy-reactive</artifactId>
 </dependency>
 <dependency>
   <groupId>io.quarkus</groupId>
-  <artifactId>quarkus-resteasy-jsonb</artifactId>
+  <artifactId>quarkus-resteasy-reactive-jackson</artifactId>
 </dependency>
 ----
 
@@ -620,20 +613,7 @@ NOTE: The `getAll()` method above returns `Multi`, and the `add()` method return
 are the same Mutiny types that we met before; they are automatically recognized by the Quarkus
 reactive REST API, so we don't need to convert them into JSON ourselves.
 
-To effectively integrate the reactive logic with the REST API, your application needs to declare a
-dependency to the Quarkus RestEasy Reactive extension:
-
-[source,xml]
-----
-<dependency>
-  <groupId>io.quarkus</groupId>
-  <artifactId>quarkus-resteasy-reactive</artifactId>
-</dependency>
-<dependency>
-  <groupId>io.quarkus</groupId>
-  <artifactId>quarkus-resteasy-reactive-jsonb</artifactId>
-</dependency>
-----
+RESTEasy Reactive natively supports the Mutiny reactive types e.g. `Uni` and `Multi`.
 
 This dependency is already included in this guide's pom.xml, but if you are starting a new project
 from scratch, make sure to include it.
@@ -727,12 +707,10 @@ framework you plan to use.
 
 === Enabling Metrics with Micrometer
 
-Micrometer is the recommended metrics framework in Quarkus applications since Quarkus 1.9.
+Micrometer is the recommended metrics framework in Quarkus applications.
 
 To enable Micrometer metrics in your application, you need to add the following to your pom.xml.
 
-For Quarkus 1.11+:
-
 [source,xml]
 ----
 <dependency>
@@ -745,24 +723,6 @@ For Quarkus 1.11+:
 </dependency>
 ----
 
-For Quarkus < 1.11:
-
-[source,xml]
-----
-<dependency>
-  <groupId>com.datastax.oss</groupId>
-  <artifactId>java-driver-metrics-micrometer</artifactId>
-</dependency>
-<dependency>
-  <groupId>io.quarkus</groupId>
-  <artifactId>quarkus-micrometer</artifactId>
-</dependency>
-<dependency>
-  <groupId>io.micrometer</groupId>
-  <artifactId>micrometer-registry-prometheus</artifactId>
-</dependency>
-----
-
 This guide uses Micrometer, so the above dependencies are already included in this guide's pom.xml.
 
 === Enabling Metrics with MicroProfile Metrics
@@ -784,7 +744,7 @@ Remove any dependency to Micrometer from your pom.xml, then add the following on
 === Enabling Cassandra Metrics
 
 Even when metrics are enabled in your application, the Cassandra client will not report any metrics,
-unless you opt-in for this feature. So your next step is to enable Cassandra metrics in your
+unless you opt in for this feature. So your next step is to enable Cassandra metrics in your
 `application.properties` file.
 
 [source,properties]
@@ -861,17 +821,17 @@ you can run the native executable as follows:
 
 You can then point your browser to `http://localhost:8080/fruits.html` and use your application.
 
-== Eager vs Lazy Initialization
+== Choosing between eager and lazy initialization
 
 As explained above, this extension allows you to inject many types of beans:
 
 - A simple bean like `QuarkusCqlSession` or `FruitDao`;
-- The asynchronous version of that bean, e.g. `CompletionStage<QuarkusCqlSession>` or
-  `CompletionStage<FruitDao>;
-- The reactive version of that bean, e.g., `Uni<QuarkusCqlSession>` or `Uni<FruitDao>`.
+- The asynchronous version of that bean, for example `CompletionStage<QuarkusCqlSession>` or
+`CompletionStage<FruitDao>;
+- The reactive version of that bean, for example `Uni<QuarkusCqlSession>` or `Uni<FruitDao>`.
 
 The most straightforward approach is obviously to inject the bean directly. This should work just
-fine for most applications; however, the `QuarkusCqlSession` bean, and all DAO beans that depend on
+fine for most applications. However, the `QuarkusCqlSession` bean, and all DAO beans that depend on
 it, might take some time to initialize before they can be used for the first time, and this process
 is blocking.
 
@@ -884,21 +844,21 @@ that needs to interact with the Cassandra database.
 
 Using lazy initialization speeds up your application startup time, and avoids startup failures if
 the Cassandra database is not available. However, it could also prove dangerous if your code is
-fully asynchronous, e.g. if you are using https://quarkus.io/guides/reactive-routes[reactive
-routes]: indeed, the lazy initialization could accidentally happen on a thread that is not allowed
+fully non-blocking, for example if it uses https://quarkus.io/guides/reactive-routes[reactive
+routes]. Indeed, the lazy initialization could accidentally happen on a thread that is not allowed
 to block, such as a Vert.x event loop thread. Therefore, setting `quarkus.cassandra.init.eager-init`
 to `false` and injecting `QuarkusCqlSession` should be avoided in these contexts.
 
-If you want to use Vert.x (or any other reactive framework) and keep the lazy initialization
-behavior, you should instead inject only `CompletionStage<QuarkusCqlSession>` or
-`Uni<QuarkusCqlSession>`. When injecting these beans, the initialization process will be triggered
-lazily, but it will happen in the background, in a non-blocking way, leveraging the Vert.x event
-loop. This way you don't risk blocking the Vert.x thread.
+If you want to use Vert.x (or any other non-blocking framework) and keep the lazy initialization
+behavior, you should instead inject only a `CompletionStage` or a `Uni` of the desired bean. When
+injecting these beans, the initialization process will be triggered lazily, but it will happen in
+the background, in a non-blocking way, leveraging the Vert.x event loop. This way you don't risk
+blocking the Vert.x thread.
 
 Alternatively, you can set `quarkus.cassandra.init.eager-init` to true: in this case the session
-bean will be initialized eagerly during application startup, on the Quarkus main thread. This would
-eliminate any risk of blocking a Vert.x thread, at the cost of making your startup time (much)
-longer.
+bean and all DAO beans will be initialized eagerly during application startup, on the Quarkus main
+thread. This would eliminate any risk of blocking a Vert.x thread, at the cost of making your
+startup time (much) longer.
 
 == Conclusion
 

quickstart/pom.xml

@@ -80,7 +80,7 @@
     </dependency>
     <dependency>
       <groupId>io.quarkus</groupId>
-      <artifactId>quarkus-resteasy-reactive-jsonb</artifactId>
+      <artifactId>quarkus-resteasy-reactive-jackson</artifactId>
     </dependency>
     <dependency>
       <groupId>io.quarkus</groupId>