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