docs: include sample at the template interface

Signed-off-by: Otavio Santana <otaviopolianasantana@gmail.com>

spec/src/main/asciidoc/chapters/api/template.adoc

@@ -1,35 +1,53 @@
 == Template Classes
 
-The Template feature in Jakarta NoSQL simplifies the implementation of common database operations by providing a basic API to the underlying persistence engine. It follows the standard template pattern, a common design pattern used in software development.
+The DAO (Data Access Object) pattern in Jakarta NoSQL simplifies the implementation of common database operations by providing a basic API to the underlying persistence engine. This pattern encapsulates the logic for interacting with the database, promoting a clean separation between the application's business logic and its data access code.
 
-The Template pattern involves creating a skeletal structure for an algorithm, with some steps implemented and others left to be implemented by subclasses. Similarly, the Template feature in Jakarta NoSQL makes a skeleton around NoSQL database operations, allowing developers to focus on implementing the specific logic required for their application.
+In the DAO pattern, each entity in the application typically has a corresponding DAO class responsible for handling database operations related to that entity. These DAO classes abstract away the complexity of database interactions, providing a simplified interface for performing CRUD (Create, Read, Update, Delete) operations.
 
-The Template feature can be related to the Template Method design pattern, a variation of the Template pattern. In the Template Method pattern, an abstract class defines a template method that encapsulates a series of steps required to perform a task, with some steps implemented and others left to be implemented by subclasses.
+Jakarta NoSQL's DAO feature follows this pattern closely, offering a set of template classes that serve as the foundation for implementing DAOs. These template classes provide pre-defined methods for common database operations, such as saving, updating, querying, and deleting entities.
 
-The Template feature in Jakarta NoSQL also defines a template method for performing NoSQL database operations, with some steps implemented and others left to be implemented by the developer.
+Developers can extend these template classes to create custom DAOs for their application entities. By doing so, they can focus on implementing the specific logic required for their application, while the underlying Jakarta NoSQL framework handles the low-level database interactions.
 
-Overall, the Template feature in Jakarta NoSQL provides a simple and efficient way to implement common database operations while following established design patterns like the Template Method. By using the Template feature, developers can save time and effort in implementing their NoSQL database operations, allowing them to focus on other aspects of their application.
+Overall, the DAO pattern in Jakarta NoSQL promotes modularity, reusability, and maintainability in application development by abstracting away database access details. By adhering to this pattern, developers can create robust and scalable applications with ease, without having to deal with the complexities of database interaction at the application level.
+
+The provided code snippet demonstrates the usage of the `Template` class in Jakarta NoSQL to perform basic CRUD operations on entities in the database using the DAO pattern.
+
+1. **Create Book Entity**: An instance of the `Book` entity is created using the builder pattern. This entity represents a book with attributes such as title, author, publication year, and edition.
+
+2. **Insert Operation**: The `insert` method of the `Template` class is invoked to insert the `Book` entity into the database. This method takes the entity as a parameter and stores it in the underlying database.
+
+3. **Find Operation**: The `find` method of the `Template` class is called to retrieve the `Book` entity from the database based on its ID (`id`). This method returns an `Optional` object containing the retrieved entity, if it exists.
+
+4. **Print Result**: The retrieved `Book` entity is printed to the console using `System.out.println`. If the entity exists in the database, it will be printed; otherwise, the output will indicate that the entity was not found.
+
+5. **Delete Operation**: Finally, the `delete` method of the `Template` class is used to delete the `Book` entity from the database based on its ID. This method removes the entity from the database.
+
+Overall, this code snippet demonstrates how to use the `Template` class in Jakarta NoSQL to interact with the database, abstracting away the low-level details of database operations and providing a simplified interface for performing CRUD operations on entities.
 
 [source,java]
 ----
 @Inject
 Template template;
 
+//1. Create Book Entity
 Book book = Book.builder()
         .id(id)
         .title("Java Concurrency in Practice")
         .author("Brian Goetz")
         .year(Year.of(2006))
         .edition(1)
         .build();
-
+//2. Insert Operation
 template.insert(book);
+//3. Find Operation
 Optional<Book> optional = template.find(Book.class, id);
+//4. Print Result
 System.out.println("The result " + optional);
+//5. Delete Operation
 template.delete(Book.class, id);
 ----
 
-Furthermore, in CRUD operations, Template provides a fluent-API for either select or delete entities. Thus, Template offers the capability for search and remove beyond the ID attribute.
+The `Template` class in Jakarta NoSQL simplifies CRUD (Create, Read, Update, Delete) operations by providing a fluent API for interacting with the underlying NoSQL database. This API allows developers to perform advanced queries and deletion operations beyond the basic ID attribute.
 
 [source,java]
 ----
@@ -50,3 +68,23 @@ template.delete(Book.class)
         .gt(3)
         .execute();
 ----
+
+The fluent API feature for searching and removing entities provided by the `Template` class in Jakarta NoSQL offers excellent flexibility and convenience for CRUD operations. However, it's essential to note that this feature may only be fully supported for some types of NoSQL databases, as the capabilities of the underlying database technology may limit certain operations.
+
+In cases where the underlying NoSQL database does not support advanced querying or deletion beyond the basic ID attribute, attempting to use these features with the `Template` class will result in an `UnsupportedOperationException` being thrown by Jakarta NoSQL. This exception indicates that the current database type does not support the requested operation.
+
+Some NoSQL databases may not support all filter operations, such as logical OR operations in the fluent API. In such cases, attempting to use unsupported operations with the `Template` class will result in an `UnsupportedOperationException` being thrown by Jakarta NoSQL. This exception indicates that the current Jakarta NoSQL provider does not support the requested operation due to limitations imposed by the underlying NoSQL database technology.
+
+Developers should be aware that while Jakarta NoSQL aims to provide a unified API across different NoSQL databases, there may be variations in support for certain operations depending on the capabilities of the specific database provider. When encountering limitations or unsupported operations, developers may need to adjust their application logic or consider alternative approaches to achieve the desired functionality within the constraints of the chosen NoSQL database technology.
+
+
+In case of querying an entity using the `@Inheritance` annotation as defined by <<inheritance_definition>>, the Jakarta NoSQL provider must automatically include the condition where the value from `@DiscriminatorColumn` equals the value of `@DiscriminatorValue`.
+
+For example, given the sample code from <<inheritance_definition>> and executing the query for `SmsNotification`, the generated query should include a condition such as `type = 'SMS'` or its equivalent in the respective NoSQL database.
+
+[source,java]
+----
+List<SmsNotification> notifications = template.select(SmsNotification.class);
+----
+
+It ensures that only entities of type `SmsNotification`, as indicated by the discriminator value, are retrieved from the database.