Merge pull request #312 from eclipse-jnosql/documentation-database

Enhance documentation

Author: otaviojava

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
 

jnosql-arangodb/src/main/java/org/eclipse/jnosql/databases/arangodb/mapping/AQL.java

@@ -20,11 +20,33 @@
 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:
+ * <pre>{@code
+ * @AQL("FOR p IN Person RETURN p")
+ * List<Person> findAll();
+ * }</pre>
+ *
+ *Parameterized query:
+ * <pre>{@code
+ * @AQL("FOR p IN Person FILTER p.name == @name RETURN p")
+ * List<Person> findByName(@Param("name") String name);
+ * }</pre>
+ *
+ * @see ArangoDBRepository
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.METHOD)
 public @interface AQL {
 
+    /**
+     * The AQL query string to be executed.
+     *
+     * @return the AQL query
+     */
     String value();
 }

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<T> result;
-            Map<String, Object> params = ParamUtil.getParams(args, method);
+            Map<String, Object> params = ParamUtil.INSTANCE.getParams(args, method);
             if (params.isEmpty()) {
                 result = template.aql(aql.value(), emptyMap());
             } else {

jnosql-arangodb/src/main/java/org/eclipse/jnosql/databases/arangodb/mapping/ArangoDBRepository.java

@@ -19,9 +19,25 @@
 
 
 /**
- * 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:
+ * <pre>{@code
+ * @Repository
+ * public interface PersonRepository extends ArangoDBRepository<Person, String> {
+ *
+ *     @AQL("FOR p IN Person RETURN p")
+ *     List<Person> findAll();
+ *
+ *     @AQL("FOR p IN Person FILTER p.name == @name RETURN p")
+ *     List<Person> findByName(@Param("name") String name);
+ * }
+ * }</pre>
+ *
  * @param <T> the entity type
- * @param <K> the id entity type
+ * @param <K> the entity ID type
+ * @see AQL
  */
 public interface ArangoDBRepository<T, K> extends NoSQLRepository<T, K> {
 }

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).
      *
-     * <p>Example query: {@code FOR u IN users FILTER u.status == @status RETURN u}</p>
+     * <p>Example query:</p>
+     * <pre>{@code
+     * FOR u IN users FILTER u.status == @status RETURN u
+     * }</pre>
      *
-     * <p>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.</p>
+     * <p>The conversion of query results to entity objects is handled by Eclipse JNoSQL,
+     * applying all supported annotations.</p>
      *
-     * @param <T>    the entity class
-     * @param query  the AQL query
-     * @param params the named parameters for the query
+     * @param <T>    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}
      */
     <T> Stream<T> aql(String query, Map<String, Object> params);
 
     /**
-     * Executes an ArangoDB query using the ArangoDB Query Language (AQL).
+     * Executes an ArangoDB query using AQL with direct serialization via ArangoDB.
      *
-     * <p>Example query: {@code FOR u IN users FILTER u.status == @status RETURN u}</p>
+     * <p>Example query:</p>
+     * <pre>{@code
+     * FOR u IN users FILTER u.status == @status RETURN u
+     * }</pre>
      *
-     * <p>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.</p>
+     * <p>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.</p>
      *
-     * @param query  the AQL query
-     * @param params the named parameters for the query
-     * @param type   the type of the result
-     * @param <T>    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 <T>    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}
      */
     <T> Stream<T> aql(String query, Map<String, Object> params, Class<T> 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.
      *
-     * <p>Example query: {@code FOR u IN users FILTER u.status == @status RETURN u}</p>
+     * <p>Example query:</p>
+     * <pre>{@code
+     * FOR u IN users FILTER u.status == @status RETURN u
+     * }</pre>
      *
-     * <p>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.</p>
+     * <p>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.</p>
      *
-     * @param query the AQL query
-     * @param type  the type of the result
-     * @param <T>   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 <T>   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}
      */
     <T> Stream<T> aql(String query, Class<T> type);
 }

jnosql-arangodb/src/main/java/org/eclipse/jnosql/databases/arangodb/mapping/Param.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;

jnosql-arangodb/src/main/java/org/eclipse/jnosql/databases/arangodb/mapping/ParamUtil.java

@@ -20,14 +20,21 @@
 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:
+ * <pre>{@code
+ * @CQL("SELECT * FROM users WHERE username = :username")
+ * List<User> findByUsername(@Param("username") String username);
+ * }</pre>
  */
 @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
      */