docs: enhance the fluent api section

Signed-off-by: Maximillian Arruda <dearrudam@gmail.com>
jakartaee · Jun 10, 2023 · b4727e3 · b4727e3
1 parent 55ef201
commit b4727e3
Showing 1 changed file with 16 additions and 7 deletions.
diff --git a/spec/src/main/asciidoc/chapters/introduction/introduction.adoc b/spec/src/main/asciidoc/chapters/introduction/introduction.adoc
@@ -47,7 +47,7 @@ The https://jakarta.ee/specifications/persistence/[Jakarta Persistence] specific
 
 [source,java,subs="quotes"]
 ----
-ColumnTemplate template = // instance; a template to document NoSQL operations
+Template template = // instance; a template to document NoSQL operations
 Deity diana = Deity.builder()
         .withId("diana")
         .withName("Diana")
@@ -60,7 +60,7 @@ template.insert(diana, *ttl*);
 
 === A Fluent API
 
-Jakarta NoSQL is a fluent API for Java developers to more easily create queries that either retrieve or delete information in a `NoSQL` database type. For example:
+Jakarta NoSQL provides a fluent API for Java developers to more easily create queries that either retrieve or delete information in a `NoSQL` database type. For example, given the scenario below:
 
 [source,java]
 ----
@@ -73,18 +73,27 @@ Deity diana = Deity.builder()
 
 template.insert(diana);// insert an entity
 
+----
+
+It’s possible to retrieve information by using the Fluent API which is a uniform way to define query criteria independent of each NoSQL database type:
+
+[source,java]
+----
 List<Deity> deities = template.select(Deity.class)
         .where("name")
         .eq("Diana").result(); // SELECT Deity WHERE name equals “Diana”
-
+----
+And, with this uniform API, it’s possible to perform deletions by providing a flexible criteria selection:
+[source,java]
+----
 template.delete(Deity.class).where("name")
         .eq("Diana").execute();
 ----
 
 === Key Features
 
-* Simple APIs that support all well-known NoSQL storage types.
-* Specialized NoSQL types: Key-Value, Column Family, Document databases
-* Use of Convention Over Configuration
-* Easy-to-implement API Specification and Technology Compatibility Kit (TCK) for NoSQL Vendors
+* Simple APIs that support all well-known NoSQL storage types;
+* Specialized NoSQL types: Key-Value, Column Family, Document databases;
+* Use of Convention Over Configuration;
+* Easy-to-implement API Specification and Technology Compatibility Kit (TCK) for NoSQL Vendors;
 * The API's focus is on simplicity and ease of use. Developers should only know minimal artifacts to work with Jakarta NoSQL.