other types of comparisons for parameter based automatic query

api/src/main/java/jakarta/data/Limit.java

@@ -33,12 +33,15 @@
  * For example,</p>
  *
  * <pre>
- * Product[] findByNameLike(String namePattern, Limit limit, Sort&lt;?&gt;... sorts);
+ * &#64;Find
+ * Product[] named(&#64;By(_Product.NAME) &#64;Is(LIKE) &#64;IgnoreCase String namePattern,
+ *                 Limit limit,
+ *                 Sort&lt;Product&gt;... sorts);
  * 
  * ...
- * mostExpensive50 = products.findByNameLike(pattern, Limit.of(50), Sort.desc("price"));
+ * mostExpensive50 = products.named(pattern, Limit.of(50), Sort.desc("price"));
  * ...
- * secondMostExpensive50 = products.findByNameLike(pattern, Limit.range(51, 100), Sort.desc("price"));
+ * secondMostExpensive50 = products.named(pattern, Limit.range(51, 100), Sort.desc("price"));
  * </pre>
  *
  * <p>A repository method may not be declared with:

api/src/main/java/jakarta/data/metamodel/restrict/Operator.java

@@ -27,14 +27,23 @@ public enum Operator {
     LIKE,
     NOT_EQUAL,
     NOT_IN,
-    NOT_LIKE;
+    NOT_LIKE,
+    NOT_PREFIXED,
+    NOT_SUBSTRINGED,
+    NOT_SUFFIXED,
+    PREFIXED,
+    SUBSTRINGED,
+    SUFFIXED;
 
     /**
      * Representation of the operator as it appears in query language.
      * For example, {@link #GREATER_THAN} is represented as {@code >}
      * in query langugae.
      *
      * @return the representation of the operator in query language.
+     *         For operators that have a more complex representation in
+     *         query language, this method returns the {@link #name()}
+     *         of the operator.
      */
     String asQueryLanguage() {
         return switch (this) {
@@ -48,6 +57,12 @@ String asQueryLanguage() {
             case NOT_EQUAL -> "<>";
             case NOT_IN -> "NOT IN";
             case NOT_LIKE -> "NOT LIKE";
+            case NOT_PREFIXED -> NOT_PREFIXED.name();
+            case NOT_SUBSTRINGED -> NOT_SUBSTRINGED.name();
+            case NOT_SUFFIXED -> NOT_SUFFIXED.name();
+            case PREFIXED -> PREFIXED.name();
+            case SUBSTRINGED -> SUBSTRINGED.name();
+            case SUFFIXED -> SUFFIXED.name();
         };
     }
 
@@ -68,6 +83,12 @@ Operator negate() {
             case NOT_EQUAL -> EQUAL;
             case NOT_IN -> IN;
             case NOT_LIKE -> LIKE;
+            case NOT_PREFIXED -> PREFIXED;
+            case NOT_SUBSTRINGED -> SUBSTRINGED;
+            case NOT_SUFFIXED -> SUFFIXED;
+            case PREFIXED -> NOT_PREFIXED;
+            case SUBSTRINGED -> NOT_SUBSTRINGED;
+            case SUFFIXED -> NOT_SUFFIXED;
         };
     }
 }

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

@@ -55,23 +55,26 @@
  * query parameters) of type {@link PageRequest}, for example:</p>
  *
  * <pre>
- * &#64;OrderBy("lastName")
- * &#64;OrderBy("firstName")
- * &#64;OrderBy("id")
- * CursoredPage&lt;Employee&gt; findByHoursWorkedGreaterThan(int hours, PageRequest pageRequest);
+ * &#64;Find
+ * &#64;OrderBy(_Employee.LASTNAME)
+ * &#64;OrderBy(_Employee.FIRSTNAME)
+ * &#64;OrderBy(_Employee.ID)
+ * CursoredPage&lt;Employee&gt; withOvertime(
+ *         &#64;By(_Employee.HOURSWORKED) &#64;Is(GREATER_THAN) int fullTimeHours,
+ *         PageRequest pageRequest);
  * </pre>
  *
  * <p>In initial page may be requested using an offset-based page request:</p>
  *
  * <pre>
- * page = employees.findByHoursWorkedGreaterThan(1500, PageRequest.ofSize(50));
+ * page = employees.withOvertime(40, PageRequest.ofSize(50));
  * </pre>
  *
  * <p>The next page may be requested relative to the end of the current page,
  * as follows:</p>
  *
  * <pre>
- * page = employees.findByHoursWorkedGreaterThan(1500, page.nextPageRequest());
+ * page = employees.withOvertime(40, page.nextPageRequest());
  * </pre>
  *
  * <p>Here, the instance of {@link PageRequest} returned by
@@ -92,7 +95,7 @@
  *         PageRequest.ofPage(5)
  *                    .size(50)
  *                    .afterCursor(Cursor.forKey(emp.lastName, emp.firstName, emp.id));
- * page = employees.findByHoursWorkedGreaterThan(1500, pageRequest);
+ * page = employees.withOvertime(40, pageRequest);
  * </pre>
  *
  * <p>By making the query for the next page relative to observed values,

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

@@ -37,20 +37,25 @@
  * example:</p>
  *
  * <pre>
+ * &#64;Find
  * &#64;OrderBy("age")
  * &#64;OrderBy("ssn")
- * Person[] findByAgeBetween(int minAge, int maxAge, PageRequest pageRequest);
+ * Person[] agedBetween(&#64;By("age") &#64;Is(GREATER_THAN_EQUAL) int minAge,
+ *                      &#64;By("age") &#64;Is(LESS_THAN_EQUAL) int maxAge,
+ *                      PageRequest pageRequest);
  * </pre>
  *
  * <p>This method might be called as follows:</p>
  *
  * <pre>
- * var page = people.findByAgeBetween(35, 59,
+ * var page = people.agedBetween(
+ *                35, 59,
  *                PageRequest.ofSize(100));
  * var results = page.content();
  * ...
  * while (page.hasNext()) {
- *     page = people.findByAgeBetween(35, 59,
+ *     page = people.agedBetween(
+ *                35, 59,
  *                page.nextPageRequest().withoutTotal());
  *     results = page.content();
  *   ...

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

@@ -33,7 +33,10 @@
  *     to the unique identifier attribute.
  * </ul>
  * <p>Arguments to the annotated parameter are compared to values of the
- * mapped attribute.</p>
+ * mapped attribute. The equality comparison is used by default.<p>
+ *
+ * <p>For other types of basic comparisons, include the {@link Is} annotation.</p>
+ *
  * <p>The attribute name may be a compound name like {@code address.city}.</p>
  *
  * <p>For example, for a {@code Person} entity with attributes {@code ssn},

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

@@ -0,0 +1,60 @@
+/*
+ * Copyright (c) 2024,2025 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.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package jakarta.data.repository;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import jakarta.data.metamodel.restrict.Operator;
+
+/**
+ * <p>Annotates a parameter of a repository {@link Find} or {@link Delete} method,
+ * indicating that a persistent field should be compared ignoring case.
+ * The {@link By} annotation can be used on the same parameter to identify the
+ * persistent field. Otherwise, if the {@code -parameters} compile option is
+ * enabled, the the persistent field is inferred by matching the name of the
+ * method parameter. The {@link Operator#EQUAL EQUAL} comparison is assumed
+ * unless the {@link Is} annotation is used on the same parameter to choose a
+ * different type of comparison.</p>
+ *
+ * <p>For example,</p>
+ *
+ * <pre>
+ * &#64;Repository
+ * public interface People extends BasicRepository&lt;Person, Long&gt; {
+ *
+ *     // Find all Person entities where the lastName matches the respective value
+ *     // ignoring case.
+ *     &#64;Find
+ *     List&lt;Person&gt; withSurname(&#64;By(_Person.LASTNAME) &#64;IgnoreCase String surname);
+ *
+ *     // Find a page of Person entities where the lastName field begins with the
+ *     // supplied prefix, ignoring case.
+ *     &#64;Find
+ *     Page&lt;Person&gt; withSurnamePrefix(&#64;By(_Product.LASTNAME) &#64;Is(PREFIXED) &#64;IgnoreCase String prefix,
+ *                                    PageRequest pagination,
+ *                                    Order&lt;Person&gt; order);
+ * }
+ * </pre>
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.PARAMETER)
+public @interface IgnoreCase {
+}

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

@@ -0,0 +1,89 @@
+/*
+ * Copyright (c) 2024,2025 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.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package jakarta.data.repository;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import jakarta.data.metamodel.restrict.Operator;
+
+/**
+ * <p>Annotates a parameter of a repository {@link Find} or {@link Delete} method,
+ * indicating how a persistent field is compared against the parameter's value.
+ * The {@link By} annotation can be used on the same parameter to identify the
+ * persistent field. Otherwise, if the {@code -parameters} compile option is
+ * enabled, the the persistent field is inferred by matching the name of the
+ * method parameter.</p>
+ *
+ * <p>For example,</p>
+ *
+ * <pre>
+ * &#64;Repository
+ * public interface Products extends CrudRepository&lt;Product, Long&gt; {
+ *
+ *     // Find all Product entities where the price field is less than a maximum value.
+ *     &#64;Find
+ *     List&lt;Product&gt; pricedBelow(&#64;By(_Product.PRICE) &#64;Is(LESS_THAN) float max);
+ *
+ *     // Find a page of Product entities where the name field matches a pattern, ignoring case.
+ *     &#64;Find
+ *     Page&lt;Product&gt; search(&#64;By(_Product.NAME) &#64;Is(LIKE) &#64;IgnoreCase String pattern,
+ *                          PageRequest pagination,
+ *                          Order&lt;Product&gt; order);
+ *
+ *     // Remove Product entities with any of the unique identifiers listed.
+ *     &#64;Delete
+ *     void remove(&#64;By(ID) &#64;Is(IN) List&lt;Long&gt; productIds);
+ * }
+ * </pre>
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.PARAMETER)
+public @interface Is {
+
+    /**
+     * <p>The type of comparison operation to use when comparing a persistent
+     * field against a value that is supplied to a repository method..</p>
+     *
+     * <p>The following example compares the year a person was born against
+     * a minimum and maximum year that are supplied as parameters to a repository
+     * method:</p>
+     *
+     * <pre>
+     * &#64;Find
+     * &#64;OrderBy(_Person.YEAR_BORN)
+     * List&lt;Person&gt; bornWithin(&#64;By(_Person.YEAR_BORN) &#64;Is(GREATER_THAN_EQUAL) float minYear,
+     *                         &#64;By(_Person.YEAR_BORN) &#64;Is(LESS_THAN_EQUAL) float maxYear);
+     * </pre>
+     *
+     * <p>The default comparison operation is the {@linkplain Operator#EQUAL equality}
+     * comparison.</p>
+     *
+     * <p>For concise code, it can be convenient for a repository interface to
+     * statically import one or more constants from this class. For example:</p>
+     *
+     * <pre>
+     * import static jakarta.data.metamodel.restrict.Operator.*;
+     * </pre>
+     *
+     * @return the type of comparison operation.
+     */
+    Operator value() default Operator.EQUAL;
+}

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

@@ -62,8 +62,9 @@
  * <p>The default sort order is ascending. The {@code descending} member can be
  * used to specify the sort direction.</p>
  * <pre>
- * &#64;OrderBy(value = "price", descending = true)
- * {@code Stream<Product>} findByPriceLessThanEqual(double maxPrice);
+ * &#64;Find
+ * &#64;OrderBy(value = _Product.PRICE, descending = true)
+ * {@code Stream<Product>} pricedBelow(&#64;By(_Product.PRICE) &#64;Is(LESS_THAN) double maxPrice);
  * </pre>
  *
  * <p>A repository method with an {@code @OrderBy} annotation must not
@@ -115,8 +116,9 @@
      * <p>For example,</p>
      *
      * <pre>
+     * &#64;Find
      * &#64;OrderBy("age")
-     * Stream&lt;Person&gt; findByLastName(String lastName);
+     * Stream&lt;Person&gt; withLastName(&#64;By("lastName") &#64;IgnoreCase String surname);
      * </pre>
      *
      * @return entity attribute name.

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

@@ -37,8 +37,9 @@
  * @Repository
  * public interface Products extends DataRepository<Product, Long> {
  *
+ *     @Find
  *     @OrderBy("price")
- *     List<Product> findByNameLike(String namePattern);
+ *     List<Product> named(@By("name") @Is(LIKE) @IgnoreCase String namePattern);
  *
  *     @Query("UPDATE Product SET price = price - (price * ?1) WHERE price * ?1 <= ?2")
  *     int putOnSale(float rateOfDiscount, float maxDiscount);
@@ -52,7 +53,7 @@
  * Products products;
  *
  * ...
- * found = products.findByNameLike("%Printer%");
+ * found = products.named("%Printer%");
  * numUpdated = products.putOnSale(0.15f, 20.0f);
  * </pre>
  *