diff --git a/docs/src/main/asciidoc/cassandra.adoc b/docs/src/main/asciidoc/cassandra.adoc index 0ca94f3231095..b6ebb0c1790e5 100644 --- a/docs/src/main/asciidoc/cassandra.adoc +++ b/docs/src/main/asciidoc/cassandra.adoc @@ -131,11 +131,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. @@ -149,7 +149,7 @@ 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. @@ -191,12 +191,12 @@ 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 driver ships +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 make sure this is the one -you are using. Also, never use both annotation processors together. +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 `java-driver-mapper-runtime` dependency in compile scope in the project's `pom.xml` @@ -214,10 +214,10 @@ IMPORTANT: Although this module is called "runtime", it must be declared in comp 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. @@ -807,17 +807,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` or +- The asynchronous version of that bean, for example `CompletionStage` or `CompletionStage; -- The reactive version of that bean, e.g., `Uni` or `Uni`. +- The reactive version of that bean, for example `Uni` or `Uni`. 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. @@ -830,8 +830,8 @@ 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 non-blocking, 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.