{@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();
}
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{@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 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.
* - * @paramExample 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 - * @paramExample 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{@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
*/
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 MapExample 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 + * Example usage: + *
{@code
+ * template.cql("SELECT * FROM users WHERE id = :id", Map.of("id", 1));
+ * }
*
- * @param {@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 + * 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 {@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();
}
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..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;
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..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
@@ -19,15 +19,30 @@
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();
}
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..5de7259de
--- /dev/null
+++ b/jnosql-database-commons/src/main/java/org/eclipse/jnosql/mapping/driver/ParamUtil.java
@@ -0,0 +1,81 @@
+/*
+ * 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;
+
+/**
+ * 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}
+ */
+ public Map hbase.family.n: as prefix to add family, eg: hbase,family.1=column-family {@link HBaseColumnManager#insert(org.eclipse.jnosql.communication.semistructured.CommunicationEntity, Duration)} {@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-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
+ * This interface allows interaction with OrientDB as a document-oriented NoSQL database,
+ * supporting standard CRUD operations and custom queries using the {@link SQL} annotation.
+ * Example usage:
+ * This template provides methods for executing native SQL queries,
+ * live queries, and queries with named parameters.
+ * Example usage: {@link RavenDBDocumentManager#insert(CommunicationEntity, Duration)} {@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)} riak.host-: The prefix to host. eg: riak.server.host.1= host1 {@link DefaultSolrDocumentManager#insert(CommunicationEntity, Duration)}
+ *
* Upon instantiation, it initializes with the provided repository type, provider name, and qualifiers.
* The provider name specifies the database provider for the repository.
- *
+ * {@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
+ *
+ * @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
+ * {@code
+ * @Repository
+ * interface ProductRepository extends HazelcastRepository
*
* @param
+ * {@code
+ * @Inject
+ * private HazelcastTemplate hazelcastTemplate;
+ *
+ * // Query using SQL-like syntax
+ * Collection
+ *
+ * @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
+ * {@code
+ * Collection
*
- * @param query the query
* @param
+ * {@code
+ * @Repository
+ * interface PersonRepository extends HazelcastRepository
*/
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface Query {
+ /**
+ * The Hazelcast query expression.
+ *
+ * @return the query string to be executed
+ */
String value();
}
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
+ * {@code
+ * @Repository
+ * public interface UserRepository extends OrientDBCrudRepository
+ *
+ * @param
+ * {@code
+ * Stream
*
- * @param query the query
- * @param params the params
- * @return the query result
- * @throws NullPointerException when either query or params are null
+ * @param
+ * {@code
+ * Map
*
- * @param query the query
- * @param params the params
- * @return the query result
- * @throws NullPointerException when either query or params are null
+ * @param
+ * {@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
+ * {@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
+ * {@code
+ * @SQL("SELECT FROM User WHERE age > :age")
+ * List
*/
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface SQL {
+ /**
+ * Defines the SQL query to be executed.
+ *
+ * @return the SQL query string
+ */
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;
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
- *