From 8ad8f2419a2c4140ae3cf4a9de6505b0722bb70a Mon Sep 17 00:00:00 2001 From: Otavio Santana Date: Sun, 2 Mar 2025 04:22:04 +0000 Subject: [PATCH 01/39] docs: enhance arangodb template documentation Signed-off-by: Otavio Santana --- .../arangodb/mapping/ArangoDBTemplate.java | 75 +++++++++++-------- 1 file changed, 42 insertions(+), 33 deletions(-) diff --git a/jnosql-arangodb/src/main/java/org/eclipse/jnosql/databases/arangodb/mapping/ArangoDBTemplate.java b/jnosql-arangodb/src/main/java/org/eclipse/jnosql/databases/arangodb/mapping/ArangoDBTemplate.java index bf7873b8c..8f12a2fe6 100644 --- a/jnosql-arangodb/src/main/java/org/eclipse/jnosql/databases/arangodb/mapping/ArangoDBTemplate.java +++ b/jnosql-arangodb/src/main/java/org/eclipse/jnosql/databases/arangodb/mapping/ArangoDBTemplate.java @@ -21,62 +21,71 @@ import java.util.Map; import java.util.stream.Stream; /** - * A template specialization for ArangoDB that includes capabilities for executing ArangoDB query language, AQL. - * This template extends {@link DocumentTemplate} and provides methods for executing AQL queries with various - * options. + * A specialized {@link DocumentTemplate} for ArangoDB, providing methods to execute + * queries using the ArangoDB Query Language (AQL). + * + *

This template allows executing AQL queries with named parameters and supports + * result serialization either through Eclipse JNoSQL or directly via ArangoDB.

*/ public interface ArangoDBTemplate extends DocumentTemplate { /** * Executes an ArangoDB query using the ArangoDB Query Language (AQL). * - *

Example query: {@code FOR u IN users FILTER u.status == @status RETURN u}

+ *

Example query:

+ * 
{@code
+     * FOR u IN users FILTER u.status == @status RETURN u
+     * }
* - *

The conversion from the query result to entities will happen at the Eclipse JNoSQL side. - * It will utilize and consider all the annotations supported by Eclipse JNoSQL.

+ *

The conversion of query results to entity objects is handled by Eclipse JNoSQL, + * applying all supported annotations.

* - * @param the entity class - * @param query the AQL query - * @param params the named parameters for the query + * @param the entity type + * @param query the AQL query string + * @param params a map containing named parameters for the query * @return a {@link Stream} of entities representing the query result - * @throws NullPointerException when either the query or params are null + * @throws NullPointerException if {@code query} or {@code params} is {@code null} */ Stream aql(String query, Map params); /** - * Executes an ArangoDB query using the ArangoDB Query Language (AQL). + * Executes an ArangoDB query using AQL with direct serialization via ArangoDB. * - *

Example query: {@code FOR u IN users FILTER u.status == @status RETURN u}

+ *

Example query:

+ * 
{@code
+     * FOR u IN users FILTER u.status == @status RETURN u
+     * }
* - *

The serialization of the query result will happen at the ArangoDB side using - * {@link com.arangodb.ArangoDatabase#query(String, Class)}. This serialization does not have any converter support - * at the mapper side, - * thus it will ignore any annotations that Eclipse JNoSQL has.

+ *

The serialization of query results is performed directly by ArangoDB using + * {@link com.arangodb.ArangoDatabase#query(String, Class)}, bypassing Eclipse JNoSQL + * converters. Consequently, annotations supported by Eclipse JNoSQL are ignored.

* - * @param query the AQL query - * @param params the named parameters for the query - * @param type the type of the result - * @param the type - * @return a {@link Stream} of the specified type representing the query result - * @throws NullPointerException when either the query or params are null + * @param the expected result type + * @param query the AQL query string + * @param params a map containing named parameters for the query + * @param type the target class for result serialization + * @return a {@link Stream} of results of type {@code T} + * @throws NullPointerException if {@code query}, {@code params}, or {@code type} is {@code null} */ Stream aql(String query, Map params, Class type); /** - * Executes an ArangoDB query using the ArangoDB Query Language (AQL) with an empty parameter map. + * Executes an ArangoDB query using AQL with an empty parameter map. * - *

Example query: {@code FOR u IN users FILTER u.status == @status RETURN u}

+ *

Example query:

+ * 
{@code
+     * FOR u IN users FILTER u.status == @status RETURN u
+     * }
* - *

The serialization of the query result will happen at the ArangoDB side using - * {@link com.arangodb.ArangoDatabase#query(String, Class)}. This serialization does not have any converter support - * at the mapper side, - * thus it will ignore any annotations that Eclipse JNoSQL has.

+ *

The serialization of query results is performed directly by ArangoDB using + * {@link com.arangodb.ArangoDatabase#query(String, Class)}. This means that + * Eclipse JNoSQL annotations will not be considered.

* - * @param query the AQL query - * @param type the type of the result - * @param the type - * @return a {@link Stream} of the specified type representing the query result - * @throws NullPointerException when either the query or type are null + * @param the expected result type + * @param query the AQL query string + * @param type the target class for result serialization + * @return a {@link Stream} of results of type {@code T} + * @throws NullPointerException if {@code query} or {@code type} is {@code null} */ Stream aql(String query, Class type); } From 156985827f2b9361b923d083c9739a97806ac6d7 Mon Sep 17 00:00:00 2001 From: Otavio Santana Date: Sun, 2 Mar 2025 04:24:16 +0000 Subject: [PATCH 02/39] docs: enhance aql annotation Signed-off-by: Otavio Santana --- .../databases/arangodb/mapping/AQL.java | 25 ++++++++++++++++++- 1 file changed, 24 insertions(+), 1 deletion(-) diff --git a/jnosql-arangodb/src/main/java/org/eclipse/jnosql/databases/arangodb/mapping/AQL.java b/jnosql-arangodb/src/main/java/org/eclipse/jnosql/databases/arangodb/mapping/AQL.java index ee7602ab7..0725c2f71 100644 --- a/jnosql-arangodb/src/main/java/org/eclipse/jnosql/databases/arangodb/mapping/AQL.java +++ b/jnosql-arangodb/src/main/java/org/eclipse/jnosql/databases/arangodb/mapping/AQL.java @@ -20,11 +20,34 @@ import java.lang.annotation.Target; /** - * To a dynamic query on ArangoDBRepository and ArangoDBRepositoryAsync interfaces. + * Annotation to define a dynamic AQL (ArangoDB Query Language) query for methods + * in the {@link ArangoDBRepository} interface. + * + *

This annotation enables executing custom AQL queries directly from repository methods, + * similar to how queries are defined in other JNoSQL repositories.

+ * + *

Example usage:

+ * 
{@code
+ * @AQL("FOR p IN Person RETURN p")
+ * List findAll();
+ * }
+ * + *

Parameterized query:

+ * 
{@code
+ * @AQL("FOR p IN Person FILTER p.name == @name RETURN p")
+ * List findByName(@Param("name") String name);
+ * }
+ * + * @see ArangoDBRepository */ @Retention(RetentionPolicy.RUNTIME) @Target(ElementType.METHOD) public @interface AQL { + /** + * The AQL query string to be executed. + * + * @return the AQL query + */ String value(); } From 71aee3ed0108ba0a49661d28ac659aaee7fb278d Mon Sep 17 00:00:00 2001 From: Otavio Santana Date: Sun, 2 Mar 2025 04:24:54 +0000 Subject: [PATCH 03/39] docs: enhance arangodb repository Signed-off-by: Otavio Santana --- .../arangodb/mapping/ArangoDBRepository.java | 21 +++++++++++++++++-- 1 file changed, 19 insertions(+), 2 deletions(-) diff --git a/jnosql-arangodb/src/main/java/org/eclipse/jnosql/databases/arangodb/mapping/ArangoDBRepository.java b/jnosql-arangodb/src/main/java/org/eclipse/jnosql/databases/arangodb/mapping/ArangoDBRepository.java index b5c7b8a78..6b24b8d30 100644 --- a/jnosql-arangodb/src/main/java/org/eclipse/jnosql/databases/arangodb/mapping/ArangoDBRepository.java +++ b/jnosql-arangodb/src/main/java/org/eclipse/jnosql/databases/arangodb/mapping/ArangoDBRepository.java @@ -19,9 +19,26 @@ /** - * The arangodb {@link NoSQLRepository} + * A repository interface for ArangoDB, extending the generic {@link NoSQLRepository}. + * + *

This repository supports executing custom AQL queries via the {@link AQL} annotation.

+ * + *

Example usage:

+ * 
{@code
+ * @Repository
+ * public interface PersonRepository extends ArangoDBRepository {
+ *
+ *     @AQL("FOR p IN Person RETURN p")
+ *     List findAll();
+ *
+ *     @AQL("FOR p IN Person FILTER p.name == @name RETURN p")
+ *     List findByName(@Param("name") String name);
+ * }
+ * }
+ * * @param the entity type - * @param the id entity type + * @param the entity ID type + * @see AQL */ public interface ArangoDBRepository extends NoSQLRepository { } From eeadb7d252469be3cda89d532c852dd31decdb78 Mon Sep 17 00:00:00 2001 From: Otavio Santana Date: Sun, 2 Mar 2025 04:27:01 +0000 Subject: [PATCH 04/39] feat: generate params utls class Signed-off-by: Otavio Santana --- .../jnosql/mapping/driver/ParamUtil.java | 48 +++++++++++++++++++ 1 file changed, 48 insertions(+) create mode 100644 jnosql-database-commons/src/main/java/org/eclipse/jnosql/mapping/driver/ParamUtil.java diff --git a/jnosql-database-commons/src/main/java/org/eclipse/jnosql/mapping/driver/ParamUtil.java b/jnosql-database-commons/src/main/java/org/eclipse/jnosql/mapping/driver/ParamUtil.java new file mode 100644 index 000000000..010f20e4f --- /dev/null +++ b/jnosql-database-commons/src/main/java/org/eclipse/jnosql/mapping/driver/ParamUtil.java @@ -0,0 +1,48 @@ +/* + * Copyright (c) 2025 Contributors to the Eclipse Foundation + * All rights reserved. This program and the accompanying materials + * are made available under the terms of the Eclipse Public License v1.0 + * and Apache License v2.0 which accompanies this distribution. + * The Eclipse Public License is available at http://www.eclipse.org/legal/epl-v10.html + * and the Apache License v2.0 is available at http://www.opensource.org/licenses/apache2.0.php. + * + * You may elect to redistribute this code under either of these licenses. + * + * Contributors: + * + * Otavio Santana + */ +package org.eclipse.jnosql.mapping.driver; + +import jakarta.data.repository.Param; + +import java.lang.annotation.Annotation; +import java.lang.reflect.Method; +import java.util.HashMap; +import java.util.Map; +import java.util.Optional; +import java.util.stream.Stream; + +public enum ParamUtil { + + INSTANCE; + static Map getParams(Object[] args, Method method) { + + Map params = new HashMap<>(); + Annotation[][] annotations = method.getParameterAnnotations(); + + for (int index = 0; index < annotations.length; index++) { + + final Object arg = args[index]; + + Optional param = Stream.of(annotations[index]) + .filter(Param.class::isInstance) + .map(Param.class::cast) + .findFirst(); + param.ifPresent(p -> params.put(p.value(), arg)); + + } + + return params; + } +} From 87eb0e7c9c73fabfe1ebcf432ce9b0073dc4772d Mon Sep 17 00:00:00 2001 From: Otavio Santana Date: Sun, 2 Mar 2025 04:31:37 +0000 Subject: [PATCH 05/39] feat: enhance documentation to param utils Signed-off-by: Otavio Santana --- .../jnosql/mapping/driver/ParamUtil.java | 33 +++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/jnosql-database-commons/src/main/java/org/eclipse/jnosql/mapping/driver/ParamUtil.java b/jnosql-database-commons/src/main/java/org/eclipse/jnosql/mapping/driver/ParamUtil.java index 010f20e4f..22cc6d0bc 100644 --- a/jnosql-database-commons/src/main/java/org/eclipse/jnosql/mapping/driver/ParamUtil.java +++ b/jnosql-database-commons/src/main/java/org/eclipse/jnosql/mapping/driver/ParamUtil.java @@ -23,9 +23,42 @@ import java.util.Optional; import java.util.stream.Stream; +/** + * Utility class for extracting method parameters annotated with {@link Param} across all repository interfaces. + * + *

This utility supports repositories using custom query annotations such as {@code @AQL}, {@code @Cypher}, + * and others, where parameters are annotated with {@link Param} to enable named parameter binding.

+ * + *

Example Usage:

+ * 
{@code
+ * public interface PersonRepository extends DatabaseBRepository {
+ *
+ *     @DatabaseQuery("FOR p IN Person FILTER p.name == @name RETURN p")
+ *     List findByName(@Param("name") String name);
+ * }
+ *
+ * Method method = PersonRepository.class.getMethod("findByName", String.class);
+ * Object[] args = {"John Doe"};
+ * Map params = ParamUtil.INSTANCE.getParams(args, method);
+ * System.out.println(params); // {name=John Doe}
+ * }
+ * + *

The returned map is then used for binding values to query parameters dynamically at runtime.

+ */ public enum ParamUtil { INSTANCE; + + /** + * Extracts parameters annotated with {@link Param} from repository methods and returns them as a key-value map. + * + *

This method is designed to work with various repository query types. + * + * @param args the arguments passed to the repository method invocation + * @param method the repository method whose parameters should be extracted + * @return a map of parameter names (from {@code @Param}) and their corresponding values + * @throws IllegalArgumentException if {@code args} or {@code method} is {@code null} + */ static Map getParams(Object[] args, Method method) { Map params = new HashMap<>(); From 7215a90c5f4200bf1447b8aae052554e2c3f4462 Mon Sep 17 00:00:00 2001 From: Otavio Santana Date: Sun, 2 Mar 2025 04:34:10 +0000 Subject: [PATCH 06/39] feat: generate paramutil test Signed-off-by: Otavio Santana --- .../jnosql/mapping/driver/ParamUtil.java | 2 +- .../jnosql/mapping/driver/ParamUtilTest.java | 102 ++++++++++++++++++ 2 files changed, 103 insertions(+), 1 deletion(-) create mode 100644 jnosql-database-commons/src/test/java/org/eclipse/jnosql/mapping/driver/ParamUtilTest.java diff --git a/jnosql-database-commons/src/main/java/org/eclipse/jnosql/mapping/driver/ParamUtil.java b/jnosql-database-commons/src/main/java/org/eclipse/jnosql/mapping/driver/ParamUtil.java index 22cc6d0bc..b521e30e8 100644 --- a/jnosql-database-commons/src/main/java/org/eclipse/jnosql/mapping/driver/ParamUtil.java +++ b/jnosql-database-commons/src/main/java/org/eclipse/jnosql/mapping/driver/ParamUtil.java @@ -59,7 +59,7 @@ public enum ParamUtil { * @return a map of parameter names (from {@code @Param}) and their corresponding values * @throws IllegalArgumentException if {@code args} or {@code method} is {@code null} */ - static Map getParams(Object[] args, Method method) { + public Map getParams(Object[] args, Method method) { Map params = new HashMap<>(); Annotation[][] annotations = method.getParameterAnnotations(); diff --git a/jnosql-database-commons/src/test/java/org/eclipse/jnosql/mapping/driver/ParamUtilTest.java b/jnosql-database-commons/src/test/java/org/eclipse/jnosql/mapping/driver/ParamUtilTest.java new file mode 100644 index 000000000..c2d1ae5db --- /dev/null +++ b/jnosql-database-commons/src/test/java/org/eclipse/jnosql/mapping/driver/ParamUtilTest.java @@ -0,0 +1,102 @@ +/* + * Copyright (c) 2025 Contributors to the Eclipse Foundation + * All rights reserved. This program and the accompanying materials + * are made available under the terms of the Eclipse Public License v1.0 + * and Apache License v2.0 which accompanies this distribution. + * The Eclipse Public License is available at http://www.eclipse.org/legal/epl-v10.html + * and the Apache License v2.0 is available at http://www.opensource.org/licenses/apache2.0.php. + * + * You may elect to redistribute this code under either of these licenses. + * + * Contributors: + * + * Otavio Santana + */ +package org.eclipse.jnosql.mapping.driver; + +import jakarta.data.repository.Param; +import org.junit.jupiter.api.Test; +import java.lang.reflect.Method; +import java.util.Map; +import java.util.Optional; + +import static org.assertj.core.api.Assertions.assertThat; +import static org.assertj.core.api.Assertions.assertThatThrownBy; + +class ParamUtilTest { + + interface TestRepository { + void findByName(@Param("name") String name); + + void findByAge(@Param("age") int age); + + void findByNameAndAge(@Param("name") String name, @Param("age") int age); + + void findWithoutParams(String input); + } + + @Test + void shouldExtractSingleNamedParameter() throws NoSuchMethodException { + Method method = TestRepository.class.getMethod("findByName", String.class); + Object[] args = {"John Doe"}; + + Map params = ParamUtil.INSTANCE.getParams(args, method); + + assertThat(params) + .hasSize(1) + .containsEntry("name", "John Doe"); + } + + @Test + void shouldExtractIntegerParameter() throws NoSuchMethodException { + Method method = TestRepository.class.getMethod("findByAge", int.class); + Object[] args = {30}; + + Map params = ParamUtil.INSTANCE.getParams(args, method); + + assertThat(params) + .hasSize(1) + .containsEntry("age", 30); + } + + @Test + void shouldExtractMultipleParameters() throws NoSuchMethodException { + Method method = TestRepository.class.getMethod("findByNameAndAge", String.class, int.class); + Object[] args = {"Jane Doe", 25}; + + Map params = ParamUtil.INSTANCE.getParams(args, method); + + assertThat(params) + .hasSize(2) + .containsEntry("name", "Jane Doe") + .containsEntry("age", 25); + } + + @Test + void shouldReturnEmptyMapWhenNoParamAnnotationExists() throws NoSuchMethodException { + Method method = TestRepository.class.getMethod("findWithoutParams", String.class); + Object[] args = {"test"}; + + Map params = ParamUtil.INSTANCE.getParams(args, method); + + assertThat(params).isEmpty(); + } + + @Test + void shouldThrowExceptionWhenMethodIsNull() { + Object[] args = {"test"}; + + assertThatThrownBy(() -> ParamUtil.INSTANCE.getParams(args, null)) + .isInstanceOf(IllegalArgumentException.class) + .hasMessage("Arguments and method cannot be null"); + } + + @Test + void shouldThrowExceptionWhenArgsAreNull() throws NoSuchMethodException { + Method method = TestRepository.class.getMethod("findByName", String.class); + + assertThatThrownBy(() -> ParamUtil.INSTANCE.getParams(null, method)) + .isInstanceOf(IllegalArgumentException.class) + .hasMessage("Arguments and method cannot be null"); + } +} \ No newline at end of file From 16be55bd805954192afba82de73314f95fc81f75 Mon Sep 17 00:00:00 2001 From: Otavio Santana Date: Sun, 2 Mar 2025 04:34:53 +0000 Subject: [PATCH 07/39] feat: update param util Signed-off-by: Otavio Santana --- .../jnosql/mapping/driver/ParamUtilTest.java | 20 +------------------ 1 file changed, 1 insertion(+), 19 deletions(-) diff --git a/jnosql-database-commons/src/test/java/org/eclipse/jnosql/mapping/driver/ParamUtilTest.java b/jnosql-database-commons/src/test/java/org/eclipse/jnosql/mapping/driver/ParamUtilTest.java index c2d1ae5db..5b1a414ac 100644 --- a/jnosql-database-commons/src/test/java/org/eclipse/jnosql/mapping/driver/ParamUtilTest.java +++ b/jnosql-database-commons/src/test/java/org/eclipse/jnosql/mapping/driver/ParamUtilTest.java @@ -16,12 +16,11 @@ import jakarta.data.repository.Param; import org.junit.jupiter.api.Test; + import java.lang.reflect.Method; import java.util.Map; -import java.util.Optional; import static org.assertj.core.api.Assertions.assertThat; -import static org.assertj.core.api.Assertions.assertThatThrownBy; class ParamUtilTest { @@ -82,21 +81,4 @@ void shouldReturnEmptyMapWhenNoParamAnnotationExists() throws NoSuchMethodExcept assertThat(params).isEmpty(); } - @Test - void shouldThrowExceptionWhenMethodIsNull() { - Object[] args = {"test"}; - - assertThatThrownBy(() -> ParamUtil.INSTANCE.getParams(args, null)) - .isInstanceOf(IllegalArgumentException.class) - .hasMessage("Arguments and method cannot be null"); - } - - @Test - void shouldThrowExceptionWhenArgsAreNull() throws NoSuchMethodException { - Method method = TestRepository.class.getMethod("findByName", String.class); - - assertThatThrownBy(() -> ParamUtil.INSTANCE.getParams(null, method)) - .isInstanceOf(IllegalArgumentException.class) - .hasMessage("Arguments and method cannot be null"); - } } \ No newline at end of file From b5334215adcb270cfbc8c4b487a18f6620090506 Mon Sep 17 00:00:00 2001 From: Otavio Santana Date: Sun, 2 Mar 2025 04:35:20 +0000 Subject: [PATCH 08/39] feat: update param Signed-off-by: Otavio Santana --- .../databases/arangodb/mapping/Param.java | 31 ------------ .../databases/arangodb/mapping/ParamUtil.java | 48 ------------------- .../ArangoDBDocumentRepositoryProxyTest.java | 2 +- 3 files changed, 1 insertion(+), 80 deletions(-) delete mode 100644 jnosql-arangodb/src/main/java/org/eclipse/jnosql/databases/arangodb/mapping/Param.java delete mode 100644 jnosql-arangodb/src/main/java/org/eclipse/jnosql/databases/arangodb/mapping/ParamUtil.java diff --git a/jnosql-arangodb/src/main/java/org/eclipse/jnosql/databases/arangodb/mapping/Param.java b/jnosql-arangodb/src/main/java/org/eclipse/jnosql/databases/arangodb/mapping/Param.java deleted file mode 100644 index 07fb122d3..000000000 --- a/jnosql-arangodb/src/main/java/org/eclipse/jnosql/databases/arangodb/mapping/Param.java +++ /dev/null @@ -1,31 +0,0 @@ -/* - * Copyright (c) 2022 Contributors to the Eclipse Foundation - * All rights reserved. This program and the accompanying materials - * are made available under the terms of the Eclipse Public License v1.0 - * and Apache License v2.0 which accompanies this distribution. - * The Eclipse Public License is available at http://www.eclipse.org/legal/epl-v10.html - * and the Apache License v2.0 is available at http://www.opensource.org/licenses/apache2.0.php. - * - * You may elect to redistribute this code under either of these licenses. - * - * Contributors: - * - * Otavio Santana - */ -package org.eclipse.jnosql.databases.arangodb.mapping; - -import java.lang.annotation.ElementType; -import java.lang.annotation.Retention; -import java.lang.annotation.RetentionPolicy; -import java.lang.annotation.Target; - - -/** - * Defines a param to a AQL query. - */ -@Retention(RetentionPolicy.RUNTIME) -@Target(ElementType.PARAMETER) -public @interface Param { - - String value(); -} diff --git a/jnosql-arangodb/src/main/java/org/eclipse/jnosql/databases/arangodb/mapping/ParamUtil.java b/jnosql-arangodb/src/main/java/org/eclipse/jnosql/databases/arangodb/mapping/ParamUtil.java deleted file mode 100644 index 7c55e3c8f..000000000 --- a/jnosql-arangodb/src/main/java/org/eclipse/jnosql/databases/arangodb/mapping/ParamUtil.java +++ /dev/null @@ -1,48 +0,0 @@ -/* - * Copyright (c) 2022 Contributors to the Eclipse Foundation - * All rights reserved. This program and the accompanying materials - * are made available under the terms of the Eclipse Public License v1.0 - * and Apache License v2.0 which accompanies this distribution. - * The Eclipse Public License is available at http://www.eclipse.org/legal/epl-v10.html - * and the Apache License v2.0 is available at http://www.opensource.org/licenses/apache2.0.php. - * - * You may elect to redistribute this code under either of these licenses. - * - * Contributors: - * - * Otavio Santana - */ -package org.eclipse.jnosql.databases.arangodb.mapping; - -import java.lang.annotation.Annotation; -import java.lang.reflect.Method; -import java.util.HashMap; -import java.util.Map; -import java.util.Optional; -import java.util.stream.Stream; - -final class ParamUtil { - - private ParamUtil() { - } - - static Map getParams(Object[] args, Method method) { - - Map jsonObject = new HashMap<>(); - Annotation[][] annotations = method.getParameterAnnotations(); - - for (int index = 0; index < annotations.length; index++) { - - final Object arg = args[index]; - - Optional param = Stream.of(annotations[index]) - .filter(Param.class::isInstance) - .map(Param.class::cast) - .findFirst(); - param.ifPresent(p -> jsonObject.put(p.value(), arg)); - - } - - return jsonObject; - } -} diff --git a/jnosql-arangodb/src/test/java/org/eclipse/jnosql/databases/arangodb/mapping/ArangoDBDocumentRepositoryProxyTest.java b/jnosql-arangodb/src/test/java/org/eclipse/jnosql/databases/arangodb/mapping/ArangoDBDocumentRepositoryProxyTest.java index ad84707ed..adb42a04c 100644 --- a/jnosql-arangodb/src/test/java/org/eclipse/jnosql/databases/arangodb/mapping/ArangoDBDocumentRepositoryProxyTest.java +++ b/jnosql-arangodb/src/test/java/org/eclipse/jnosql/databases/arangodb/mapping/ArangoDBDocumentRepositoryProxyTest.java @@ -144,6 +144,6 @@ interface HumanRepository extends ArangoDBRepository { List findAllQuery(); @AQL("FOR p IN Person FILTER p.name = @name RETURN p") - List findByName(@Param("name") String name); + List findByName(String name); } } From 60971ae07f2f5ec0a03081438a45fce436e80755 Mon Sep 17 00:00:00 2001 From: Otavio Santana Date: Sun, 2 Mar 2025 04:36:53 +0000 Subject: [PATCH 09/39] feat: enhance update Signed-off-by: Otavio Santana --- .../arangodb/mapping/ArangoDBDocumentRepositoryProxy.java | 3 ++- .../arangodb/mapping/ArangoDBDocumentRepositoryProxyTest.java | 3 ++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/jnosql-arangodb/src/main/java/org/eclipse/jnosql/databases/arangodb/mapping/ArangoDBDocumentRepositoryProxy.java b/jnosql-arangodb/src/main/java/org/eclipse/jnosql/databases/arangodb/mapping/ArangoDBDocumentRepositoryProxy.java index d0e22a80f..b68ab196d 100644 --- a/jnosql-arangodb/src/main/java/org/eclipse/jnosql/databases/arangodb/mapping/ArangoDBDocumentRepositoryProxy.java +++ b/jnosql-arangodb/src/main/java/org/eclipse/jnosql/databases/arangodb/mapping/ArangoDBDocumentRepositoryProxy.java @@ -19,6 +19,7 @@ import org.eclipse.jnosql.mapping.core.query.AbstractRepository; import org.eclipse.jnosql.mapping.core.repository.DynamicReturn; import org.eclipse.jnosql.mapping.document.DocumentTemplate; +import org.eclipse.jnosql.mapping.driver.ParamUtil; import org.eclipse.jnosql.mapping.metadata.EntitiesMetadata; import org.eclipse.jnosql.mapping.metadata.EntityMetadata; import org.eclipse.jnosql.mapping.semistructured.query.AbstractSemiStructuredRepositoryProxy; @@ -93,7 +94,7 @@ public Object invoke(Object instance, Method method, Object[] args) throws Throw AQL aql = method.getAnnotation(AQL.class); if (Objects.nonNull(aql)) { Stream result; - Map params = ParamUtil.getParams(args, method); + Map params = ParamUtil.INSTANCE.getParams(args, method); if (params.isEmpty()) { result = template.aql(aql.value(), emptyMap()); } else { diff --git a/jnosql-arangodb/src/test/java/org/eclipse/jnosql/databases/arangodb/mapping/ArangoDBDocumentRepositoryProxyTest.java b/jnosql-arangodb/src/test/java/org/eclipse/jnosql/databases/arangodb/mapping/ArangoDBDocumentRepositoryProxyTest.java index adb42a04c..adc6e37f5 100644 --- a/jnosql-arangodb/src/test/java/org/eclipse/jnosql/databases/arangodb/mapping/ArangoDBDocumentRepositoryProxyTest.java +++ b/jnosql-arangodb/src/test/java/org/eclipse/jnosql/databases/arangodb/mapping/ArangoDBDocumentRepositoryProxyTest.java @@ -14,6 +14,7 @@ */ package org.eclipse.jnosql.databases.arangodb.mapping; +import jakarta.data.repository.Param; import jakarta.inject.Inject; import org.assertj.core.api.Assertions; import org.eclipse.jnosql.mapping.core.Converters; @@ -144,6 +145,6 @@ interface HumanRepository extends ArangoDBRepository { List findAllQuery(); @AQL("FOR p IN Person FILTER p.name = @name RETURN p") - List findByName(String name); + List findByName(@Param("name") String name); } } From 8ed0f7ba589fa60342963e20b5a4d272792f8246 Mon Sep 17 00:00:00 2001 From: Otavio Santana Date: Sun, 2 Mar 2025 04:39:01 +0000 Subject: [PATCH 10/39] docs: update cassandra template Signed-off-by: Otavio Santana --- .../cassandra/mapping/CassandraTemplate.java | 128 +++++++++--------- 1 file changed, 64 insertions(+), 64 deletions(-) diff --git a/jnosql-cassandra/src/main/java/org/eclipse/jnosql/databases/cassandra/mapping/CassandraTemplate.java b/jnosql-cassandra/src/main/java/org/eclipse/jnosql/databases/cassandra/mapping/CassandraTemplate.java index 44160bd82..8b3070649 100644 --- a/jnosql-cassandra/src/main/java/org/eclipse/jnosql/databases/cassandra/mapping/CassandraTemplate.java +++ b/jnosql-cassandra/src/main/java/org/eclipse/jnosql/databases/cassandra/mapping/CassandraTemplate.java @@ -27,120 +27,120 @@ import java.util.stream.Stream; /** - * A Cassandra extension of {@link ColumnTemplate} + * A Cassandra-specific extension of {@link ColumnTemplate}, providing additional functionality for interacting + * with a Cassandra database using CQL queries and different consistency levels. */ public interface CassandraTemplate extends ColumnTemplate { /** - * Saves a ColumnEntity with a defined ConsistencyLevel + * Saves an entity with a specified {@link ConsistencyLevel}. * - * @param type - * @param entity the entity - * @param level the {@link ConsistencyLevel} - * @return the entity saved - * @throws NullPointerException when both entity or level are null + * @param the type of the entity + * @param entity the entity to be saved + * @param level the desired {@link ConsistencyLevel} for the operation + * @return the saved entity + * @throws NullPointerException if either {@code entity} or {@code level} is {@code null} */ - T save(T entity, ConsistencyLevel level); - /** - * Saves an entity using {@link ConsistencyLevel} + * Saves multiple entities with a specified {@link ConsistencyLevel} and a time-to-live (TTL) duration. * - * @param type - * @param entities the entities - * @param ttl the ttl - * @param level the level - * @return the entity saved - * @throws NullPointerException when either entity or ttl or level are null + * @param the type of the entities + * @param entities the iterable collection of entities to be saved + * @param ttl the time-to-live duration for the records + * @param level the desired {@link ConsistencyLevel} for the operation + * @return an iterable containing the saved entities + * @throws NullPointerException if {@code entities}, {@code ttl}, or {@code level} is {@code null} */ Iterable save(Iterable entities, Duration ttl, ConsistencyLevel level); /** - * Saves a ColumnEntity with a defined ConsistencyLevel + * Saves multiple entities with a specified {@link ConsistencyLevel}. * - * @param type - * @param entities the entities - * @param level the {@link ConsistencyLevel} - * @return the entity saved - * @throws NullPointerException when both entity or level are null + * @param the type of the entities + * @param entities the iterable collection of entities to be saved + * @param level the desired {@link ConsistencyLevel} for the operation + * @return an iterable containing the saved entities + * @throws NullPointerException if {@code entities} or {@code level} is {@code null} */ - Iterable save(Iterable entities, ConsistencyLevel level); - /** - * Saves an entity using {@link ConsistencyLevel} + * Saves an entity with a specified {@link ConsistencyLevel} and a time-to-live (TTL) duration. * - * @param type - * @param entity the entity - * @param ttl the ttl - * @param level the level - * @return the entity saved - * @throws NullPointerException when either entity or ttl or level are null + * @param the type of the entity + * @param entity the entity to be saved + * @param ttl the time-to-live duration for the record + * @param level the desired {@link ConsistencyLevel} for the operation + * @return the saved entity + * @throws NullPointerException if {@code entity}, {@code ttl}, or {@code level} is {@code null} */ T save(T entity, Duration ttl, ConsistencyLevel level); - /** - * Deletes an information using {@link ConsistencyLevel} + * Deletes records based on a {@link DeleteQuery} with a specified {@link ConsistencyLevel}. * - * @param query the query - * @param level the level - * @throws NullPointerException when either query or level are null + * @param query the delete query defining the criteria for deletion + * @param level the desired {@link ConsistencyLevel} for the operation + * @throws NullPointerException if either {@code query} or {@code level} is {@code null} */ void delete(DeleteQuery query, ConsistencyLevel level); /** - * Finds using a consistency level + * Executes a {@link SelectQuery} using a specified {@link ConsistencyLevel} and retrieves the matching records. * - * @param type - * @param query the query - * @param level the consistency level - * @return the query using a consistency level + * @param the type of the result + * @param query the select query defining the criteria for data retrieval + * @param level the desired {@link ConsistencyLevel} for the operation + * @return a stream of results matching the query criteria */ Stream find(SelectQuery query, ConsistencyLevel level); /** - * Executes CQL + * Executes a raw CQL query. * - * @param type - * @param query the Cassandra query language - * @return the result of this query - * @throws NullPointerException when query is null + * @param the type of the result + * @param query the CQL query to be executed + * @return a stream containing the results of the query + * @throws NullPointerException if {@code query} is {@code null} */ Stream cql(String query); /** - * Executes CQL using the provided named values. - * E.g.: "SELECT * FROM users WHERE id = :i", Map.<String, Object>of("i", 1)" + * Executes a CQL query with named parameters. + *

+ * Example usage: + * 

{@code
+     * template.cql("SELECT * FROM users WHERE id = :id", Map.of("id", 1));
+     * }
* - * @param type - * @param query the Cassandra query language - * @param values values required for the execution of {@code query} - * @return the result of this query - * @throws NullPointerException when query is null + * @param the type of the result + * @param query the CQL query with named placeholders + * @param values a map of parameter names to values + * @return a stream containing the results of the query + * @throws NullPointerException if {@code query} is {@code null} */ Stream cql(String query, Map values); /** - * Executes CQL + * Executes a CQL query with positional parameters. * - * @param type - * @param query the Cassandra query language - * @param params the params - * @return the result of this query - * @throws NullPointerException when query is null + * @param the type of the result + * @param query the CQL query with positional placeholders + * @param params the values to be bound to the query placeholders + * @return a stream containing the results of the query + * @throws NullPointerException if {@code query} is {@code null} */ Stream cql(String query, Object... params); /** - * Executes a statement + * Executes a {@link SimpleStatement} in Cassandra. * - * @param type - * @param statement the statement - * @return the result of this query - * @throws NullPointerException when statement is null + * @param the type of the result + * @param statement the prepared {@link SimpleStatement} to be executed + * @return a stream containing the results of the query + * @throws NullPointerException if {@code statement} is {@code null} */ Stream execute(SimpleStatement statement); From 9105641740b6a264e4acbfd132ad5ee0d61ab0e5 Mon Sep 17 00:00:00 2001 From: Otavio Santana Date: Sun, 2 Mar 2025 04:40:54 +0000 Subject: [PATCH 11/39] docs: enhance CQl documentation Signed-off-by: Otavio Santana --- .../jnosql/databases/cassandra/mapping/CQL.java | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/jnosql-cassandra/src/main/java/org/eclipse/jnosql/databases/cassandra/mapping/CQL.java b/jnosql-cassandra/src/main/java/org/eclipse/jnosql/databases/cassandra/mapping/CQL.java index c068ae01d..c37eb3065 100644 --- a/jnosql-cassandra/src/main/java/org/eclipse/jnosql/databases/cassandra/mapping/CQL.java +++ b/jnosql-cassandra/src/main/java/org/eclipse/jnosql/databases/cassandra/mapping/CQL.java @@ -20,14 +20,25 @@ import java.lang.annotation.Target; /** - * Annotation used to define a dynamic CQL query method in CassandraRepository and CassandraRepositoryAsync interfaces. + * Annotation used to define a dynamic CQL query method in {@link CassandraRepository}. + *

+ * Methods annotated with {@code @CQL} allow the execution of custom Cassandra Query Language (CQL) statements + * within repository interfaces. + *

+ *

+ * Example usage: + * 

{@code
+ * @CQL("SELECT * FROM users WHERE username = :username")
+ * List findByUsername(@Param("username") String username);
+ * }
+ *

*/ @Retention(RetentionPolicy.RUNTIME) @Target(ElementType.METHOD) public @interface CQL { /** - * The CQL query string. + * The CQL query string to be executed. * * @return the CQL query string */ From 4dab2e5f3c1d847c58fbce776f2c44575e6da9b5 Mon Sep 17 00:00:00 2001 From: Otavio Santana Date: Sun, 2 Mar 2025 04:42:23 +0000 Subject: [PATCH 12/39] docs: enhance documentaition Signed-off-by: Otavio Santana --- .../mapping/CassandraRepository.java | 19 +++++++++++++++++-- 1 file changed, 17 insertions(+), 2 deletions(-) diff --git a/jnosql-cassandra/src/main/java/org/eclipse/jnosql/databases/cassandra/mapping/CassandraRepository.java b/jnosql-cassandra/src/main/java/org/eclipse/jnosql/databases/cassandra/mapping/CassandraRepository.java index 3f6e49a19..4cea606e5 100644 --- a/jnosql-cassandra/src/main/java/org/eclipse/jnosql/databases/cassandra/mapping/CassandraRepository.java +++ b/jnosql-cassandra/src/main/java/org/eclipse/jnosql/databases/cassandra/mapping/CassandraRepository.java @@ -18,10 +18,25 @@ import org.eclipse.jnosql.mapping.NoSQLRepository; /** - * The Cassandra {@link NoSQLRepository} + * A Cassandra-specific extension of {@link NoSQLRepository}, providing repository-style data access. + * This interface extends the generic {@link NoSQLRepository}, allowing seamless integration with Cassandra's + * schema-less NoSQL database model while leveraging query capabilities provided by {@link CQL}. + * + *

Example usage:

+ * 
{@code
+ * @Repository
+ * public interface UserRepository extends CassandraRepository {
+ *
+ *     @CQL("SELECT * FROM users WHERE username = :username")
+ *     List findByUsername(@Param("username") String username);
+ *
+ *     @CQL("DELETE FROM users WHERE id = :id")
+ *     void deleteById(@Param("id") String id);
+ * }
+ * }
* * @param the entity type - * @param the id entity type + * @param the primary key type of the entity */ public interface CassandraRepository extends NoSQLRepository { From 32e23caa15b16c95b11268f9a804d102883b4767 Mon Sep 17 00:00:00 2001 From: Otavio Santana Date: Sun, 2 Mar 2025 04:45:27 +0000 Subject: [PATCH 13/39] feat: update cassandra documentation Signed-off-by: Otavio Santana --- .../cassandra/mapping/CQLObjectUtil.java | 48 ------------------- .../mapping/CassandraRepositoryProxy.java | 3 +- .../databases/cassandra/mapping/Param.java | 37 -------------- .../mapping/CassandraRepositoryProxyTest.java | 1 + 4 files changed, 3 insertions(+), 86 deletions(-) delete mode 100644 jnosql-cassandra/src/main/java/org/eclipse/jnosql/databases/cassandra/mapping/CQLObjectUtil.java delete mode 100644 jnosql-cassandra/src/main/java/org/eclipse/jnosql/databases/cassandra/mapping/Param.java diff --git a/jnosql-cassandra/src/main/java/org/eclipse/jnosql/databases/cassandra/mapping/CQLObjectUtil.java b/jnosql-cassandra/src/main/java/org/eclipse/jnosql/databases/cassandra/mapping/CQLObjectUtil.java deleted file mode 100644 index 4818d02aa..000000000 --- a/jnosql-cassandra/src/main/java/org/eclipse/jnosql/databases/cassandra/mapping/CQLObjectUtil.java +++ /dev/null @@ -1,48 +0,0 @@ -/* - * Copyright (c) 2022 Contributors to the Eclipse Foundation - * All rights reserved. This program and the accompanying materials - * are made available under the terms of the Eclipse Public License v1.0 - * and Apache License v2.0 which accompanies this distribution. - * The Eclipse Public License is available at http://www.eclipse.org/legal/epl-v10.html - * and the Apache License v2.0 is available at http://www.opensource.org/licenses/apache2.0.php. - * - * You may elect to redistribute this code under either of these licenses. - * - * Contributors: - * - * Otavio Santana - */ -package org.eclipse.jnosql.databases.cassandra.mapping; - -import java.lang.annotation.Annotation; -import java.lang.reflect.Method; -import java.util.HashMap; -import java.util.Map; -import java.util.Optional; -import java.util.stream.Stream; - -final class CQLObjectUtil { - - private CQLObjectUtil() { - } - - static Map getValues(Object[] args, Method method) { - - Map map = new HashMap<>(); - Annotation[][] annotations = method.getParameterAnnotations(); - - for (int index = 0; index < annotations.length; index++) { - - final Object arg = args[index]; - - Optional param = Stream.of(annotations[index]) - .filter(Param.class::isInstance) - .map(Param.class::cast) - .findFirst(); - param.ifPresent(p -> map.put(p.value(), arg)); - - } - - return map; - } -} diff --git a/jnosql-cassandra/src/main/java/org/eclipse/jnosql/databases/cassandra/mapping/CassandraRepositoryProxy.java b/jnosql-cassandra/src/main/java/org/eclipse/jnosql/databases/cassandra/mapping/CassandraRepositoryProxy.java index f9b58f3f2..6bba34896 100644 --- a/jnosql-cassandra/src/main/java/org/eclipse/jnosql/databases/cassandra/mapping/CassandraRepositoryProxy.java +++ b/jnosql-cassandra/src/main/java/org/eclipse/jnosql/databases/cassandra/mapping/CassandraRepositoryProxy.java @@ -19,6 +19,7 @@ import org.eclipse.jnosql.mapping.core.Converters; import org.eclipse.jnosql.mapping.core.query.AbstractRepository; import org.eclipse.jnosql.mapping.core.repository.DynamicReturn; +import org.eclipse.jnosql.mapping.driver.ParamUtil; import org.eclipse.jnosql.mapping.metadata.EntitiesMetadata; import org.eclipse.jnosql.mapping.metadata.EntityMetadata; import org.eclipse.jnosql.mapping.semistructured.query.AbstractSemiStructuredRepositoryProxy; @@ -91,7 +92,7 @@ public Object invoke(Object instance, Method method, Object[] args) throws Throw if (Objects.nonNull(cql)) { Stream result; - Map values = CQLObjectUtil.getValues(args, method); + Map values = ParamUtil.INSTANCE.getParams(args, method); if (!values.isEmpty()) { result = template.cql(cql.value(), values); } else if (args == null || args.length == 0) { diff --git a/jnosql-cassandra/src/main/java/org/eclipse/jnosql/databases/cassandra/mapping/Param.java b/jnosql-cassandra/src/main/java/org/eclipse/jnosql/databases/cassandra/mapping/Param.java deleted file mode 100644 index 2ca2ed34b..000000000 --- a/jnosql-cassandra/src/main/java/org/eclipse/jnosql/databases/cassandra/mapping/Param.java +++ /dev/null @@ -1,37 +0,0 @@ -/* - * Copyright (c) 2022 Contributors to the Eclipse Foundation - * All rights reserved. This program and the accompanying materials - * are made available under the terms of the Eclipse Public License v1.0 - * and Apache License v2.0 which accompanies this distribution. - * The Eclipse Public License is available at http://www.eclipse.org/legal/epl-v10.html - * and the Apache License v2.0 is available at http://www.opensource.org/licenses/apache2.0.php. - * - * You may elect to redistribute this code under either of these licenses. - * - * Contributors: - * - * Otavio Santana - */ -package org.eclipse.jnosql.databases.cassandra.mapping; - -import java.lang.annotation.ElementType; -import java.lang.annotation.Retention; -import java.lang.annotation.RetentionPolicy; -import java.lang.annotation.Target; - - -/** - * An annotation used to define a parameter in a CQL query. - * This annotation is used to specify the name of the parameter. - */ -@Retention(RetentionPolicy.RUNTIME) -@Target(ElementType.PARAMETER) -public @interface Param { - - /** - * Specifies the name of the parameter. - * - * @return the name of the parameter - */ - String value(); -} \ No newline at end of file diff --git a/jnosql-cassandra/src/test/java/org/eclipse/jnosql/databases/cassandra/mapping/CassandraRepositoryProxyTest.java b/jnosql-cassandra/src/test/java/org/eclipse/jnosql/databases/cassandra/mapping/CassandraRepositoryProxyTest.java index 1e4c8f4fd..0b1ddeb5c 100644 --- a/jnosql-cassandra/src/test/java/org/eclipse/jnosql/databases/cassandra/mapping/CassandraRepositoryProxyTest.java +++ b/jnosql-cassandra/src/test/java/org/eclipse/jnosql/databases/cassandra/mapping/CassandraRepositoryProxyTest.java @@ -14,6 +14,7 @@ */ package org.eclipse.jnosql.databases.cassandra.mapping; +import jakarta.data.repository.Param; import jakarta.inject.Inject; import org.eclipse.jnosql.communication.semistructured.DeleteQuery; import org.eclipse.jnosql.mapping.column.ColumnTemplate; From 08bd462a20277677ac6c1460fcf3a7574b6fcc24 Mon Sep 17 00:00:00 2001 From: Otavio Santana Date: Sun, 2 Mar 2025 04:47:33 +0000 Subject: [PATCH 14/39] docs: enhance couchbase template Signed-off-by: Otavio Santana --- .../couchbase/mapping/CouchbaseTemplate.java | 48 ++++++++++++++----- 1 file changed, 37 insertions(+), 11 deletions(-) diff --git a/jnosql-couchbase/src/main/java/org/eclipse/jnosql/databases/couchbase/mapping/CouchbaseTemplate.java b/jnosql-couchbase/src/main/java/org/eclipse/jnosql/databases/couchbase/mapping/CouchbaseTemplate.java index 157c7986b..9e2df226b 100644 --- a/jnosql-couchbase/src/main/java/org/eclipse/jnosql/databases/couchbase/mapping/CouchbaseTemplate.java +++ b/jnosql-couchbase/src/main/java/org/eclipse/jnosql/databases/couchbase/mapping/CouchbaseTemplate.java @@ -21,28 +21,54 @@ import java.util.stream.Stream; /** - * A {@link DocumentTemplate} to couchbase + * A Couchbase-specific extension of {@link DocumentTemplate} that enables querying using N1QL. + *

+ * This interface provides methods to execute Couchbase's N1QL queries, allowing dynamic parameterized + * queries and plain queries. + *

+ * + * Example Usage + * 
{@code
+ * @Inject
+ * private CouchbaseTemplate template;
+ *
+ * // Query with named parameters
+ * JsonObject params = JsonObject.create().put("status", "active");
+ * Stream activeUsers = template.n1qlQuery("SELECT * FROM users WHERE status = $status", params);
+ *
+ * // Plain query execution
+ * Stream allUsers = template.n1qlQuery("SELECT * FROM users");
+ * }
*/ public interface CouchbaseTemplate extends DocumentTemplate { /** - * Executes the n1qlquery with params and then result que result + * Executes an N1QL query with named parameters and returns the query result. + *

+ * Example query: + * {@code SELECT * FROM users WHERE status = $status} + *

* - * @param n1qlQuery the query - * @param params the params - * @return the query result - * @throws NullPointerException when either n1qlQuery or params are null + * @param the entity type + * @param n1qlQuery the N1QL query to execute + * @param params the parameters for the query + * @return a {@link Stream} of entities representing the query result + * @throws NullPointerException if either {@code n1qlQuery} or {@code params} is null */ Stream n1qlQuery(String n1qlQuery, JsonObject params); - /** - * Executes the n1ql plain query and then result que result + * Executes a plain N1QL query without parameters and returns the query result. + *

+ * Example query: + * {@code SELECT * FROM users} + *

* - * @param n1qlQuery the query - * @return the query result - * @throws NullPointerException when either n1qlQuery or params are null + * @param the entity type + * @param n1qlQuery the N1QL query to execute + * @return a {@link Stream} of entities representing the query result + * @throws NullPointerException if {@code n1qlQuery} is null */ Stream n1qlQuery(String n1qlQuery); From 165c4c3d4eaaf6712deb97d6b96ffb688d67cde0 Mon Sep 17 00:00:00 2001 From: Otavio Santana Date: Sun, 2 Mar 2025 04:49:08 +0000 Subject: [PATCH 15/39] docs: enhance n1ql documentation Signed-off-by: Otavio Santana --- .../databases/couchbase/mapping/N1QL.java | 23 +++++++++++++++++-- 1 file changed, 21 insertions(+), 2 deletions(-) diff --git a/jnosql-couchbase/src/main/java/org/eclipse/jnosql/databases/couchbase/mapping/N1QL.java b/jnosql-couchbase/src/main/java/org/eclipse/jnosql/databases/couchbase/mapping/N1QL.java index 2f25e5cbc..56c5d6d6e 100644 --- a/jnosql-couchbase/src/main/java/org/eclipse/jnosql/databases/couchbase/mapping/N1QL.java +++ b/jnosql-couchbase/src/main/java/org/eclipse/jnosql/databases/couchbase/mapping/N1QL.java @@ -19,12 +19,31 @@ import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; + /** - * To a dynamic query on CouchbaseRepository and CouchbaseRepositoryAsync interfaces. + * Annotation used to define a dynamic N1QL query in {@link CouchbaseRepository}. + *

+ * This annotation allows repository methods to be mapped to Couchbase N1QL queries. + * Parameters can be provided using the {@link Param} annotation. + *

+ * + *

Example Usage

+ * 
{@code
+ * @Repository
+ * interface ProductRepository extends CouchbaseRepository {
+ *
+ *     @N1QL("SELECT * FROM products WHERE category = $category")
+ *     List findByCategory(@Param("category") String category);
+ * }
+ * }
*/ @Retention(RetentionPolicy.RUNTIME) @Target(ElementType.METHOD) public @interface N1QL { - + /** + * The N1QL query string to be executed. + * + * @return the N1QL query + */ String value(); } From d0dbace1b81f03c291342b9eaca1be24c48e2b20 Mon Sep 17 00:00:00 2001 From: Otavio Santana Date: Sun, 2 Mar 2025 04:49:17 +0000 Subject: [PATCH 16/39] docs: create couchbase repository Signed-off-by: Otavio Santana --- .../mapping/CouchbaseRepository.java | 22 +++++++++++++++++-- 1 file changed, 20 insertions(+), 2 deletions(-) diff --git a/jnosql-couchbase/src/main/java/org/eclipse/jnosql/databases/couchbase/mapping/CouchbaseRepository.java b/jnosql-couchbase/src/main/java/org/eclipse/jnosql/databases/couchbase/mapping/CouchbaseRepository.java index a9f7c7b4f..637f2bd24 100644 --- a/jnosql-couchbase/src/main/java/org/eclipse/jnosql/databases/couchbase/mapping/CouchbaseRepository.java +++ b/jnosql-couchbase/src/main/java/org/eclipse/jnosql/databases/couchbase/mapping/CouchbaseRepository.java @@ -18,9 +18,27 @@ import org.eclipse.jnosql.mapping.NoSQLRepository; /** - * The couchbase {@link NoSQLRepository} + * A Couchbase-specific extension of {@link NoSQLRepository}. + *

+ * This repository interface provides built-in CRUD operations and supports dynamic queries + * using the {@link N1QL} annotation for executing Couchbase N1QL queries. + *

+ * + *

Example Usage

+ * 
{@code
+ * @Repository
+ * interface UserRepository extends CouchbaseRepository {
+ *
+ *     @N1QL("SELECT * FROM users WHERE name = $name")
+ *     List findByName(@Param("name") String name);
+ *
+ *     @N1QL("SELECT * FROM users WHERE age > $age")
+ *     List findByAgeGreaterThan(@Param("age") int age);
+ * }
+ * }
+ * * @param the entity type - * @param the entity id type + * @param the entity ID type */ public interface CouchbaseRepository extends NoSQLRepository { } From 6d554ea69676962937ec6bb54c1ea9e2060ee27c Mon Sep 17 00:00:00 2001 From: Otavio Santana Date: Sun, 2 Mar 2025 04:49:52 +0000 Subject: [PATCH 17/39] feat: update param Signed-off-by: Otavio Santana --- .../couchbase/mapping/JsonObjectUtil.java | 49 ------------------- .../databases/couchbase/mapping/N1QL.java | 2 +- .../databases/couchbase/mapping/Param.java | 31 ------------ .../CouchbaseDocumentRepositoryProxyTest.java | 2 +- 4 files changed, 2 insertions(+), 82 deletions(-) delete mode 100644 jnosql-couchbase/src/main/java/org/eclipse/jnosql/databases/couchbase/mapping/JsonObjectUtil.java delete mode 100644 jnosql-couchbase/src/main/java/org/eclipse/jnosql/databases/couchbase/mapping/Param.java diff --git a/jnosql-couchbase/src/main/java/org/eclipse/jnosql/databases/couchbase/mapping/JsonObjectUtil.java b/jnosql-couchbase/src/main/java/org/eclipse/jnosql/databases/couchbase/mapping/JsonObjectUtil.java deleted file mode 100644 index 6c5e2981a..000000000 --- a/jnosql-couchbase/src/main/java/org/eclipse/jnosql/databases/couchbase/mapping/JsonObjectUtil.java +++ /dev/null @@ -1,49 +0,0 @@ -/* - * Copyright (c) 2022 Contributors to the Eclipse Foundation - * All rights reserved. This program and the accompanying materials - * are made available under the terms of the Eclipse Public License v1.0 - * and Apache License v2.0 which accompanies this distribution. - * The Eclipse Public License is available at http://www.eclipse.org/legal/epl-v10.html - * and the Apache License v2.0 is available at http://www.opensource.org/licenses/apache2.0.php. - * - * You may elect to redistribute this code under either of these licenses. - * - * Contributors: - * - * Otavio Santana - */ -package org.eclipse.jnosql.databases.couchbase.mapping; - - -import com.couchbase.client.java.json.JsonObject; - -import java.lang.annotation.Annotation; -import java.lang.reflect.Method; -import java.util.Optional; -import java.util.stream.Stream; - -final class JsonObjectUtil { - - private JsonObjectUtil() { - } - - static JsonObject getParams(Object[] args, Method method) { - - JsonObject jsonObject = JsonObject.create(); - Annotation[][] annotations = method.getParameterAnnotations(); - - for (int index = 0; index < annotations.length; index++) { - - final Object arg = args[index]; - - Optional param = Stream.of(annotations[index]) - .filter(Param.class::isInstance) - .map(Param.class::cast) - .findFirst(); - param.ifPresent(p -> jsonObject.put(p.value(), arg)); - - } - - return jsonObject; - } -} diff --git a/jnosql-couchbase/src/main/java/org/eclipse/jnosql/databases/couchbase/mapping/N1QL.java b/jnosql-couchbase/src/main/java/org/eclipse/jnosql/databases/couchbase/mapping/N1QL.java index 56c5d6d6e..d623d0339 100644 --- a/jnosql-couchbase/src/main/java/org/eclipse/jnosql/databases/couchbase/mapping/N1QL.java +++ b/jnosql-couchbase/src/main/java/org/eclipse/jnosql/databases/couchbase/mapping/N1QL.java @@ -24,7 +24,7 @@ * Annotation used to define a dynamic N1QL query in {@link CouchbaseRepository}. *

* This annotation allows repository methods to be mapped to Couchbase N1QL queries. - * Parameters can be provided using the {@link Param} annotation. + * Parameters can be provided using the {@link jakarta.data.repository.Param} annotation. *

* *

Example Usage

diff --git a/jnosql-couchbase/src/main/java/org/eclipse/jnosql/databases/couchbase/mapping/Param.java b/jnosql-couchbase/src/main/java/org/eclipse/jnosql/databases/couchbase/mapping/Param.java deleted file mode 100644 index c676c87e0..000000000 --- a/jnosql-couchbase/src/main/java/org/eclipse/jnosql/databases/couchbase/mapping/Param.java +++ /dev/null @@ -1,31 +0,0 @@ -/* - * Copyright (c) 2022 Contributors to the Eclipse Foundation - * All rights reserved. This program and the accompanying materials - * are made available under the terms of the Eclipse Public License v1.0 - * and Apache License v2.0 which accompanies this distribution. - * The Eclipse Public License is available at http://www.eclipse.org/legal/epl-v10.html - * and the Apache License v2.0 is available at http://www.opensource.org/licenses/apache2.0.php. - * - * You may elect to redistribute this code under either of these licenses. - * - * Contributors: - * - * Otavio Santana - */ -package org.eclipse.jnosql.databases.couchbase.mapping; - -import java.lang.annotation.ElementType; -import java.lang.annotation.Retention; -import java.lang.annotation.RetentionPolicy; -import java.lang.annotation.Target; - - -/** - * Defines a param to a N1QL query. - */ -@Retention(RetentionPolicy.RUNTIME) -@Target(ElementType.PARAMETER) -public @interface Param { - - String value(); -} diff --git a/jnosql-couchbase/src/test/java/org/eclipse/jnosql/databases/couchbase/mapping/CouchbaseDocumentRepositoryProxyTest.java b/jnosql-couchbase/src/test/java/org/eclipse/jnosql/databases/couchbase/mapping/CouchbaseDocumentRepositoryProxyTest.java index b1f74e4bc..6860266e3 100644 --- a/jnosql-couchbase/src/test/java/org/eclipse/jnosql/databases/couchbase/mapping/CouchbaseDocumentRepositoryProxyTest.java +++ b/jnosql-couchbase/src/test/java/org/eclipse/jnosql/databases/couchbase/mapping/CouchbaseDocumentRepositoryProxyTest.java @@ -133,6 +133,6 @@ interface HumanRepository extends CouchbaseRepository { List findAllQuery(); @N1QL("select * from Person where name = $name") - List findByName(@Param("name") String name); + List findByName(String name); } } \ No newline at end of file From b25cdcf6a3ff32ade8d1954a6085221bf72f5607 Mon Sep 17 00:00:00 2001 From: Otavio Santana Date: Sun, 2 Mar 2025 04:51:28 +0000 Subject: [PATCH 18/39] feat: update param Signed-off-by: Otavio Santana --- .../couchbase/mapping/JsonObjectUtil.java | 50 +++++++++++++++++++ .../CouchbaseDocumentRepositoryProxyTest.java | 3 +- 2 files changed, 52 insertions(+), 1 deletion(-) create mode 100644 jnosql-couchbase/src/main/java/org/eclipse/jnosql/databases/couchbase/mapping/JsonObjectUtil.java diff --git a/jnosql-couchbase/src/main/java/org/eclipse/jnosql/databases/couchbase/mapping/JsonObjectUtil.java b/jnosql-couchbase/src/main/java/org/eclipse/jnosql/databases/couchbase/mapping/JsonObjectUtil.java new file mode 100644 index 000000000..156e61ea3 --- /dev/null +++ b/jnosql-couchbase/src/main/java/org/eclipse/jnosql/databases/couchbase/mapping/JsonObjectUtil.java @@ -0,0 +1,50 @@ +/* + * Copyright (c) 2022 Contributors to the Eclipse Foundation + * All rights reserved. This program and the accompanying materials + * are made available under the terms of the Eclipse Public License v1.0 + * and Apache License v2.0 which accompanies this distribution. + * The Eclipse Public License is available at http://www.eclipse.org/legal/epl-v10.html + * and the Apache License v2.0 is available at http://www.opensource.org/licenses/apache2.0.php. + * + * You may elect to redistribute this code under either of these licenses. + * + * Contributors: + * + * Otavio Santana + */ +package org.eclipse.jnosql.databases.couchbase.mapping; + + +import com.couchbase.client.java.json.JsonObject; +import jakarta.data.repository.Param; + +import java.lang.annotation.Annotation; +import java.lang.reflect.Method; +import java.util.Optional; +import java.util.stream.Stream; + +final class JsonObjectUtil { + + private JsonObjectUtil() { + } + + static JsonObject getParams(Object[] args, Method method) { + + JsonObject jsonObject = JsonObject.create(); + Annotation[][] annotations = method.getParameterAnnotations(); + + for (int index = 0; index < annotations.length; index++) { + + final Object arg = args[index]; + + Optional param = Stream.of(annotations[index]) + .filter(Param.class::isInstance) + .map(Param.class::cast) + .findFirst(); + param.ifPresent(p -> jsonObject.put(p.value(), arg)); + + } + + return jsonObject; + } +} diff --git a/jnosql-couchbase/src/test/java/org/eclipse/jnosql/databases/couchbase/mapping/CouchbaseDocumentRepositoryProxyTest.java b/jnosql-couchbase/src/test/java/org/eclipse/jnosql/databases/couchbase/mapping/CouchbaseDocumentRepositoryProxyTest.java index 6860266e3..b9a25bc1e 100644 --- a/jnosql-couchbase/src/test/java/org/eclipse/jnosql/databases/couchbase/mapping/CouchbaseDocumentRepositoryProxyTest.java +++ b/jnosql-couchbase/src/test/java/org/eclipse/jnosql/databases/couchbase/mapping/CouchbaseDocumentRepositoryProxyTest.java @@ -15,6 +15,7 @@ package org.eclipse.jnosql.databases.couchbase.mapping; import com.couchbase.client.java.json.JsonObject; +import jakarta.data.repository.Param; import jakarta.inject.Inject; import org.eclipse.jnosql.mapping.core.Converters; import org.eclipse.jnosql.mapping.core.spi.EntityMetadataExtension; @@ -133,6 +134,6 @@ interface HumanRepository extends CouchbaseRepository { List findAllQuery(); @N1QL("select * from Person where name = $name") - List findByName(String name); + List findByName(@Param("name") String name); } } \ No newline at end of file From 93b9ff8f5c01ac705525fc18adb3b0184abc1e37 Mon Sep 17 00:00:00 2001 From: Otavio Santana Date: Sun, 2 Mar 2025 04:54:03 +0000 Subject: [PATCH 19/39] docs: generate documentation at Couchdbmanager Signed-off-by: Otavio Santana --- .../communication/CouchDBDocumentManager.java | 26 ++++++++++++++++--- 1 file changed, 22 insertions(+), 4 deletions(-) diff --git a/jnosql-couchdb/src/main/java/org/eclipse/jnosql/databases/couchdb/communication/CouchDBDocumentManager.java b/jnosql-couchdb/src/main/java/org/eclipse/jnosql/databases/couchdb/communication/CouchDBDocumentManager.java index 4ca32a779..84d9ef20f 100644 --- a/jnosql-couchdb/src/main/java/org/eclipse/jnosql/databases/couchdb/communication/CouchDBDocumentManager.java +++ b/jnosql-couchdb/src/main/java/org/eclipse/jnosql/databases/couchdb/communication/CouchDBDocumentManager.java @@ -19,15 +19,33 @@ import org.eclipse.jnosql.communication.semistructured.DatabaseManager; /** - * A couchdb extension where it does provide a {@link CouchDBDocumentManager#count()} feature. + * A CouchDB-specific extension of {@link DatabaseManager} that provides an additional + * feature to count the number of documents in the database. + *

+ * This interface offers a {@code count()} method to retrieve the total number of documents + * stored in the CouchDB database. It extends the {@link DatabaseManager} to align with + * Eclipse JNoSQL's database management abstraction. + *

+ * + * Example Usage: + * 
{@code
+ * @Inject
+ * private CouchDBDocumentManager documentManager;
+ *
+ * long totalDocuments = documentManager.count();
+ * }
+ * + * @see DatabaseManager */ public interface CouchDBDocumentManager extends DatabaseManager { /** - * Returns the number of elements of database + * Retrieves the total number of documents in the database. + * Note: Not all CouchDB implementations support this feature. If the operation is not + * supported, an {@link UnsupportedOperationException} will be thrown. * - * @return the number of elements - * @throws UnsupportedOperationException when the database dot not have support + * @return the total number of documents in the database + * @throws UnsupportedOperationException if the database does not support counting documents */ long count(); } From 31cbfe4c6ebb60ae4ef75c0d9e969c97ca6fbd68 Mon Sep 17 00:00:00 2001 From: Otavio Santana Date: Sun, 2 Mar 2025 04:55:32 +0000 Subject: [PATCH 20/39] docs: geneate ES template Signed-off-by: Otavio Santana --- .../mapping/ElasticsearchTemplate.java | 36 ++++++++++++++++--- 1 file changed, 31 insertions(+), 5 deletions(-) diff --git a/jnosql-elasticsearch/src/main/java/org/eclipse/jnosql/databases/elasticsearch/mapping/ElasticsearchTemplate.java b/jnosql-elasticsearch/src/main/java/org/eclipse/jnosql/databases/elasticsearch/mapping/ElasticsearchTemplate.java index a1dd6496e..7b080a964 100644 --- a/jnosql-elasticsearch/src/main/java/org/eclipse/jnosql/databases/elasticsearch/mapping/ElasticsearchTemplate.java +++ b/jnosql-elasticsearch/src/main/java/org/eclipse/jnosql/databases/elasticsearch/mapping/ElasticsearchTemplate.java @@ -21,16 +21,42 @@ import java.util.stream.Stream; /** - * A {@link DocumentTemplate} to elasticsearch + * An Elasticsearch-specific extension of {@link DocumentTemplate}, + * providing a method to perform search queries using {@link SearchRequest}. + * + * This template allows executing Elasticsearch queries and retrieving results + * as a stream of entities mapped by Eclipse JNoSQL. + * + * Example usage: + * 
+ * {@code
+ * @Inject
+ * private ElasticsearchTemplate elasticsearchTemplate;
+ *
+ * SearchRequest request = new SearchRequest.Builder()
+ *         .index("documents")
+ *         .query(q -> q.match(m -> m.field("title").query("Eclipse JNoSQL")))
+ *         .build();
+ *
+ * Stream results = elasticsearchTemplate.search(request);
+ * results.forEach(System.out::println);
+ * }
+ *
+ * + * @see DocumentTemplate */ public interface ElasticsearchTemplate extends DocumentTemplate { /** - * Find entities from {@link SearchRequest} + * Executes a search query using the provided {@link SearchRequest}. + * The search query should be built using Elasticsearch's client API and passed + * to this method. The results will be mapped to the specified entity type + * and returned as a stream. * - * @param query the query - * @return the objects from query - * @throws NullPointerException when query is null + * @param the entity type + * @param query the Elasticsearch query request + * @return a stream of entities resulting from the search query + * @throws NullPointerException if the query is null */ Stream search(SearchRequest query); } From 3bab504328f3f2d590e21d2d0f4c0f99e875b5cb Mon Sep 17 00:00:00 2001 From: Otavio Santana Date: Sun, 2 Mar 2025 04:57:43 +0000 Subject: [PATCH 21/39] docs: enhance documentation to HazelcastTemplate Signed-off-by: Otavio Santana --- .../hazelcast/mapping/HazelcastTemplate.java | 68 +++++++++++++++---- 1 file changed, 53 insertions(+), 15 deletions(-) diff --git a/jnosql-hazelcast/src/main/java/org/eclipse/jnosql/databases/hazelcast/mapping/HazelcastTemplate.java b/jnosql-hazelcast/src/main/java/org/eclipse/jnosql/databases/hazelcast/mapping/HazelcastTemplate.java index fe66cc11c..37f1f5e13 100644 --- a/jnosql-hazelcast/src/main/java/org/eclipse/jnosql/databases/hazelcast/mapping/HazelcastTemplate.java +++ b/jnosql-hazelcast/src/main/java/org/eclipse/jnosql/databases/hazelcast/mapping/HazelcastTemplate.java @@ -21,40 +21,78 @@ import java.util.Map; /** - * A template layer to Hazelcast key-value type + * A specialized {@link KeyValueTemplate} for Hazelcast, + * providing methods to execute queries using SQL-like expressions and predicates. + *

+ * This template facilitates querying key-value structures stored in a Hazelcast instance. + * It supports both SQL-like queries with named parameters and Hazelcast-specific predicates. + *

+ * + * Example usage: + * 
+ * {@code
+ * @Inject
+ * private HazelcastTemplate hazelcastTemplate;
+ *
+ * // Query using SQL-like syntax
+ * Collection movies = hazelcastTemplate.sql("name = :name", Map.of("name", "Inception"));
+ * movies.forEach(System.out::println);
+ *
+ * // Query using Hazelcast Predicate
+ * Predicate predicate = Predicates.equal("genre", "Sci-Fi");
+ * Collection sciFiMovies = hazelcastTemplate.sql(predicate);
+ * sciFiMovies.forEach(System.out::println);
+ * }
+ *
+ * + * @see KeyValueTemplate */ public interface HazelcastTemplate extends KeyValueTemplate { /** - * Executes hazelcast query + * Executes a Hazelcast query using SQL-like syntax. + *

+ * The query should follow Hazelcast's SQL-like query syntax for key-value stores. + *

* * @param the entity type - * @param query the query - * @return the result query - * @throws NullPointerException when there is null query + * @param query the SQL-like query string + * @return a collection of matching entities + * @throws NullPointerException if the query is null */ Collection sql(String query); /** - * Executes hazelcast query with named query. - * E.g.: bucketManager.query("name = :name", singletonMap("name", "Matrix")) + * Executes a Hazelcast query with named parameters. + *

+ * Example usage: + * 

+     * {@code
+     * Collection movies = hazelcastTemplate.sql("name = :name", Map.of("name", "The Matrix"));
+     * }
+     *
+ *

* - * @param query the query * @param the entity type - * @param params the params to bind - * @return the result query - * @throws NullPointerException when there is null query + * @param query the SQL-like query string + * @param params a map of named parameters to bind in the query + * @return a collection of matching entities + * @throws NullPointerException if the query or params are null */ Collection sql(String query, Map params); /** - * Executes hazelcast query + * Executes a Hazelcast query using a {@link Predicate}. + *

+ * The predicate-based approach is useful for filtering key-value pairs + * based on specific criteria. + *

* - * @param predicate the hazelcast predicate * @param the key type * @param the value type - * @return the result query - * @throws NullPointerException when there is null predicate + * @param predicate the Hazelcast predicate for filtering data + * @return a collection of values that match the predicate + * @throws NullPointerException if the predicate is null */ Collection sql(Predicate predicate); From acc700e04ab1bd9dc2966670b5b7ebc2835a89c5 Mon Sep 17 00:00:00 2001 From: Otavio Santana Date: Sun, 2 Mar 2025 04:59:48 +0000 Subject: [PATCH 22/39] docs: enhance hazelcast query documentation Signed-off-by: Otavio Santana --- .../databases/hazelcast/mapping/Query.java | 23 ++++++++++++++++++- 1 file changed, 22 insertions(+), 1 deletion(-) diff --git a/jnosql-hazelcast/src/main/java/org/eclipse/jnosql/databases/hazelcast/mapping/Query.java b/jnosql-hazelcast/src/main/java/org/eclipse/jnosql/databases/hazelcast/mapping/Query.java index 3fd0ab2ff..0ecfb37f8 100644 --- a/jnosql-hazelcast/src/main/java/org/eclipse/jnosql/databases/hazelcast/mapping/Query.java +++ b/jnosql-hazelcast/src/main/java/org/eclipse/jnosql/databases/hazelcast/mapping/Query.java @@ -20,11 +20,32 @@ import java.lang.annotation.Target; /** - * To a dynamic query on HazelcastRepository interfaces. + * Annotation for defining a dynamic query method in Hazelcast repositories. + *

+ * This annotation allows developers to specify Hazelcast query expressions + * directly in repository methods. + *

+ * + * Example usage: + * 
+ * {@code
+ * @Repository
+ * interface PersonRepository extends HazelcastRepository {
+ *
+ *     @Query("age > 30")
+ *     List findAdults();
+ * }
+ * }
+ *
*/ @Retention(RetentionPolicy.RUNTIME) @Target(ElementType.METHOD) public @interface Query { + /** + * The Hazelcast query expression. + * + * @return the query string to be executed + */ String value(); } From 101300c96206ab7be3808a786af43c5ab3427b75 Mon Sep 17 00:00:00 2001 From: Otavio Santana Date: Sun, 2 Mar 2025 05:00:26 +0000 Subject: [PATCH 23/39] feat: update documentation at Hazelcastrepository Signed-off-by: Otavio Santana --- .../mapping/HazelcastRepository.java | 23 +++++++++++++++++-- 1 file changed, 21 insertions(+), 2 deletions(-) diff --git a/jnosql-hazelcast/src/main/java/org/eclipse/jnosql/databases/hazelcast/mapping/HazelcastRepository.java b/jnosql-hazelcast/src/main/java/org/eclipse/jnosql/databases/hazelcast/mapping/HazelcastRepository.java index 46a4d3dfa..998357638 100644 --- a/jnosql-hazelcast/src/main/java/org/eclipse/jnosql/databases/hazelcast/mapping/HazelcastRepository.java +++ b/jnosql-hazelcast/src/main/java/org/eclipse/jnosql/databases/hazelcast/mapping/HazelcastRepository.java @@ -18,10 +18,29 @@ import org.eclipse.jnosql.mapping.NoSQLRepository; /** - * The hazelcast {@link NoSQLRepository} + * A Hazelcast-specific extension of {@link NoSQLRepository}, providing + * key-value data storage and retrieval using Hazelcast. + *

+ * This repository interface allows for defining custom queries using + * {@link Query} annotations and enables CRUD operations for entities. + *

+ * + * Example usage: + * 
+ * {@code
+ * @Repository
+ * interface ProductRepository extends HazelcastRepository {
+ *
+ *     @Query("category = :category")
+ *     Set findByCategory(@Param("category") String category);
+ * }
+ * }
+ *
* * @param the entity type - * @param the id entity type + * @param the identifier type + * @see Query + * @see NoSQLRepository */ public interface HazelcastRepository extends NoSQLRepository { } From bd6f4606a947a52ff59d83125caefa7b79324724 Mon Sep 17 00:00:00 2001 From: Otavio Santana Date: Sun, 2 Mar 2025 05:01:35 +0000 Subject: [PATCH 24/39] feat: update test hazelcast Signed-off-by: Otavio Santana --- .../mapping/HazelcastRepositoryProxy.java | 3 +- .../databases/hazelcast/mapping/Param.java | 31 ------------ .../hazelcast/mapping/ParamUtil.java | 48 ------------------- .../mapping/HazelcastRepositoryProxyTest.java | 3 +- 4 files changed, 4 insertions(+), 81 deletions(-) delete mode 100644 jnosql-hazelcast/src/main/java/org/eclipse/jnosql/databases/hazelcast/mapping/Param.java delete mode 100644 jnosql-hazelcast/src/main/java/org/eclipse/jnosql/databases/hazelcast/mapping/ParamUtil.java diff --git a/jnosql-hazelcast/src/main/java/org/eclipse/jnosql/databases/hazelcast/mapping/HazelcastRepositoryProxy.java b/jnosql-hazelcast/src/main/java/org/eclipse/jnosql/databases/hazelcast/mapping/HazelcastRepositoryProxy.java index a0e2b993c..d530ec710 100644 --- a/jnosql-hazelcast/src/main/java/org/eclipse/jnosql/databases/hazelcast/mapping/HazelcastRepositoryProxy.java +++ b/jnosql-hazelcast/src/main/java/org/eclipse/jnosql/databases/hazelcast/mapping/HazelcastRepositoryProxy.java @@ -16,6 +16,7 @@ import org.eclipse.jnosql.mapping.core.query.AbstractRepository; import org.eclipse.jnosql.mapping.core.repository.DynamicReturn; +import org.eclipse.jnosql.mapping.driver.ParamUtil; import org.eclipse.jnosql.mapping.keyvalue.KeyValueTemplate; import org.eclipse.jnosql.mapping.keyvalue.query.AbstractKeyValueRepositoryProxy; import org.eclipse.jnosql.mapping.keyvalue.query.DefaultKeyValueRepository; @@ -84,7 +85,7 @@ public Object invoke(Object instance, Method method, Object[] args) throws Throw Query query = method.getAnnotation(Query.class); if (Objects.nonNull(query)) { Stream result; - Map params = ParamUtil.getParams(args, method); + Map params = ParamUtil.INSTANCE.getParams(args, method); if (params.isEmpty()) { result = template.sql(query.value()).stream(); } else { diff --git a/jnosql-hazelcast/src/main/java/org/eclipse/jnosql/databases/hazelcast/mapping/Param.java b/jnosql-hazelcast/src/main/java/org/eclipse/jnosql/databases/hazelcast/mapping/Param.java deleted file mode 100644 index c00997f71..000000000 --- a/jnosql-hazelcast/src/main/java/org/eclipse/jnosql/databases/hazelcast/mapping/Param.java +++ /dev/null @@ -1,31 +0,0 @@ -/* - * Copyright (c) 2022 Contributors to the Eclipse Foundation - * All rights reserved. This program and the accompanying materials - * are made available under the terms of the Eclipse Public License v1.0 - * and Apache License v2.0 which accompanies this distribution. - * The Eclipse Public License is available at http://www.eclipse.org/legal/epl-v10.html - * and the Apache License v2.0 is available at http://www.opensource.org/licenses/apache2.0.php. - * - * You may elect to redistribute this code under either of these licenses. - * - * Contributors: - * - * Otavio Santana - */ -package org.eclipse.jnosql.databases.hazelcast.mapping; - -import java.lang.annotation.ElementType; -import java.lang.annotation.Retention; -import java.lang.annotation.RetentionPolicy; -import java.lang.annotation.Target; - - -/** - * Defines a param to a Query query. - */ -@Retention(RetentionPolicy.RUNTIME) -@Target(ElementType.PARAMETER) -public @interface Param { - - String value(); -} diff --git a/jnosql-hazelcast/src/main/java/org/eclipse/jnosql/databases/hazelcast/mapping/ParamUtil.java b/jnosql-hazelcast/src/main/java/org/eclipse/jnosql/databases/hazelcast/mapping/ParamUtil.java deleted file mode 100644 index 2f49eb70a..000000000 --- a/jnosql-hazelcast/src/main/java/org/eclipse/jnosql/databases/hazelcast/mapping/ParamUtil.java +++ /dev/null @@ -1,48 +0,0 @@ -/* - * Copyright (c) 2022 Contributors to the Eclipse Foundation - * All rights reserved. This program and the accompanying materials - * are made available under the terms of the Eclipse Public License v1.0 - * and Apache License v2.0 which accompanies this distribution. - * The Eclipse Public License is available at http://www.eclipse.org/legal/epl-v10.html - * and the Apache License v2.0 is available at http://www.opensource.org/licenses/apache2.0.php. - * - * You may elect to redistribute this code under either of these licenses. - * - * Contributors: - * - * Otavio Santana - */ -package org.eclipse.jnosql.databases.hazelcast.mapping; - -import java.lang.annotation.Annotation; -import java.lang.reflect.Method; -import java.util.HashMap; -import java.util.Map; -import java.util.Optional; -import java.util.stream.Stream; - -final class ParamUtil { - - private ParamUtil() { - } - - static Map getParams(Object[] args, Method method) { - - Map jsonObject = new HashMap<>(); - Annotation[][] annotations = method.getParameterAnnotations(); - - for (int index = 0; index < annotations.length; index++) { - - final Object arg = args[index]; - - Optional param = Stream.of(annotations[index]) - .filter(Param.class::isInstance) - .map(Param.class::cast) - .findFirst(); - param.ifPresent(p -> jsonObject.put(p.value(), arg)); - - } - - return jsonObject; - } -} diff --git a/jnosql-hazelcast/src/test/java/org/eclipse/jnosql/databases/hazelcast/mapping/HazelcastRepositoryProxyTest.java b/jnosql-hazelcast/src/test/java/org/eclipse/jnosql/databases/hazelcast/mapping/HazelcastRepositoryProxyTest.java index aecd43c65..094c00656 100644 --- a/jnosql-hazelcast/src/test/java/org/eclipse/jnosql/databases/hazelcast/mapping/HazelcastRepositoryProxyTest.java +++ b/jnosql-hazelcast/src/test/java/org/eclipse/jnosql/databases/hazelcast/mapping/HazelcastRepositoryProxyTest.java @@ -14,6 +14,7 @@ */ package org.eclipse.jnosql.databases.hazelcast.mapping; +import jakarta.data.repository.Param; import jakarta.inject.Inject; import org.eclipse.jnosql.mapping.core.Converters; import org.eclipse.jnosql.mapping.core.spi.EntityMetadataExtension; @@ -136,6 +137,6 @@ interface HumanRepository extends HazelcastRepository { List findActive(); @Query("name = :name AND age = :age") - Set findByAgeAndInteger(@Param("name") String name, @Param("age") Integer age); + Set findByAgeAndInteger(@Param("name") String name,@Param("age") Integer age); } } \ No newline at end of file From 0065ccaa72bf266b8ffa6078ce06e32974fd44af Mon Sep 17 00:00:00 2001 From: Otavio Santana Date: Sun, 2 Mar 2025 05:04:47 +0000 Subject: [PATCH 25/39] feat: update documentation on orientdb template Signed-off-by: Otavio Santana --- .../orientdb/mapping/OrientDBTemplate.java | 86 ++++++++++++++----- 1 file changed, 66 insertions(+), 20 deletions(-) diff --git a/jnosql-orientdb/src/main/java/org/eclipse/jnosql/databases/orientdb/mapping/OrientDBTemplate.java b/jnosql-orientdb/src/main/java/org/eclipse/jnosql/databases/orientdb/mapping/OrientDBTemplate.java index b833bea4e..a84fb75ee 100644 --- a/jnosql-orientdb/src/main/java/org/eclipse/jnosql/databases/orientdb/mapping/OrientDBTemplate.java +++ b/jnosql-orientdb/src/main/java/org/eclipse/jnosql/databases/orientdb/mapping/OrientDBTemplate.java @@ -23,45 +23,91 @@ import java.util.stream.Stream; /** - * A {@link DocumentTemplate} to orientdb + * A specialized {@link DocumentTemplate} for OrientDB. + *

+ * This template provides methods for executing native SQL queries, + * live queries, and queries with named parameters. + *

*/ public interface OrientDBTemplate extends DocumentTemplate { /** - * Find using OrientDB native query + * Executes a native OrientDB SQL query. + *

+ * This method allows running SQL queries with positional parameters. + * Example usage: + * 

+     * {@code
+     * Stream users = template.sql("SELECT FROM User WHERE age > ?", 30);
+     * }
+     *
+ *

* - * @param query the query - * @param params the params - * @return the query result - * @throws NullPointerException when either query or params are null + * @param the expected result type + * @param query the SQL query string + * @param params optional positional parameters for the query + * @return a stream of results matching the query + * @throws NullPointerException if the query or params are null */ Stream sql(String query, Object... params); /** - * Find using OrientDB native query with map params + * Executes a native OrientDB SQL query with named parameters. + *

+ * Example usage: + * 

+     * {@code
+     * Map params = Map.of("age", 30);
+     * Stream users = template.sql("SELECT FROM User WHERE age > :age", params);
+     * }
+     *
+ *

* - * @param query the query - * @param params the params - * @return the query result - * @throws NullPointerException when either query or params are null + * @param the expected result type + * @param query the SQL query string + * @param params a map of named parameters for the query + * @return a stream of results matching the query + * @throws NullPointerException if the query or params are null */ Stream sql(String query, Map params); + /** - * Execute live query + * Executes a live query in OrientDB. + *

+ * A live query listens for real-time changes in the database and triggers callbacks + * for each event that occurs (insert, update, delete). + * Example usage: + * 

+     * {@code
+     * template.live(selectQuery, event -> System.out.println("Update: " + event));
+     * }
+     *
+ *

* - * @param query the query - * @param callBacks callbacks for each operation - * @throws NullPointerException when both query and callBack are null + * @param the expected result type + * @param query the query definition using {@link SelectQuery} + * @param callBacks callback to handle live query events + * @throws NullPointerException if either query or callBacks is null */ void live(SelectQuery query, OrientDBLiveCallback callBacks); /** - * Execute live query + * Executes a live query in OrientDB using a SQL string. + *

+ * The query must include the "LIVE" keyword. + * Example usage: + * 

+     * {@code
+     * template.live("LIVE SELECT FROM User", event -> System.out.println("User changed: " + event));
+     * }
+     *
+ *

* - * @param query the string query, you must add "live" - * @param callBacks callbacks for each operation - * @param params the params - * @throws NullPointerException when both query, callBack are null + * @param the expected result type + * @param query the SQL query string containing the "LIVE" keyword + * @param callBacks callback to handle live query events + * @param params optional positional parameters for the query + * @throws NullPointerException if either query or callBacks is null */ void live(String query, OrientDBLiveCallback callBacks, Object... params); } From 2ac1687c04d4fd7e3ab0943cad6e3a4ecf012a01 Mon Sep 17 00:00:00 2001 From: Otavio Santana Date: Sun, 2 Mar 2025 05:07:37 +0000 Subject: [PATCH 26/39] docs: generate sql documentation on orientdb Signed-off-by: Otavio Santana --- .../databases/orientdb/mapping/SQL.java | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/jnosql-orientdb/src/main/java/org/eclipse/jnosql/databases/orientdb/mapping/SQL.java b/jnosql-orientdb/src/main/java/org/eclipse/jnosql/databases/orientdb/mapping/SQL.java index 5195ea607..6b160f52b 100644 --- a/jnosql-orientdb/src/main/java/org/eclipse/jnosql/databases/orientdb/mapping/SQL.java +++ b/jnosql-orientdb/src/main/java/org/eclipse/jnosql/databases/orientdb/mapping/SQL.java @@ -20,11 +20,28 @@ import java.lang.annotation.Target; /** - * To a dynamic query on OrientDBCrudRepository and OrientDBCrudRepositoryAsync interfaces. + * Annotation for defining dynamic SQL queries in OrientDB repositories. + *

+ * This annotation is used on methods within {@link OrientDBCrudRepository} to execute + * custom SQL queries directly on OrientDB. + *

+ * + *

Example usage:

+ * 
+ * {@code
+ * @SQL("SELECT FROM User WHERE age > :age")
+ * List findUsersByAge(@Param("age") int age);
+ * }
+ *
*/ @Retention(RetentionPolicy.RUNTIME) @Target(ElementType.METHOD) public @interface SQL { + /** + * Defines the SQL query to be executed. + * + * @return the SQL query string + */ String value(); } From 480a0d6b730c85e9061141a8f0160873e08e733d Mon Sep 17 00:00:00 2001 From: Otavio Santana Date: Sun, 2 Mar 2025 05:07:47 +0000 Subject: [PATCH 27/39] docs: generate orientdb repository Signed-off-by: Otavio Santana --- .../mapping/OrientDBCrudRepository.java | 25 ++++++++++++++++--- 1 file changed, 22 insertions(+), 3 deletions(-) diff --git a/jnosql-orientdb/src/main/java/org/eclipse/jnosql/databases/orientdb/mapping/OrientDBCrudRepository.java b/jnosql-orientdb/src/main/java/org/eclipse/jnosql/databases/orientdb/mapping/OrientDBCrudRepository.java index b75136ee5..8562f811b 100644 --- a/jnosql-orientdb/src/main/java/org/eclipse/jnosql/databases/orientdb/mapping/OrientDBCrudRepository.java +++ b/jnosql-orientdb/src/main/java/org/eclipse/jnosql/databases/orientdb/mapping/OrientDBCrudRepository.java @@ -18,10 +18,29 @@ import org.eclipse.jnosql.mapping.NoSQLRepository; /** - * The OrientDB {@link NoSQLRepository} + * A repository interface for OrientDB that extends {@link NoSQLRepository}. + *

+ * This interface allows interaction with OrientDB as a document-oriented NoSQL database, + * supporting standard CRUD operations and custom queries using the {@link SQL} annotation. + *

* - * @param the entity type - * @param the entity id type + *

Example usage:

+ * 
+ * {@code
+ * @Repository
+ * public interface UserRepository extends OrientDBCrudRepository {
+ *
+ *     @SQL("SELECT FROM User WHERE age > :age")
+ *     List findUsersByAge(@Param("age") int age);
+ *
+ *     @SQL("SELECT FROM User WHERE name = :name")
+ *     List findByName(@Param("name") String name);
+ * }
+ * }
+ *
+ * + * @param the entity type + * @param the entity ID type */ public interface OrientDBCrudRepository extends NoSQLRepository { } From 296962b9418212458577dc66d9e134f8dc0cbe0c Mon Sep 17 00:00:00 2001 From: Otavio Santana Date: Sun, 2 Mar 2025 05:11:36 +0000 Subject: [PATCH 28/39] feat: remove utils on orientdb Signed-off-by: Otavio Santana --- .../orientdb/mapping/MapTypeUtil.java | 48 ------------------- .../OrientDBDocumentRepositoryProxy.java | 3 +- .../databases/orientdb/mapping/Param.java | 31 ------------ .../OrientDBDocumentRepositoryProxyTest.java | 1 + 4 files changed, 3 insertions(+), 80 deletions(-) delete mode 100644 jnosql-orientdb/src/main/java/org/eclipse/jnosql/databases/orientdb/mapping/MapTypeUtil.java delete mode 100644 jnosql-orientdb/src/main/java/org/eclipse/jnosql/databases/orientdb/mapping/Param.java diff --git a/jnosql-orientdb/src/main/java/org/eclipse/jnosql/databases/orientdb/mapping/MapTypeUtil.java b/jnosql-orientdb/src/main/java/org/eclipse/jnosql/databases/orientdb/mapping/MapTypeUtil.java deleted file mode 100644 index 048ffe0c0..000000000 --- a/jnosql-orientdb/src/main/java/org/eclipse/jnosql/databases/orientdb/mapping/MapTypeUtil.java +++ /dev/null @@ -1,48 +0,0 @@ -/* - * Copyright (c) 2022 Contributors to the Eclipse Foundation - * All rights reserved. This program and the accompanying materials - * are made available under the terms of the Eclipse Public License v1.0 - * and Apache License v2.0 which accompanies this distribution. - * The Eclipse Public License is available at http://www.eclipse.org/legal/epl-v10.html - * and the Apache License v2.0 is available at http://www.opensource.org/licenses/apache2.0.php. - * - * You may elect to redistribute this code under either of these licenses. - * - * Contributors: - * - * Otavio Santana - */ -package org.eclipse.jnosql.databases.orientdb.mapping; - -import java.lang.annotation.Annotation; -import java.lang.reflect.Method; -import java.util.HashMap; -import java.util.Map; -import java.util.Optional; -import java.util.stream.Stream; - -final class MapTypeUtil { - - private MapTypeUtil() { - } - - static Map getParams(Object[] args, Method method) { - - Map params = new HashMap<>(); - Annotation[][] annotations = method.getParameterAnnotations(); - - for (int index = 0; index < annotations.length; index++) { - - final Object arg = args[index]; - - Optional param = Stream.of(annotations[index]) - .filter(Param.class::isInstance) - .map(Param.class::cast) - .findFirst(); - param.ifPresent(p -> params.put(p.value(), arg)); - - } - - return params; - } -} diff --git a/jnosql-orientdb/src/main/java/org/eclipse/jnosql/databases/orientdb/mapping/OrientDBDocumentRepositoryProxy.java b/jnosql-orientdb/src/main/java/org/eclipse/jnosql/databases/orientdb/mapping/OrientDBDocumentRepositoryProxy.java index 75b0f0503..f2cef97eb 100644 --- a/jnosql-orientdb/src/main/java/org/eclipse/jnosql/databases/orientdb/mapping/OrientDBDocumentRepositoryProxy.java +++ b/jnosql-orientdb/src/main/java/org/eclipse/jnosql/databases/orientdb/mapping/OrientDBDocumentRepositoryProxy.java @@ -19,6 +19,7 @@ import org.eclipse.jnosql.mapping.core.query.AbstractRepository; import org.eclipse.jnosql.mapping.core.repository.DynamicReturn; import org.eclipse.jnosql.mapping.document.DocumentTemplate; +import org.eclipse.jnosql.mapping.driver.ParamUtil; import org.eclipse.jnosql.mapping.metadata.EntitiesMetadata; import org.eclipse.jnosql.mapping.metadata.EntityMetadata; import org.eclipse.jnosql.mapping.semistructured.query.AbstractSemiStructuredRepositoryProxy; @@ -96,7 +97,7 @@ public Object invoke(Object instance, Method method, Object[] args) throws Throw if (args == null || args.length == 0) { result = template.sql(sql.value()); } else { - Map params = MapTypeUtil.getParams(args, method); + Map params = ParamUtil.INSTANCE.getParams(args, method); if (params.isEmpty()) { result = template.sql(sql.value(), args); } else { diff --git a/jnosql-orientdb/src/main/java/org/eclipse/jnosql/databases/orientdb/mapping/Param.java b/jnosql-orientdb/src/main/java/org/eclipse/jnosql/databases/orientdb/mapping/Param.java deleted file mode 100644 index 28908d472..000000000 --- a/jnosql-orientdb/src/main/java/org/eclipse/jnosql/databases/orientdb/mapping/Param.java +++ /dev/null @@ -1,31 +0,0 @@ -/* - * Copyright (c) 2022 Contributors to the Eclipse Foundation - * All rights reserved. This program and the accompanying materials - * are made available under the terms of the Eclipse Public License v1.0 - * and Apache License v2.0 which accompanies this distribution. - * The Eclipse Public License is available at http://www.eclipse.org/legal/epl-v10.html - * and the Apache License v2.0 is available at http://www.opensource.org/licenses/apache2.0.php. - * - * You may elect to redistribute this code under either of these licenses. - * - * Contributors: - * - * Otavio Santana - */ -package org.eclipse.jnosql.databases.orientdb.mapping; - -import java.lang.annotation.ElementType; -import java.lang.annotation.Retention; -import java.lang.annotation.RetentionPolicy; -import java.lang.annotation.Target; - - -/** - * Defines a param to a OrientDB query. - */ -@Retention(RetentionPolicy.RUNTIME) -@Target(ElementType.PARAMETER) -public @interface Param { - - String value(); -} diff --git a/jnosql-orientdb/src/test/java/org/eclipse/jnosql/databases/orientdb/mapping/OrientDBDocumentRepositoryProxyTest.java b/jnosql-orientdb/src/test/java/org/eclipse/jnosql/databases/orientdb/mapping/OrientDBDocumentRepositoryProxyTest.java index e393b7ccc..f2791fb2d 100644 --- a/jnosql-orientdb/src/test/java/org/eclipse/jnosql/databases/orientdb/mapping/OrientDBDocumentRepositoryProxyTest.java +++ b/jnosql-orientdb/src/test/java/org/eclipse/jnosql/databases/orientdb/mapping/OrientDBDocumentRepositoryProxyTest.java @@ -14,6 +14,7 @@ */ package org.eclipse.jnosql.databases.orientdb.mapping; +import jakarta.data.repository.Param; import jakarta.inject.Inject; import jakarta.nosql.tck.entities.Person; import org.eclipse.jnosql.mapping.core.Converters; From 6784ac18fcac366f7e51263c9d91b00861722c21 Mon Sep 17 00:00:00 2001 From: Otavio Santana Date: Sun, 2 Mar 2025 05:13:12 +0000 Subject: [PATCH 29/39] docs: enhance and explain the change at changelog Signed-off-by: Otavio Santana --- CHANGELOG.adoc | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc index 8534ffc1d..a18ad12b8 100644 --- a/CHANGELOG.adoc +++ b/CHANGELOG.adoc @@ -19,6 +19,7 @@ and this project adheres to https://semver.org/spec/v2.0.0.html[Semantic Version - Update Couchbase client 3.7.6 - Update DynamoDB driver 2.29.45 - Update ArangoDb driver to 7.17.0 +- At repositories params, use the Param annotation from Jakarta Data API. === Fixed From ee6abe02614b116de74820672105280e2ba41f3a Mon Sep 17 00:00:00 2001 From: Otavio Santana Date: Sun, 2 Mar 2025 05:15:41 +0000 Subject: [PATCH 30/39] docs: update documentation removing h3 Signed-off-by: Otavio Santana --- .../main/java/org/eclipse/jnosql/mapping/driver/ParamUtil.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/jnosql-database-commons/src/main/java/org/eclipse/jnosql/mapping/driver/ParamUtil.java b/jnosql-database-commons/src/main/java/org/eclipse/jnosql/mapping/driver/ParamUtil.java index b521e30e8..d38f2f895 100644 --- a/jnosql-database-commons/src/main/java/org/eclipse/jnosql/mapping/driver/ParamUtil.java +++ b/jnosql-database-commons/src/main/java/org/eclipse/jnosql/mapping/driver/ParamUtil.java @@ -29,7 +29,7 @@ *

This utility supports repositories using custom query annotations such as {@code @AQL}, {@code @Cypher}, * and others, where parameters are annotated with {@link Param} to enable named parameter binding.

* - *

Example Usage:

+ * Example Usage: * 
{@code
  * public interface PersonRepository extends DatabaseBRepository {
  *

From 71e3a380a36f2a13c4795cd5856258d9870d36d3 Mon Sep 17 00:00:00 2001
From: Otavio Santana 
Date: Sun, 2 Mar 2025 05:21:07 +0000
Subject: [PATCH 31/39] docs: remove p tag at javadoc documentation

Signed-off-by: Otavio Santana 
---
 .../eclipse/jnosql/databases/arangodb/mapping/AQL.java   | 9 ++++-----
 .../databases/arangodb/mapping/ArangoDBRepository.java   | 5 ++---
 .../databases/arangodb/mapping/ArangoDBTemplate.java     | 4 ++--
 .../couchdb/communication/CouchDBDocumentManager.java    | 3 ---
 .../hbase/communication/HBaseColumnConfiguration.java    | 2 +-
 .../hbase/communication/HBaseColumnManager.java          | 2 +-
 .../mongodb/communication/MongoDBDocumentManager.java    | 4 ++--
 .../ravendb/communication/RavenDBDocumentManager.java    | 2 +-
 .../riak/communication/RiakBucketManagerFactory.java     | 2 +-
 .../riak/communication/RiakKeyValueConfiguration.java    | 2 +-
 .../solr/communication/SolrDocumentManager.java          | 2 +-
 .../tinkerpop/mapping/spi/CustomRepositoryGraphBean.java | 4 ++--
 12 files changed, 18 insertions(+), 23 deletions(-)

diff --git a/jnosql-arangodb/src/main/java/org/eclipse/jnosql/databases/arangodb/mapping/AQL.java b/jnosql-arangodb/src/main/java/org/eclipse/jnosql/databases/arangodb/mapping/AQL.java
index 0725c2f71..a020d8a70 100644
--- a/jnosql-arangodb/src/main/java/org/eclipse/jnosql/databases/arangodb/mapping/AQL.java
+++ b/jnosql-arangodb/src/main/java/org/eclipse/jnosql/databases/arangodb/mapping/AQL.java
@@ -22,17 +22,16 @@
 /**
  * Annotation to define a dynamic AQL (ArangoDB Query Language) query for methods
  * in the {@link ArangoDBRepository} interface.
+ * This annotation enables executing custom AQL queries directly from repository methods,
+ * similar to how queries are defined in other JNoSQL repositories.
  *
- * 
This annotation enables executing custom AQL queries directly from repository methods,
- * similar to how queries are defined in other JNoSQL repositories.

- *
- * 
Example usage:

+ * Example usage:
  * 
{@code
  * @AQL("FOR p IN Person RETURN p")
  * List findAll();
  * }

  *
- * 
Parameterized query:

+ *Parameterized query:
  * 
{@code
  * @AQL("FOR p IN Person FILTER p.name == @name RETURN p")
  * List findByName(@Param("name") String name);
diff --git a/jnosql-arangodb/src/main/java/org/eclipse/jnosql/databases/arangodb/mapping/ArangoDBRepository.java b/jnosql-arangodb/src/main/java/org/eclipse/jnosql/databases/arangodb/mapping/ArangoDBRepository.java
index 6b24b8d30..dc9bb84b6 100644
--- a/jnosql-arangodb/src/main/java/org/eclipse/jnosql/databases/arangodb/mapping/ArangoDBRepository.java
+++ b/jnosql-arangodb/src/main/java/org/eclipse/jnosql/databases/arangodb/mapping/ArangoDBRepository.java
@@ -20,10 +20,9 @@
 
 /**
  * A repository interface for ArangoDB, extending the generic {@link NoSQLRepository}.
+ * This repository supports executing custom AQL queries via the {@link AQL} annotation.
  *
- * 
This repository supports executing custom AQL queries via the {@link AQL} annotation.

- *
- * 
Example usage:

+ * Example usage:
  * 
{@code
  * @Repository
  * public interface PersonRepository extends ArangoDBRepository {
diff --git a/jnosql-arangodb/src/main/java/org/eclipse/jnosql/databases/arangodb/mapping/ArangoDBTemplate.java b/jnosql-arangodb/src/main/java/org/eclipse/jnosql/databases/arangodb/mapping/ArangoDBTemplate.java
index 8f12a2fe6..3c669433f 100644
--- a/jnosql-arangodb/src/main/java/org/eclipse/jnosql/databases/arangodb/mapping/ArangoDBTemplate.java
+++ b/jnosql-arangodb/src/main/java/org/eclipse/jnosql/databases/arangodb/mapping/ArangoDBTemplate.java
@@ -24,8 +24,8 @@
  * A specialized {@link DocumentTemplate} for ArangoDB, providing methods to execute
  * queries using the ArangoDB Query Language (AQL).
  *
- * 
This template allows executing AQL queries with named parameters and supports
- * result serialization either through Eclipse JNoSQL or directly via ArangoDB.

+ *  This template allows executing AQL queries with named parameters and supports
+ * result serialization either through Eclipse JNoSQL or directly via ArangoDB.
  */
 public interface ArangoDBTemplate extends DocumentTemplate {
 
diff --git a/jnosql-couchdb/src/main/java/org/eclipse/jnosql/databases/couchdb/communication/CouchDBDocumentManager.java b/jnosql-couchdb/src/main/java/org/eclipse/jnosql/databases/couchdb/communication/CouchDBDocumentManager.java
index 84d9ef20f..0f0f7d94e 100644
--- a/jnosql-couchdb/src/main/java/org/eclipse/jnosql/databases/couchdb/communication/CouchDBDocumentManager.java
+++ b/jnosql-couchdb/src/main/java/org/eclipse/jnosql/databases/couchdb/communication/CouchDBDocumentManager.java
@@ -21,12 +21,9 @@
 /**
  * A CouchDB-specific extension of {@link DatabaseManager} that provides an additional
  * feature to count the number of documents in the database.
- * 

  * This interface offers a {@code count()} method to retrieve the total number of documents
  * stored in the CouchDB database. It extends the {@link DatabaseManager} to align with
  * Eclipse JNoSQL's database management abstraction.
- * 

- *
  * Example Usage:
  * 
{@code
  * @Inject
diff --git a/jnosql-hbase/src/main/java/org/eclipse/jnosql/databases/hbase/communication/HBaseColumnConfiguration.java b/jnosql-hbase/src/main/java/org/eclipse/jnosql/databases/hbase/communication/HBaseColumnConfiguration.java
index 44949f20a..b07711859 100644
--- a/jnosql-hbase/src/main/java/org/eclipse/jnosql/databases/hbase/communication/HBaseColumnConfiguration.java
+++ b/jnosql-hbase/src/main/java/org/eclipse/jnosql/databases/hbase/communication/HBaseColumnConfiguration.java
@@ -29,7 +29,7 @@
 
 /**
  * Configuration to HBase that returns {@link HBaseColumnManagerFactory}
- * 
hbase.family.n: as prefix to add family, eg: hbase,family.1=column-family

+ * hbase.family.n: as prefix to add family, eg: hbase,family.1=column-family
  */
 public class HBaseColumnConfiguration implements DatabaseConfiguration {
 
diff --git a/jnosql-hbase/src/main/java/org/eclipse/jnosql/databases/hbase/communication/HBaseColumnManager.java b/jnosql-hbase/src/main/java/org/eclipse/jnosql/databases/hbase/communication/HBaseColumnManager.java
index 261ad4508..988fb7410 100644
--- a/jnosql-hbase/src/main/java/org/eclipse/jnosql/databases/hbase/communication/HBaseColumnManager.java
+++ b/jnosql-hbase/src/main/java/org/eclipse/jnosql/databases/hbase/communication/HBaseColumnManager.java
@@ -52,7 +52,7 @@
 /**
  * The Hbase implementation to {@link DatabaseManager}.
  * It does not support TTL methods
- * 
{@link HBaseColumnManager#insert(org.eclipse.jnosql.communication.semistructured.CommunicationEntity, Duration)}

+ * {@link HBaseColumnManager#insert(org.eclipse.jnosql.communication.semistructured.CommunicationEntity, Duration)}
  */
 public class HBaseColumnManager implements DatabaseManager {
 
diff --git a/jnosql-mongodb/src/main/java/org/eclipse/jnosql/databases/mongodb/communication/MongoDBDocumentManager.java b/jnosql-mongodb/src/main/java/org/eclipse/jnosql/databases/mongodb/communication/MongoDBDocumentManager.java
index 6fb1eb979..84f8ded79 100644
--- a/jnosql-mongodb/src/main/java/org/eclipse/jnosql/databases/mongodb/communication/MongoDBDocumentManager.java
+++ b/jnosql-mongodb/src/main/java/org/eclipse/jnosql/databases/mongodb/communication/MongoDBDocumentManager.java
@@ -48,8 +48,8 @@
 
 /**
  * The mongodb implementation to {@link DatabaseManager} that does not support TTL methods
- * 
{@link MongoDBDocumentManager#insert(CommunicationEntity, Duration)}

- * 
Closing a {@link MongoDBDocumentManager} has no effect.
+ * {@link MongoDBDocumentManager#insert(CommunicationEntity, Duration)}
+ * Closing a {@link MongoDBDocumentManager} has no effect.
  */
 public class MongoDBDocumentManager implements DatabaseManager {
 
diff --git a/jnosql-ravendb/src/main/java/org/eclipse/jnosql/databases/ravendb/communication/RavenDBDocumentManager.java b/jnosql-ravendb/src/main/java/org/eclipse/jnosql/databases/ravendb/communication/RavenDBDocumentManager.java
index bc483bcac..2f1054bbf 100644
--- a/jnosql-ravendb/src/main/java/org/eclipse/jnosql/databases/ravendb/communication/RavenDBDocumentManager.java
+++ b/jnosql-ravendb/src/main/java/org/eclipse/jnosql/databases/ravendb/communication/RavenDBDocumentManager.java
@@ -45,7 +45,7 @@
 
 /**
  * The RavenDB implementation to {@link DatabaseManager} that does not support TTL methods
- * 
{@link RavenDBDocumentManager#insert(CommunicationEntity, Duration)}

+ * {@link RavenDBDocumentManager#insert(CommunicationEntity, Duration)}
  */
 public class RavenDBDocumentManager implements DatabaseManager {
 
diff --git a/jnosql-riak/src/main/java/org/eclipse/jnosql/databases/riak/communication/RiakBucketManagerFactory.java b/jnosql-riak/src/main/java/org/eclipse/jnosql/databases/riak/communication/RiakBucketManagerFactory.java
index d3566338a..01bbb552c 100644
--- a/jnosql-riak/src/main/java/org/eclipse/jnosql/databases/riak/communication/RiakBucketManagerFactory.java
+++ b/jnosql-riak/src/main/java/org/eclipse/jnosql/databases/riak/communication/RiakBucketManagerFactory.java
@@ -29,7 +29,7 @@
  * The riak implementation to {@link BucketManagerFactory} that returns {@link RiakBucketManager}
  * This implementation just has support to {@link RiakBucketManagerFactory#apply(String)}
  * So, these metdhos will returns {@link UnsupportedOperationException}
- * 
{@link BucketManagerFactory#getList(String, Class)}

+ * 
{@link BucketManagerFactory#getList(String, Class)}
  * 
{@link BucketManagerFactory#getSet(String, Class)}

  * 
{@link BucketManagerFactory#getQueue(String, Class)}

  * 
{@link BucketManagerFactory#getMap(String, Class, Class)}

diff --git a/jnosql-riak/src/main/java/org/eclipse/jnosql/databases/riak/communication/RiakKeyValueConfiguration.java b/jnosql-riak/src/main/java/org/eclipse/jnosql/databases/riak/communication/RiakKeyValueConfiguration.java
index 1104e0b61..432e61129 100644
--- a/jnosql-riak/src/main/java/org/eclipse/jnosql/databases/riak/communication/RiakKeyValueConfiguration.java
+++ b/jnosql-riak/src/main/java/org/eclipse/jnosql/databases/riak/communication/RiakKeyValueConfiguration.java
@@ -30,7 +30,7 @@
 
 /**
  * The riak implementation to {@link KeyValueConfiguration} that returns {@link RiakBucketManagerFactory}.
- * 
riak.host-: The prefix to host. eg: riak.server.host.1= host1

+ * riak.host-: The prefix to host. eg: riak.server.host.1= host1
  */
 public class RiakKeyValueConfiguration implements KeyValueConfiguration {
 
diff --git a/jnosql-solr/src/main/java/org/eclipse/jnosql/databases/solr/communication/SolrDocumentManager.java b/jnosql-solr/src/main/java/org/eclipse/jnosql/databases/solr/communication/SolrDocumentManager.java
index 1617d13e6..7d683a596 100644
--- a/jnosql-solr/src/main/java/org/eclipse/jnosql/databases/solr/communication/SolrDocumentManager.java
+++ b/jnosql-solr/src/main/java/org/eclipse/jnosql/databases/solr/communication/SolrDocumentManager.java
@@ -23,7 +23,7 @@
 
 /**
  * The solr implementation to {@link DatabaseManager} that does not support TTL methods
- * 
{@link DefaultSolrDocumentManager#insert(CommunicationEntity, Duration)}

+ * {@link DefaultSolrDocumentManager#insert(CommunicationEntity, Duration)}
  */
 public interface SolrDocumentManager extends DatabaseManager {
 
diff --git a/jnosql-tinkerpop/src/main/java/org/eclipse/jnosql/databases/tinkerpop/mapping/spi/CustomRepositoryGraphBean.java b/jnosql-tinkerpop/src/main/java/org/eclipse/jnosql/databases/tinkerpop/mapping/spi/CustomRepositoryGraphBean.java
index e32676b33..6a0eb0ab4 100644
--- a/jnosql-tinkerpop/src/main/java/org/eclipse/jnosql/databases/tinkerpop/mapping/spi/CustomRepositoryGraphBean.java
+++ b/jnosql-tinkerpop/src/main/java/org/eclipse/jnosql/databases/tinkerpop/mapping/spi/CustomRepositoryGraphBean.java
@@ -35,10 +35,10 @@
 /**
  * This class serves as a JNoSQL discovery bean for CDI extension, responsible for registering Custom Repository instances.
  * It extends {@link AbstractBean} and is parameterized with type {@code T} representing the repository type.
- * 

+ *
  * Upon instantiation, it initializes with the provided repository type, provider name, and qualifiers.
  * The provider name specifies the database provider for the repository.
- * 

+ *
  *
  * @param  the type of the repository
  * @see AbstractBean

From d8297b3f835960eb4f433f6c64ce5c6d9ccb832b Mon Sep 17 00:00:00 2001
From: Otavio Santana 
Date: Sun, 2 Mar 2025 05:22:58 +0000
Subject: [PATCH 32/39] docs: fix cql documentation

Signed-off-by: Otavio Santana 
---
 .../org/eclipse/jnosql/databases/cassandra/mapping/CQL.java   | 4 ----
 1 file changed, 4 deletions(-)

diff --git a/jnosql-cassandra/src/main/java/org/eclipse/jnosql/databases/cassandra/mapping/CQL.java b/jnosql-cassandra/src/main/java/org/eclipse/jnosql/databases/cassandra/mapping/CQL.java
index c37eb3065..38cf8d7bf 100644
--- a/jnosql-cassandra/src/main/java/org/eclipse/jnosql/databases/cassandra/mapping/CQL.java
+++ b/jnosql-cassandra/src/main/java/org/eclipse/jnosql/databases/cassandra/mapping/CQL.java
@@ -21,17 +21,13 @@
 
 /**
  * Annotation used to define a dynamic CQL query method in {@link CassandraRepository}.
- * 

  * Methods annotated with {@code @CQL} allow the execution of custom Cassandra Query Language (CQL) statements
  * within repository interfaces.
- * 

- * 

  * Example usage:
  * 
{@code
  * @CQL("SELECT * FROM users WHERE username = :username")
  * List findByUsername(@Param("username") String username);
  * }

- * 

  */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.METHOD)

From 635c7fcb0f5af05ade5e892ec4720ae559127837 Mon Sep 17 00:00:00 2001
From: Otavio Santana 
Date: Sun, 2 Mar 2025 05:24:26 +0000
Subject: [PATCH 33/39] docs: enhance couchbase repository

Signed-off-by: Otavio Santana 
---
 .../databases/couchbase/mapping/CouchbaseRepository.java      | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/jnosql-couchbase/src/main/java/org/eclipse/jnosql/databases/couchbase/mapping/CouchbaseRepository.java b/jnosql-couchbase/src/main/java/org/eclipse/jnosql/databases/couchbase/mapping/CouchbaseRepository.java
index 637f2bd24..794c2905e 100644
--- a/jnosql-couchbase/src/main/java/org/eclipse/jnosql/databases/couchbase/mapping/CouchbaseRepository.java
+++ b/jnosql-couchbase/src/main/java/org/eclipse/jnosql/databases/couchbase/mapping/CouchbaseRepository.java
@@ -19,12 +19,10 @@
 
 /**
  * A Couchbase-specific extension of {@link NoSQLRepository}.
- * 

  * This repository interface provides built-in CRUD operations and supports dynamic queries
  * using the {@link N1QL} annotation for executing Couchbase N1QL queries.
- * 

  *
- * 
Example Usage

+ * Example Usage
  * 
{@code
  * @Repository
  * interface UserRepository extends CouchbaseRepository {

From d5d59485e903c5ea8cd0af577091c29bdc35d6be Mon Sep 17 00:00:00 2001
From: Otavio Santana 
Date: Sun, 2 Mar 2025 05:25:05 +0000
Subject: [PATCH 34/39] docs: enhance coubhase template

Signed-off-by: Otavio Santana 
---
 .../jnosql/databases/couchbase/mapping/CouchbaseTemplate.java | 4 ----
 1 file changed, 4 deletions(-)

diff --git a/jnosql-couchbase/src/main/java/org/eclipse/jnosql/databases/couchbase/mapping/CouchbaseTemplate.java b/jnosql-couchbase/src/main/java/org/eclipse/jnosql/databases/couchbase/mapping/CouchbaseTemplate.java
index 9e2df226b..65b2e7a95 100644
--- a/jnosql-couchbase/src/main/java/org/eclipse/jnosql/databases/couchbase/mapping/CouchbaseTemplate.java
+++ b/jnosql-couchbase/src/main/java/org/eclipse/jnosql/databases/couchbase/mapping/CouchbaseTemplate.java
@@ -45,10 +45,8 @@ public interface CouchbaseTemplate extends DocumentTemplate {
 
     /**
      * Executes an N1QL query with named parameters and returns the query result.
-     * 

      * Example query:
      * {@code SELECT * FROM users WHERE status = $status}
-     * 

      *
      * @param        the entity type
      * @param n1qlQuery the N1QL query to execute
@@ -60,10 +58,8 @@ public interface CouchbaseTemplate extends DocumentTemplate {
 
     /**
      * Executes a plain N1QL query without parameters and returns the query result.
-     * 

      * Example query:
      * {@code SELECT * FROM users}
-     * 

      *
      * @param        the entity type
      * @param n1qlQuery the N1QL query to execute

From de3807373b62a8c07498bec6391afa6d474afe00 Mon Sep 17 00:00:00 2001
From: Otavio Santana 
Date: Sun, 2 Mar 2025 05:25:41 +0000
Subject: [PATCH 35/39] docs: removes h2 at N1SQL annotation

Signed-off-by: Otavio Santana 
---
 .../org/eclipse/jnosql/databases/couchbase/mapping/N1QL.java  | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/jnosql-couchbase/src/main/java/org/eclipse/jnosql/databases/couchbase/mapping/N1QL.java b/jnosql-couchbase/src/main/java/org/eclipse/jnosql/databases/couchbase/mapping/N1QL.java
index d623d0339..4219e2e36 100644
--- a/jnosql-couchbase/src/main/java/org/eclipse/jnosql/databases/couchbase/mapping/N1QL.java
+++ b/jnosql-couchbase/src/main/java/org/eclipse/jnosql/databases/couchbase/mapping/N1QL.java
@@ -22,12 +22,10 @@
 
 /**
  * Annotation used to define a dynamic N1QL query in {@link CouchbaseRepository}.
- * 

  * This annotation allows repository methods to be mapped to Couchbase N1QL queries.
  * Parameters can be provided using the {@link jakarta.data.repository.Param} annotation.
- * 

  *
- * 
Example Usage

+ * Example Usage
  * 
{@code
  * @Repository
  * interface ProductRepository extends CouchbaseRepository {

From fd8763bb33fcaeed4bfbae546294b7f2c8b9c7ee Mon Sep 17 00:00:00 2001
From: Otavio Santana 
Date: Sun, 2 Mar 2025 05:27:10 +0000
Subject: [PATCH 36/39] docs: fix hazelcast documentation

Signed-off-by: Otavio Santana 
---
 .../java/org/eclipse/jnosql/mapping/driver/ParamUtil.java     | 4 ++--
 .../databases/hazelcast/mapping/HazelcastRepository.java      | 2 --
 .../org/eclipse/jnosql/databases/hazelcast/mapping/Query.java | 2 --
 3 files changed, 2 insertions(+), 6 deletions(-)

diff --git a/jnosql-database-commons/src/main/java/org/eclipse/jnosql/mapping/driver/ParamUtil.java b/jnosql-database-commons/src/main/java/org/eclipse/jnosql/mapping/driver/ParamUtil.java
index d38f2f895..5de7259de 100644
--- a/jnosql-database-commons/src/main/java/org/eclipse/jnosql/mapping/driver/ParamUtil.java
+++ b/jnosql-database-commons/src/main/java/org/eclipse/jnosql/mapping/driver/ParamUtil.java
@@ -26,8 +26,8 @@
 /**
  * Utility class for extracting method parameters annotated with {@link Param} across all repository interfaces.
  *
- * 
This utility supports repositories using custom query annotations such as {@code @AQL}, {@code @Cypher},
- * and others, where parameters are annotated with {@link Param} to enable named parameter binding.

+ * This utility supports repositories using custom query annotations such as {@code @AQL}, {@code @Cypher},
+ * and others, where parameters are annotated with {@link Param} to enable named parameter binding.
  *
  * Example Usage:
  * 
{@code
diff --git a/jnosql-hazelcast/src/main/java/org/eclipse/jnosql/databases/hazelcast/mapping/HazelcastRepository.java b/jnosql-hazelcast/src/main/java/org/eclipse/jnosql/databases/hazelcast/mapping/HazelcastRepository.java
index 998357638..1adaf6706 100644
--- a/jnosql-hazelcast/src/main/java/org/eclipse/jnosql/databases/hazelcast/mapping/HazelcastRepository.java
+++ b/jnosql-hazelcast/src/main/java/org/eclipse/jnosql/databases/hazelcast/mapping/HazelcastRepository.java
@@ -20,10 +20,8 @@
 /**
  * A Hazelcast-specific extension of {@link NoSQLRepository}, providing
  * key-value data storage and retrieval using Hazelcast.
- * 

  * This repository interface allows for defining custom queries using
  * {@link Query} annotations and enables CRUD operations for entities.
- * 

  *
  * Example usage:
  * 
diff --git a/jnosql-hazelcast/src/main/java/org/eclipse/jnosql/databases/hazelcast/mapping/Query.java b/jnosql-hazelcast/src/main/java/org/eclipse/jnosql/databases/hazelcast/mapping/Query.java
index 0ecfb37f8..a9e28f889 100644
--- a/jnosql-hazelcast/src/main/java/org/eclipse/jnosql/databases/hazelcast/mapping/Query.java
+++ b/jnosql-hazelcast/src/main/java/org/eclipse/jnosql/databases/hazelcast/mapping/Query.java
@@ -21,10 +21,8 @@
 
 /**
  * Annotation for defining a dynamic query method in Hazelcast repositories.
- * 

  * This annotation allows developers to specify Hazelcast query expressions
  * directly in repository methods.
- * 

  *
  * Example usage:
  * 

From dcd57f401db185411c5dd28017111ffefccccd15 Mon Sep 17 00:00:00 2001
From: Otavio Santana 
Date: Sun, 2 Mar 2025 05:28:09 +0000
Subject: [PATCH 37/39] docs: enhance documentation at orientdb template

Signed-off-by: Otavio Santana 
---
 .../databases/orientdb/mapping/OrientDBTemplate.java      | 8 --------
 1 file changed, 8 deletions(-)

diff --git a/jnosql-orientdb/src/main/java/org/eclipse/jnosql/databases/orientdb/mapping/OrientDBTemplate.java b/jnosql-orientdb/src/main/java/org/eclipse/jnosql/databases/orientdb/mapping/OrientDBTemplate.java
index a84fb75ee..a44f8489e 100644
--- a/jnosql-orientdb/src/main/java/org/eclipse/jnosql/databases/orientdb/mapping/OrientDBTemplate.java
+++ b/jnosql-orientdb/src/main/java/org/eclipse/jnosql/databases/orientdb/mapping/OrientDBTemplate.java
@@ -33,7 +33,6 @@ public interface OrientDBTemplate extends DocumentTemplate {
 
     /**
      * Executes a native OrientDB SQL query.
-     * 

      * This method allows running SQL queries with positional parameters.
      * Example usage:
      * 
@@ -41,7 +40,6 @@ public interface OrientDBTemplate extends DocumentTemplate {
      * Stream users = template.sql("SELECT FROM User WHERE age > ?", 30);
      * }
      * 

-     * 

      *
      * @param     the expected result type
      * @param query  the SQL query string
@@ -53,7 +51,6 @@ public interface OrientDBTemplate extends DocumentTemplate {
 
     /**
      * Executes a native OrientDB SQL query with named parameters.
-     * 

      * Example usage:
      * 
      * {@code
@@ -61,7 +58,6 @@ public interface OrientDBTemplate extends DocumentTemplate {
      * Stream users = template.sql("SELECT FROM User WHERE age > :age", params);
      * }
      * 

-     * 

      *
      * @param     the expected result type
      * @param query  the SQL query string
@@ -73,7 +69,6 @@ public interface OrientDBTemplate extends DocumentTemplate {
 
     /**
      * Executes a live query in OrientDB.
-     * 

      * A live query listens for real-time changes in the database and triggers callbacks
      * for each event that occurs (insert, update, delete).
      * Example usage:
@@ -82,7 +77,6 @@ public interface OrientDBTemplate extends DocumentTemplate {
      * template.live(selectQuery, event -> System.out.println("Update: " + event));
      * }
      * 

-     * 

      *
      * @param       the expected result type
      * @param query    the query definition using {@link SelectQuery}
@@ -93,7 +87,6 @@ public interface OrientDBTemplate extends DocumentTemplate {
 
     /**
      * Executes a live query in OrientDB using a SQL string.
-     * 

      * The query must include the "LIVE" keyword.
      * Example usage:
      * 
@@ -101,7 +94,6 @@ public interface OrientDBTemplate extends DocumentTemplate {
      * template.live("LIVE SELECT FROM User", event -> System.out.println("User changed: " + event));
      * }
      * 

-     * 

      *
      * @param       the expected result type
      * @param query    the SQL query string containing the "LIVE" keyword

From 97b3a97c98d0ef0c9f54a7d813fadc02bb9c24ec Mon Sep 17 00:00:00 2001
From: Otavio Santana 
Date: Sun, 2 Mar 2025 05:28:44 +0000
Subject: [PATCH 38/39] docs: enhance documentation at sql hazelcast

Signed-off-by: Otavio Santana 
---
 .../java/org/eclipse/jnosql/databases/orientdb/mapping/SQL.java | 2 --
 1 file changed, 2 deletions(-)

diff --git a/jnosql-orientdb/src/main/java/org/eclipse/jnosql/databases/orientdb/mapping/SQL.java b/jnosql-orientdb/src/main/java/org/eclipse/jnosql/databases/orientdb/mapping/SQL.java
index 6b160f52b..d9c8ac53b 100644
--- a/jnosql-orientdb/src/main/java/org/eclipse/jnosql/databases/orientdb/mapping/SQL.java
+++ b/jnosql-orientdb/src/main/java/org/eclipse/jnosql/databases/orientdb/mapping/SQL.java
@@ -21,10 +21,8 @@
 
 /**
  * Annotation for defining dynamic SQL queries in OrientDB repositories.
- * 

  * This annotation is used on methods within {@link OrientDBCrudRepository} to execute
  * custom SQL queries directly on OrientDB.
- * 

  *
  * 
Example usage:

  * 

From 7ca340f848db812f31396a06db4af4b067617563 Mon Sep 17 00:00:00 2001
From: Otavio Santana 
Date: Sun, 2 Mar 2025 05:36:50 +0000
Subject: [PATCH 39/39] docs: enhance hazelcast templat

Signed-off-by: Otavio Santana 
---
 .../databases/hazelcast/mapping/HazelcastTemplate.java    | 8 --------
 1 file changed, 8 deletions(-)

diff --git a/jnosql-hazelcast/src/main/java/org/eclipse/jnosql/databases/hazelcast/mapping/HazelcastTemplate.java b/jnosql-hazelcast/src/main/java/org/eclipse/jnosql/databases/hazelcast/mapping/HazelcastTemplate.java
index 37f1f5e13..86e580b63 100644
--- a/jnosql-hazelcast/src/main/java/org/eclipse/jnosql/databases/hazelcast/mapping/HazelcastTemplate.java
+++ b/jnosql-hazelcast/src/main/java/org/eclipse/jnosql/databases/hazelcast/mapping/HazelcastTemplate.java
@@ -23,10 +23,8 @@
 /**
  * A specialized {@link KeyValueTemplate} for Hazelcast,
  * providing methods to execute queries using SQL-like expressions and predicates.
- * 

  * This template facilitates querying key-value structures stored in a Hazelcast instance.
  * It supports both SQL-like queries with named parameters and Hazelcast-specific predicates.
- * 

  *
  * Example usage:
  * 
@@ -51,9 +49,7 @@ public interface HazelcastTemplate extends KeyValueTemplate {
 
     /**
      * Executes a Hazelcast query using SQL-like syntax.
-     * 

      * The query should follow Hazelcast's SQL-like query syntax for key-value stores.
-     * 

      *
      * @param    the entity type
      * @param query the SQL-like query string
@@ -64,14 +60,12 @@ public interface HazelcastTemplate extends KeyValueTemplate {
 
     /**
      * Executes a Hazelcast query with named parameters.
-     * 

      * Example usage:
      * 
      * {@code
      * Collection movies = hazelcastTemplate.sql("name = :name", Map.of("name", "The Matrix"));
      * }
      * 

-     * 

      *
      * @param     the entity type
      * @param query  the SQL-like query string
@@ -83,10 +77,8 @@ public interface HazelcastTemplate extends KeyValueTemplate {
 
     /**
      * Executes a Hazelcast query using a {@link Predicate}.
-     * 

      * The predicate-based approach is useful for filtering key-value pairs
      * based on specific criteria.
-     * 

      *
      * @param        the key type
      * @param        the value type