From 52aaf327dd59389f5a6cb3e8c6f7ce75b9dee8c5 Mon Sep 17 00:00:00 2001
From: Otavio Santana
Date: Mon, 11 Mar 2024 19:02:48 +0000
Subject: [PATCH] docs: enhance keyvalue template
Signed-off-by: Otavio Santana
---
.../mapping/keyvalue/KeyValueTemplate.java | 84 ++++++++++---------
1 file changed, 43 insertions(+), 41 deletions(-)
diff --git a/jnosql-mapping/jnosql-mapping-key-value/src/main/java/org/eclipse/jnosql/mapping/keyvalue/KeyValueTemplate.java b/jnosql-mapping/jnosql-mapping-key-value/src/main/java/org/eclipse/jnosql/mapping/keyvalue/KeyValueTemplate.java
index fbb9b189d..835e10d34 100644
--- a/jnosql-mapping/jnosql-mapping-key-value/src/main/java/org/eclipse/jnosql/mapping/keyvalue/KeyValueTemplate.java
+++ b/jnosql-mapping/jnosql-mapping-key-value/src/main/java/org/eclipse/jnosql/mapping/keyvalue/KeyValueTemplate.java
@@ -18,55 +18,55 @@
*
*
*
- * This interface provides some methods that accepts queries in a text format to retrieve from the database but,
- * the query syntax belongs to each provider, thus, it is not Jakarta's NoSQL scope to define it.
- * Accordingly, it might vary from implementation and NoSQL provider.
+ * This interface provides some methods that accept queries in a text format to retrieve data from the database, but
+ * the query syntax belongs to each provider, thus, it is not within Jakarta NoSQL's scope to define it.
+ * Accordingly, it might vary between implementations and NoSQL providers.
*
*/
public interface KeyValueTemplate extends Template {
/**
- * Saves the entity
+ * Saves an entity.
*
* @param entity the entity to be inserted
* @param the entity type
- * @return the entity
- * @throws NullPointerException when entity is null
+ * @return the saved entity
+ * @throws NullPointerException when the entity is null
*/
T put(T entity);
/**
- * Saves the entity with time to live
+ * Saves an entity with a specified time to live (TTL).
*
* @param entity the entity to be inserted
- * @param ttl the defined time to live
+ * @param ttl the time to live
* @param the entity type
- * @return the entity
- * @throws NullPointerException when entity is null
+ * @return the saved entity
+ * @throws NullPointerException when the entity is null
* @throws UnsupportedOperationException when expired time is not supported
*/
T put(T entity, Duration ttl);
/**
- * Saves the {@link Iterable} of entities
+ * Saves an {@link Iterable} of entities.
*
- * @param entities keys to be inserted
+ * @param entities the entities to be inserted
* @param the entity type
- * @return the entities
+ * @return the saved entities
* @throws NullPointerException when the iterable is null
*/
default Iterable put(Iterable entities) {
Objects.requireNonNull(entities, "entities is required");
- return StreamSupport.stream(entities.spliterator(), false).map(this::put).toList();
+ return StreamSupport.stream(entities.spliterator(), false).map(this::put).collect(Collectors.toList());
}
/**
- * Saves the {@link Iterable} of entities with a defined time to live
+ * Saves an {@link Iterable} of entities with a specified time to live (TTL).
*
- * @param entities entities to be insert
- * @param ttl the time to entity expire
+ * @param entities the entities to be inserted
+ * @param ttl the time to live
* @param the entity type
- * @return the entities
- * @throws NullPointerException when the iterable is null
+ * @return the saved entities
+ * @throws NullPointerException when the iterable or ttl is null
* @throws UnsupportedOperationException when expired time is not supported
*/
default Iterable put(Iterable entities, Duration ttl) {
@@ -76,98 +76,100 @@ default Iterable put(Iterable entities, Duration ttl) {
}
/**
- * Finds the Value from a key
+ * Finds the value associated with a key.
*
* @param key the key
* @param the key type
* @param the entity type
* @param type the entity class to convert the result
- * @return the {@link Optional} when is not found will return a {@link Optional#empty()}
+ * @return an {@link Optional} containing the value, or {@link Optional#empty()} if not found
* @throws NullPointerException when the key is null
*/
Optional get(K key, Class type);
/**
- * Executes a query database.
+ * Executes a database query.
*
*
- * The query syntax belongs to each provider, thus, it is not Jakarta's NoSQL scope to define it. Accordingly, it might vary from implementation and NoSQL provider.
+ * The query syntax belongs to each provider, thus, it is not within Jakarta NoSQL's scope to define it.
+ * Accordingly, it might vary between implementations and NoSQL providers.
*
*
* @param query the query
* @param type the entity class
* @param the entity type
- * @return the result list, if either put or remove it will return empty
- * @throws NullPointerException when query is null, if the query is get the entity class is required
+ * @return a stream of query results; an empty stream if no results are found
+ * @throws NullPointerException when the query is null, or when the query is 'get' and the entity class is not provided
* @throws UnsupportedOperationException when the provider does not support query by text
*/
Stream query(String query, Class type);
/**
- * Executes a query database then returns as single result
+ * Executes a database query and returns a single result.
*
*
- * The query syntax belongs to each provider, thus, it is not Jakarta's NoSQL scope to define it. Accordingly, it might vary from implementation and NoSQL provider.
+ * The query syntax belongs to each provider, thus, it is not within Jakarta NoSQL's scope to define it.
+ * Accordingly, it might vary between implementations and NoSQL providers.
*
*
* @param query the query
* @param type the entity class
* @param the entity type
- * @return the result {@link Optional}, if either put or remove it will return {@link Optional#empty()}
- * @throws NullPointerException when query is null, if the query is get the entity class is required
+ * @return an {@link Optional} containing the single result, or {@link Optional#empty()} if no result is found
+ * @throws NullPointerException when the query is null, or when the query is 'get' and the entity class is not provided
* @throws UnsupportedOperationException when the provider does not support query by text
*/
Optional getSingleResult(String query, Class type);
/**
- * Executes a query database and don't return result, e.g.: when the query is either remove or
- * put
+ * Executes a database query without returning a result, e.g., for 'put' or 'remove' operations.
*
* @param query the query
- * @throws NullPointerException when query is null
+ * @throws NullPointerException when the query is null
* @throws UnsupportedOperationException when the provider does not support query by text
*/
void query(String query);
/**
- * Executes a query database with {@link PreparedStatement}
+ * Executes a database query with a {@link PreparedStatement}.
*
*
- * The query syntax belongs to each provider, thus, it is not Jakarta's NoSQL scope to define it. Accordingly, it might vary from implementation and NoSQL provider.
+ * The query syntax belongs to each provider, thus, it is not within Jakarta NoSQL's scope to define it.
+ * Accordingly, it might vary between implementations and NoSQL providers.
*
*
* @param query the query
* @param type the entity class
* @param the entity type
* @return a {@link PreparedStatement} instance
- * @throws NullPointerException when query is null, if the query is get the entity class is required
+ * @throws NullPointerException when the query is null, or when the query is 'get' and the entity class is not provided
* @throws UnsupportedOperationException when the provider does not support query by text
*/
PreparedStatement prepare(String query, Class type);
/**
- * Finds a list of values from keys
+ * Finds a list of values associated with the specified keys.
*
* @param type the entity class
* @param keys the keys to be used in this query
* @param the key type
* @param the entity type
- * @return the list of result
- * @throws NullPointerException when either the keys or the entities values are null
+ * @return a list of results
+ * @throws NullPointerException when either the keys or the entity values are null
*/
Iterable get(Iterable keys, Class type);
/**
- * Removes an entity from key
+ * Removes an entity associated with the specified key.
*
- * @param key the key bo be used
+ * @param key the key to be used
* @param the key type
* @throws NullPointerException when the key is null
*/
void delete(K key);
/**
- * Removes entities from keys
+ * Removes entities associated with the specified keys.
*
* @param keys the keys to be used
* @param the key type