Replace JDQL with JCQL

README.adoc

@@ -132,11 +132,11 @@ List<Product> found = products.findAll(
 );
 ----
 
-== Jakarta Data Query Language (JDQL)
+== Jakarta Common Query Language (JCQL)
 
-Jakarta Data introduces the Jakarta Data Query Language (JDQL), a streamlined query language designed to specify the semantics of query methods within Jakarta Data repositories. Utilizing the `@Query` annotation, JDQL allows developers to define queries straightforwardly and robustly.
+A query language for relational and non-relational data, Jakarta Common Query Language (JCQL), is defined by the Jakarta Query specification. Jakarta Data repository methods can be annotated `@Query` to indicate that the method runs a given JCQL query upon invocation of the method.
 
-JDQL is conceptualized as a subset of the Jakarta Persistence Query Language (JPQL). It inherits its syntax and functionality while being specifically tailored to accommodate the broad spectrum of data storage technologies supported by Jakarta Data. This design approach ensures that JDQL remains compatible with JPQL yet simplifies its implementation across diverse data stores.
+JCQL is conceptualized as a subset of the Jakarta Persistence Query Language (JPQL). It inherits its syntax and functionality while being specifically tailored to accommodate the broad spectrum of data storage technologies supported by Jakarta Data. This design approach ensures that JCQL remains compatible with JPQL yet simplifies its implementation across diverse data stores.
 
 [source,java]
 ----
@@ -153,7 +153,7 @@ public interface BookRepository extends BasicRepository<Book, UUID> {
 }
 ----
 
-*JDQL* supports three primary types of statements, reflecting the core operations typically required for data manipulation and retrieval in applications:
+*JCQL* supports three primary types of statements, reflecting the core operations typically required for data manipulation and retrieval in applications:
 
 * *Select Statements*: Facilitate data retrieval from a data store, allowing for the specification of criteria to filter results.
 * *Update Statements*: This option enables the modification of existing records in the data store based on specified criteria.

api/src/main/java/jakarta/data/page/CursoredPage.java

@@ -18,6 +18,7 @@
 package jakarta.data.page;
 
 import jakarta.data.repository.OrderBy;
+import jakarta.data.repository.Query;
 import jakarta.data.Order;
 import jakarta.data.Sort;
 
@@ -109,9 +110,15 @@
  *
  * <h2>Cursor-based Pagination with {@code @Query}</h2>
  *
+ * <p>The {@link Query} annotation from Jakarta Data and the similar
+ * {@code jakarta.persistence.StaticQuery} annotation from Jakarta Persistence
+ * allow the application to supply a Jakarta Common Query Language (JCQL) or
+ * Jakarta Persistence Query Language (JPQL) query for the repository method
+ * to perform.</p>
+ *
  * <p>Cursor-based pagination involves generating and appending additional
  * restrictions involving the key elements to the {@code WHERE} clause of the
- * query. For this to be possible, a user-provided JDQL or JPQL query must end
+ * query. For this to be possible, a user-provided JCQL or JPQL query must end
  * with a {@code WHERE} clause to which additional conditions may be
  * appended. Cursor-pagination is not available for native SQL queries and
  * some JPQL queries.</p>

api/src/main/java/jakarta/data/repository/OrderBy.java

@@ -72,9 +72,9 @@
  * <ul>
  * <li>the <em>Query by Method Name</em> {@code OrderBy} keyword in its
  *     name,</li>
- * <li>a {@link Query} or {@link jakarta.persistence.query.StaticQuery}
+ * <li>a {@link Query} or {@code jakarta.persistence.query.StaticQuery}
  *     annotation specifying a query with an {@code ORDER BY} clause, nor</li>
- * <li>a {@link jakarta.persistence.query.StaticNativeQuery} annotation.</li>
+ * <li>a {@code jakarta.persistence.query.StaticNativeQuery} annotation.</li>
  * </ul>
  * <p>A Jakarta Data provider is permitted to reject such a repository
  * method declaration at compile time or to implement the method to
@@ -85,6 +85,7 @@
  * or a more specific subclass if the database is incapable of
  * ordering with the requested sort criteria.</p>
  */
+// TODO replace @code with @link to StaticQuery/StaticNativeQuery once Persistence 4.0 M1 is available
 @Repeatable(OrderBy.List.class)
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.METHOD)

api/src/main/java/jakarta/data/repository/Query.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022,2025 Contributors to the Eclipse Foundation
+ * Copyright (c) 2022,2026 Contributors to the Eclipse Foundation
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -30,16 +30,17 @@
 
 /**
  * <p>Annotates a repository method as a query method, specifying a query
- * written in Jakarta Data Query Language (JDQL) or in Jakarta Persistence
- * Query Language (JPQL). A Jakarta Data provider is not required to support
+ * written in Jakarta Common Query Language (JCQL) or in Jakarta Persistence
+ * Query Language (JPQL). JCQL and JPQL are defined by the Jakarta Query
+ * specification. A Jakarta Data provider is not required to support
  * the complete JPQL language, which targets relational data stores. However,
  * a given provider might offer features of JPQL which go beyond the subset
- * required by JDQL, or might even offer vendor-specific extensions to JDQL
+ * required by JCQL, or might even offer vendor-specific extensions to JCQL
  * which target particular capabilities of the target data store technology.
  * Such extensions come with no guarantee of portability between providers,
  * nor between databases.</p>
  *
- * <p>The required {@link #value} member specifies the JDQL or JPQL query as
+ * <p>The required {@link #value} member specifies the JCQL or JPQL query as
  * a string.</p>
  *
  * <p>For {@code select} statements, the return type of the query method must
@@ -72,14 +73,14 @@
  *     </li>
  * </ul>
  *
- * <p>Compared to SQL, JDQL allows an abbreviated syntax for {@code select}
+ * <p>Compared to SQL, JCQL allows an abbreviated syntax for {@code select}
  * statements:</p>
  * <ul>
- * <li>The {@code from} clause is optional in JDQL. When it is missing, the
+ * <li>The {@code from} clause is optional in JCQL. When it is missing, the
  *     queried entity is determined by the return type of the repository
  *     method, or, if the return type is not an entity type, by the primary
  *     entity type of the repository.</li>
- * <li>The {@code select} clause is optional in both JDQL and JPQL. When it
+ * <li>The {@code select} clause is optional in both JCQL and JPQL. When it
  *     is missing, the query returns the queried entity.</li>
  * </ul>
  *
@@ -119,11 +120,11 @@
  * @Repository
  * public interface People extends CrudRepository<Person, Long> {
  *
- *     // JDQL with positional parameters
+ *     // JCQL with positional parameters
  *     @Query("where firstName = ?1 and lastName = ?2")
  *     List<Person> byName(String first, String last);
  *
- *     // JDQL with a named parameter
+ *     // JCQL with a named parameter
  *     @Query("where firstName || ' ' || lastName like :pattern")
  *     List<Person> byName(String pattern);
  *
@@ -177,7 +178,7 @@
 
     /**
      * <p>Specifies the query executed by the annotated repository method,
-     * in JDQL or JPQL.</p>
+     * in JCQL or JPQL.</p>
      *
      * <p>If the annotated repository method accepts other forms of sorting
      * (such as a parameter of type {@link Sort}), it is the responsibility of

api/src/main/java/jakarta/data/spi/expression/literal/NumericLiteral.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2025 Contributors to the Eclipse Foundation
+ * Copyright (c) 2025,2026 Contributors to the Eclipse Foundation
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -53,7 +53,7 @@ static <N extends Number & Comparable<N>> NumericLiteral<N> of(N value) {
     // Integer value, but there was no indication of this given that both
     // convert to the same String. We could switch the output to include a
     // suffix, such as 'I' at the end, but the downside of that would be not
-    // matching JDQL.
+    // matching JCQL.
     /**
      * <p>Returns a {@code String} representing the literal numeric value.</p>
      *

api/src/main/java/module-info.java

@@ -451,10 +451,11 @@
  * Stream<Person> livingInCity(String address_city);
  * </pre>
  *
- * <h2>JDQL query methods</h2>
+ * <h2>Methods annotated {@code @Query}</h2>
  *
- * <p>The {@link Query} annotation specifies that a method executes a query written
- * in Jakarta Data Query Language (JDQL) or Jakarta Persistence Query Language (JPQL).
+ * <p>The {@link Query} annotation specifies that a method executes a query
+ * written in Jakarta Common Query Language (JCQL) or Jakarta Persistence
+ * Query Language (JPQL), which are defined by the Jakarta Query specification.
  * A Jakarta Data provider is not required to support the complete JPQL language,
  * which targets relational data stores.</p>
  *
@@ -892,7 +893,7 @@
  * a <em>special parameter</em> of type {@link Restriction}.</p>
  *
  * <p>Special parameters occur after parameters related to query conditions
- * and JDQL query parameters. Special parameters enable limits, pagination,
+ * and JCQL query parameters. Special parameters enable limits, pagination,
  * sorting, and restrictions to be determined at runtime.</p>
  *
  * <h3>Limits</h3>