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_IGNORE_CASE) 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/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_EQ) int minAge,
+ *                      &#64;By("age") &#64;Is(LESS_THAN_EQ) 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 field or property.
  * </ul>
  * <p>Arguments to the annotated parameter are compared to values of the
- * mapped persistent field.</p>
+ * mapped persistent field. The equality comparison is used by default.<p>
+ *
+ * <p>For other types of basic comparisons, include the {@link Is} annotation.</p>
+ *
  * <p>The field 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/Is.java

@@ -0,0 +1,103 @@
+/*
+ * Copyright (c) 2024 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;
+
+/**
+ * <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 is used on the same parameter to identify the
+ * persistent field.</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_IGNORE_CASE) 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 {
+    // TODO add JavaDoc with examples to these
+    String EQUAL                = "EQUAL";
+    String GREATER_THAN         = "GREATER_THAN";
+    String GREATER_THAN_EQ      = "GREATER_THAN_EQ";
+    String IGNORE_CASE          = "IGNORE_CASE";
+    String IN                   = "IN";
+    String LESS_THAN            = "LESS_THAN";
+    String LESS_THAN_EQ         = "LESS_THAN_EQ";
+    String LIKE                 = "LIKE";
+    String LIKE_IGNORE_CASE     = "LIKE_IGNORE_CASE";
+    String NOT                  = "NOT";
+    String NOT_IGNORE_CASE      = "NOT_IGNORE_CASE";
+    String NOT_IN               = "NOT_IN";
+    String NOT_LIKE             = "NOT_LIKE";
+    String NOT_LIKE_IGNORE_CASE = "NOT_LIKE_IGNORE_CASE";
+
+    /**
+     * <p>The type of comparison operation to use when comparing a persistent
+     * field against a value that is supplied to a repository method.
+     * For portable applications, the comparison operation must be one of the
+     * constants defined within this class. Jakarta Data providers might choose
+     * to provide their own constants as non-portable extensions.</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(TREATER_THAN_EQ) float minYear,
+     *                         &#64;By(_Person.YEAR_BORN) &#64;Is(LESS_THAN_EQ) float maxYear);
+     * </pre>
+     *
+     * <p>The default comparison operation is the {@linkplain #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.repository.Is.*;
+     * </pre>
+     *
+     * @return the type of comparison operation.
+     */
+    String value() default 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;Is(IGNORE_CASE) 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_IGNORE_CASE) 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>
  *