docs: update database manager

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

jnosql-communication/jnosql-communication-semistructured/src/main/java/org/eclipse/jnosql/communication/semistructured/ColumnQueryParser.java

@@ -43,7 +43,7 @@ public final class ColumnQueryParser {
      * @throws IllegalArgumentException when the query has value parameters
      * @throws QueryException           when there is error in the syntax
      */
-    public Stream<CommunicationEntity> query(String query, DatabaseManager manager, ColumnObserverParser observer) {
+    public Stream<CommunicationEntity> query(String query, DatabaseManager manager, CommunicationObserverParser observer) {
         validation(query, manager, observer);
         String command = query.substring(0, 6);
         return switch (command) {
@@ -68,7 +68,7 @@ public Stream<CommunicationEntity> query(String query, DatabaseManager manager,
      * @throws IllegalArgumentException when the query has value parameters
      * @throws QueryException           when there is error in the syntax
      */
-    public CommunicationPreparedStatement prepare(String query, DatabaseManager manager, ColumnObserverParser observer) {
+    public CommunicationPreparedStatement prepare(String query, DatabaseManager manager, CommunicationObserverParser observer) {
         validation(query, manager, observer);
         String command = query.substring(0, 6);
 
@@ -83,7 +83,7 @@ public CommunicationPreparedStatement prepare(String query, DatabaseManager mana
     }
 
 
-    private void validation(String query, DatabaseManager manager, ColumnObserverParser observer) {
+    private void validation(String query, DatabaseManager manager, CommunicationObserverParser observer) {
         Objects.requireNonNull(query, "query is required");
         Objects.requireNonNull(manager, "manager is required");
         Objects.requireNonNull(observer, "manager is observer");

jnosql-communication/jnosql-communication-semistructured/src/main/java/org/eclipse/jnosql/communication/semistructured/ColumnObserverParser.java → jnosql-communication/jnosql-communication-semistructured/src/main/java/org/eclipse/jnosql/communication/semistructured/CommunicationObserverParser.java

@@ -20,9 +20,9 @@
  * An observer to a parser; this observer allows checking both the name of an entity and the fields.
  * This observer might be used to the mapper process.
  */
-public interface ColumnObserverParser {
+public interface CommunicationObserverParser {
 
-    ColumnObserverParser EMPTY = new ColumnObserverParser() {
+    CommunicationObserverParser EMPTY = new CommunicationObserverParser() {
     };
 
     /**

jnosql-communication/jnosql-communication-semistructured/src/main/java/org/eclipse/jnosql/communication/semistructured/ConditionQueryParser.java

@@ -30,7 +30,7 @@ abstract class ConditionQueryParser {
 
 
     protected CommunicationEntity getEntity(ConditionQuerySupplier query, String columnFamily, Params params,
-                                            ColumnObserverParser observer) {
+                                            CommunicationObserverParser observer) {
         CommunicationEntity entity = CommunicationEntity.of(columnFamily);
 
         if (query.useJSONCondition()) {

jnosql-communication/jnosql-communication-semistructured/src/main/java/org/eclipse/jnosql/communication/semistructured/Conditions.java

@@ -28,12 +28,12 @@ final class Conditions {
     private Conditions() {
     }
 
-    static CriteriaCondition getCondition(Where where, Params params, ColumnObserverParser observer, String entity) {
+    static CriteriaCondition getCondition(Where where, Params params, CommunicationObserverParser observer, String entity) {
         QueryCondition condition = where.condition();
         return getCondition(condition, params, observer, entity);
     }
 
-    static CriteriaCondition getCondition(QueryCondition condition, Params parameters, ColumnObserverParser observer, String entity) {
+    static CriteriaCondition getCondition(QueryCondition condition, Params parameters, CommunicationObserverParser observer, String entity) {
         return switch (condition.condition()) {
             case EQUALS -> CriteriaCondition.eq(Element.of(getName(condition, observer, entity),
                     Values.get(condition.value(), parameters)));
@@ -68,7 +68,7 @@ static CriteriaCondition getCondition(QueryCondition condition, Params parameter
         };
     }
 
-    private static String getName(QueryCondition condition, ColumnObserverParser observer, String entity) {
+    private static String getName(QueryCondition condition, CommunicationObserverParser observer, String entity) {
         return observer.fireField(entity, condition.name());
     }
 

jnosql-communication/jnosql-communication-semistructured/src/main/java/org/eclipse/jnosql/communication/semistructured/DatabaseManager.java

@@ -41,68 +41,141 @@ public interface DatabaseManager extends AutoCloseable {
     String name();
 
     /**
-     * Saves an entity into the database.
+     * <p>Inserts an entity into the database. If an entity of this type with the same
+     * unique identifier already exists in the database and the database supports ACID transactions,
+     * then this method raises an exception. In databases that follow the BASE model
+     * or use an append model to write data, this exception is not thrown.</p>
+     *
+     * <p>The entity instance returned as a result of this method must include all values that were
+     * written to the database, including all automatically generated values and incremented values
+     * that changed due to the insert. After invoking this method, do not continue to use the instance
+     * that is supplied as a parameter. This method makes no guarantees about the state of the
+     * instance that is supplied as a parameter.</p>
      *
      * @param entity the entity to be saved
      * @return the saved entity
      * @throws NullPointerException when the provided entity is null
      */
     CommunicationEntity insert(CommunicationEntity entity);
 
+
     /**
-     * Updates an entity in the database.
+     * Inserts an entity into the database with an expiration to the entity. If an entity of this type with the same
+     * unique identifier already exists in the database and the database supports ACID transactions,
+     * then this method raises an error. In databases that follow the BASE model
+     * or use an append model to write data, this exception is not thrown.
      *
-     * @param entity the entity to be updated
-     * @return the updated entity
-     * @throws NullPointerException when the provided entity is null
+     * <p>The entity instance returned as a result of this method must include all values that were
+     * written to the database, including all automatically generated values and incremented values
+     * that changed due to the insert. After invoking this method, do not continue to use the instance
+     * that is supplied as a parameter. This method makes no guarantees about the state of the
+     * instance that is supplied as a parameter.</p>
+     *
+     * <p>Time-To-Live (TTL) is a feature provided by some NoSQL databases where data is automatically removed from the
+     * database after a specified duration. When inserting an entity with a TTL, the entity will be automatically deleted
+     * from the database after the specified duration has passed since its insertion. If the database does not support TTL
+     * or if the TTL feature is not enabled, this operation will not have any effect on the entity's expiration.</p>
+     *
+     * @param entity the entity to insert. Must not be {@code null}.
+     * @param ttl    time to live
+     * @return the inserted entity, which may or may not be a different instance depending on whether the insert caused
+     * values to be generated or automatically incremented.
+     * @throws NullPointerException          if the entity is null.
+     * @throws UnsupportedOperationException when the database does not provide TTL
      */
-    CommunicationEntity update(CommunicationEntity entity);
+    CommunicationEntity insert(CommunicationEntity entity, Duration ttl);
 
     /**
-     * Updates multiple entities in the database. By default, each entity is updated
-     * individually using {@link DatabaseManager#update(CommunicationEntity)}. Each NoSQL vendor may
-     * provide a more appropriate implementation.
+     * Inserts multiple entities into the database. If any entity of this type with the same
+     * unique identifier as any of the given entities already exists in the database and the database
+     * supports ACID transactions, then this method raises an error.
+     * In databases that follow the BASE model or use an append model to write data, this exception
+     * is not thrown.
      *
-     * @param entities the entities to be updated
-     * @return the updated entities
-     * @throws NullPointerException when the provided collection of entities is null
+     * <p>The entities within the returned {@link Iterable} must include all values that were
+     * written to the database, including all automatically generated values and incremented values
+     * that changed due to the insert. After invoking this method, do not continue to use
+     * the entity instances that are supplied in the parameter. This method makes no guarantees
+     * about the state of the entity instances that are supplied in the parameter.
+     * The position of entities within the {@code Iterable} return value must correspond to the
+     * position of entities in the parameter based on the unique identifier of the entity.</p>
+     *
+     * @param entities entities to insert.
+     * @return an iterable containing the inserted entities, which may or may not be different instances depending
+     * on whether the insert caused values to be generated or automatically incremented.
+     * @throws NullPointerException if the iterable is null or any element is null.
      */
-    Iterable<CommunicationEntity> update(Iterable<CommunicationEntity> entities);
+    Iterable<CommunicationEntity> insert(Iterable<CommunicationEntity> entities);
 
     /**
-     * Saves an entity into the database with a specified time to live (TTL).
+     * Inserts multiple entities into the database with the expiration date. If any entity of this type with the same
+     * unique identifier as any of the given entities already exists in the database and the database
+     * supports ACID transactions, then this method raises an error.
+     * In databases that follow the BASE model or use an append model to write data, this exception
+     * is not thrown.
      *
-     * @param entity the entity to be saved
-     * @param ttl    the time to live for the entity
-     * @return the saved entity
-     * @throws NullPointerException          when either the entity or the TTL is null
-     * @throws UnsupportedOperationException when the database does not support this feature
+     * <p>The entities within the returned {@link Iterable} must include all values that were
+     * written to the database, including all automatically generated values and incremented values
+     * that changed due to the insert. After invoking this method, do not continue to use
+     * the entity instances that are supplied in the parameter. This method makes no guarantees
+     * about the state of the entity instances that are supplied in the parameter.
+     * The position of entities within the {@code Iterable} return value must correspond to the
+     * position of entities in the parameter based on the unique identifier of the entity.</p>
+     *
+     * <p>Time-To-Live (TTL) is a feature provided by some NoSQL databases where data is automatically removed from the
+     * database after a specified duration. When inserting entities with a TTL, the entities will be automatically deleted
+     * from the database after the specified duration has passed since their insertion. If the database does not support TTL
+     * or if the TTL feature is not enabled, this operation will not have any effect on the expiration of the entities.</p>
+     *
+     * @param entities entities to insert.
+     * @param ttl      time to live
+     * @return an iterable containing the inserted entities, which may or may not be different instances depending
+     * on whether the insert caused values to be generated or automatically incremented.
+     * @throws NullPointerException if the iterable is null or any element is null.
+     * @throws UnsupportedOperationException if the database does not provide time-to-live for insert operations.
      */
-    CommunicationEntity insert(CommunicationEntity entity, Duration ttl);
+    Iterable<CommunicationEntity> insert(Iterable<CommunicationEntity> entities, Duration ttl);
 
     /**
-     * Saves multiple entities into the database. By default, each entity is saved
-     * individually using {@link DatabaseManager#insert(CommunicationEntity)}. Each NoSQL vendor may
-     * provide a more appropriate implementation.
+     * Modifies an entity that already exists in the database.
+     *
+     * <p>For an update to be made, a matching entity with the same unique identifier
+     * must be present in the database. In databases that use an append model to write data or
+     * follow the BASE model, this method behaves the same as the {@link #insert} method.</p>
      *
-     * @param entities the entities to be saved
-     * @return the saved entities
-     * @throws NullPointerException when the provided collection of entities is null
+     * <p>If the entity is versioned (for example, with an annotation or by
+     * another convention from the entity model such as having an attribute named {@code version}),
+     * then the version must also match. The version is automatically incremented when making
+     * the update.</p>
+     *
+     * <p>Non-matching entities are ignored and do not cause an error to be raised.</p>
+     *
+     * @param entity the entity to update. Must not be {@code null}.
+     * @return the updated entity, which may or may not be a different instance depending on whether the update caused
+     * values to be generated or automatically incremented.
+     * @throws NullPointerException if the entity is null.
      */
-    Iterable<CommunicationEntity> insert(Iterable<CommunicationEntity> entities);
+    CommunicationEntity update(CommunicationEntity entity);
 
     /**
-     * Saves multiple entities into the database with a specified time to live (TTL).
-     * By default, each entity is saved individually using {@link DatabaseManager#insert(CommunicationEntity, Duration)}.
-     * Each NoSQL vendor may provide a more appropriate implementation.
+     * Modifies entities that already exist in the database.
+     *
+     * <p>For an update to be made to an entity, a matching entity with the same unique identifier
+     * must be present in the database. In databases that use an append model to write data or
+     * follow the BASE model, this method behaves the same as the {@link #insert(Iterable)} method.</p>
+     *
+     * <p>If the entity is versioned (for example, with an annotation or by
+     * another convention from the entity model such as having an attribute named {@code version}),
+     * then the version must also match. The version is automatically incremented when making
+     * the update.</p>
      *
-     * @param entities the entities to be saved
-     * @param ttl      the time to live for the entities
-     * @return the saved entities
-     * @throws NullPointerException          when either the collection of entities or the TTL is null
-     * @throws UnsupportedOperationException when the database does not support this feature
+     * <p>Non-matching entities are ignored and do not cause an error to be raised.</p>
+     *
+     * @param entities entities to update.
+     * @return the number of matching entities that were found in the database to update.
+     * @throws NullPointerException if either the iterable is null or any element is null.
      */
-    Iterable<CommunicationEntity> insert(Iterable<CommunicationEntity> entities, Duration ttl);
+    Iterable<CommunicationEntity> update(Iterable<CommunicationEntity> entities);
 
     /**
      * Deletes entities from the database based on the specified query.
@@ -160,7 +233,7 @@ default boolean exists(SelectQuery query) {
     default Stream<CommunicationEntity> query(String query) {
         Objects.requireNonNull(query, "query is required");
         ColumnQueryParser parser = new ColumnQueryParser();
-        return parser.query(query, this, ColumnObserverParser.EMPTY);
+        return parser.query(query, this, CommunicationObserverParser.EMPTY);
     }
 
     /**
@@ -174,7 +247,7 @@ default Stream<CommunicationEntity> query(String query) {
     default CommunicationPreparedStatement prepare(String query) {
         Objects.requireNonNull(query, "query is required");
         ColumnQueryParser parser = new ColumnQueryParser();
-        return parser.prepare(query, this, ColumnObserverParser.EMPTY);
+        return parser.prepare(query, this, CommunicationObserverParser.EMPTY);
     }
 
     /**

jnosql-communication/jnosql-communication-semistructured/src/main/java/org/eclipse/jnosql/communication/semistructured/DeleteQueryParser.java

@@ -28,11 +28,11 @@
 
 import static java.util.Objects.requireNonNull;
 
-public final class DeleteQueryParser implements BiFunction<org.eclipse.jnosql.communication.query.DeleteQuery, ColumnObserverParser, ColumnDeleteQueryParams> {
+public final class DeleteQueryParser implements BiFunction<org.eclipse.jnosql.communication.query.DeleteQuery, CommunicationObserverParser, ColumnDeleteQueryParams> {
 
 
 
-    Stream<CommunicationEntity> query(String query, DatabaseManager manager, ColumnObserverParser observer) {
+    Stream<CommunicationEntity> query(String query, DatabaseManager manager, CommunicationObserverParser observer) {
 
         DeleteQuery deleteQuery = getQuery(query, observer);
         manager.delete(deleteQuery);
@@ -41,7 +41,7 @@ Stream<CommunicationEntity> query(String query, DatabaseManager manager, ColumnO
 
 
     CommunicationPreparedStatement prepare(String query, DatabaseManager manager,
-                                           ColumnObserverParser observer) {
+                                           CommunicationObserverParser observer) {
         Params params = Params.newParams();
         DeleteQuery deleteQuery = getQuery(query, params, observer);
         return CommunicationPreparedStatement.delete(deleteQuery, params, query, manager);
@@ -51,23 +51,23 @@ CommunicationPreparedStatement prepare(String query, DatabaseManager manager,
 
     @Override
     public ColumnDeleteQueryParams apply(org.eclipse.jnosql.communication.query.DeleteQuery deleteQuery,
-                                         ColumnObserverParser columnObserverParser) {
+                                         CommunicationObserverParser communicationObserverParser) {
 
         requireNonNull(deleteQuery, "deleteQuery is required");
-        requireNonNull(columnObserverParser, "columnObserverParser is required");
+        requireNonNull(communicationObserverParser, "columnObserverParser is required");
         Params params = Params.newParams();
-        DeleteQuery query = getQuery(params, columnObserverParser, deleteQuery);
+        DeleteQuery query = getQuery(params, communicationObserverParser, deleteQuery);
         return new ColumnDeleteQueryParams(query, params);
     }
 
-    private DeleteQuery getQuery(String query, Params params, ColumnObserverParser observer) {
+    private DeleteQuery getQuery(String query, Params params, CommunicationObserverParser observer) {
         DeleteQueryConverter converter = new DeleteQueryConverter();
         org.eclipse.jnosql.communication.query.DeleteQuery deleteQuery = converter.apply(query);
 
         return getQuery(params, observer, deleteQuery);
     }
 
-    private DeleteQuery getQuery(Params params, ColumnObserverParser observer, org.eclipse.jnosql.communication.query.DeleteQuery deleteQuery) {
+    private DeleteQuery getQuery(Params params, CommunicationObserverParser observer, org.eclipse.jnosql.communication.query.DeleteQuery deleteQuery) {
         String columnFamily = observer.fireEntity(deleteQuery.entity());
         List<String> columns = deleteQuery.fields().stream()
                 .map(f -> observer.fireField(columnFamily, f))
@@ -78,7 +78,7 @@ private DeleteQuery getQuery(Params params, ColumnObserverParser observer, org.e
         return new DefaultDeleteQuery(columnFamily, condition, columns);
     }
 
-    private DeleteQuery getQuery(String query, ColumnObserverParser observer) {
+    private DeleteQuery getQuery(String query, CommunicationObserverParser observer) {
 
         DeleteQueryConverter converter = new DeleteQueryConverter();
         org.eclipse.jnosql.communication.query.DeleteQuery deleteQuery = converter.apply(query);