Reuse existing Operator enum

njr-11 · njr-11 · commit a55eebad5c5b · 2025-02-17T11:33:02.000-06:00
diff --git a/api/src/main/java/jakarta/data/Limit.java b/api/src/main/java/jakarta/data/Limit.java
@@ -34,7 +34,7 @@
  *
  * <pre>
  * &#64;Find
- * Product[] named(&#64;By(_Product.NAME) &#64;Is(LIKE_ANY_CASE) String namePattern,
+ * Product[] named(&#64;By(_Product.NAME) &#64;Is(LIKE) &#64;IgnoreCase String namePattern,
  *                 Limit limit,
  *                 Sort&lt;Product&gt;... sorts);
  * 
diff --git a/api/src/main/java/jakarta/data/metamodel/restrict/Operator.java b/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;
         };
     }
 }
diff --git a/api/src/main/java/jakarta/data/page/PageRequest.java b/api/src/main/java/jakarta/data/page/PageRequest.java
@@ -40,8 +40,8 @@
  * &#64;Find
  * &#64;OrderBy("age")
  * &#64;OrderBy("ssn")
- * Person[] agedBetween(&#64;By("age") &#64;Is(GREATER_THAN_EQ) int minAge,
- *                      &#64;By("age") &#64;Is(LESS_THAN_EQ) int maxAge,
+ * 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>
  *
diff --git a/api/src/main/java/jakarta/data/repository/IgnoreCase.java b/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 {
+}
diff --git a/api/src/main/java/jakarta/data/repository/Is.java b/api/src/main/java/jakarta/data/repository/Is.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2024 Contributors to the Eclipse Foundation
+ * 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.
@@ -22,6 +22,8 @@
 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.
@@ -42,7 +44,7 @@
  *
  *     // 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_ANY_CASE) String pattern,
+ *     Page&lt;Product&gt; search(&#64;By(_Product.NAME) &#64;Is(LIKE) &#64;IgnoreCase String pattern,
  *                          PageRequest pagination,
  *                          Order&lt;Product&gt; order);
  *
@@ -67,65 +69,21 @@
      * <pre>
      * &#64;Find
      * &#64;OrderBy(_Person.YEAR_BORN)
-     * List&lt;Person&gt; bornWithin(&#64;By(_Person.YEAR_BORN) &#64;Is(GREATER_THAN_EQ) float minYear,
-     *                         &#64;By(_Person.YEAR_BORN) &#64;Is(LESS_THAN_EQ) float maxYear);
+     * 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 #EQUAL equality}
+     * <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.repository.Is.Op.*;
+     * import static jakarta.data.metamodel.restrict.Operator.*;
      * </pre>
      *
      * @return the type of comparison operation.
      */
-    Op value() default Op.EQUAL;
-
-    /**
-     * <p>Comparison operations for the {@link Is} annotation.</p>
-     *
-     * <p>For more concise code, it can be convenient to statically import one
-     * or more comparison operations. For example:</p>
-     *
-     * <pre>
-     * import static jakarta.data.repository.Is.Op.*;
-     * </pre>
-     */
-    public static enum Op {
-        // TODO add JavaDoc with examples to these
-        ANY_CASE,
-        EQUAL,
-        GREATER_THAN,
-        GREATER_THAN_ANY_CASE,
-        GREATER_THAN_EQ,
-        GREATER_THAN_EQ_ANY_CASE,
-        IN,
-        LESS_THAN,
-        LESS_THAN_ANY_CASE,
-        LESS_THAN_EQ,
-        LESS_THAN_EQ_ANY_CASE,
-        LIKE,
-        LIKE_ANY_CASE,
-        PREFIXED,
-        PREFIXED_ANY_CASE,
-        SUBSTRINGED,
-        SUBSTRINGED_ANY_CASE,
-        SUFFIXED,
-        SUFFIXED_ANY_CASE,
-        NOT,
-        NOT_ANY_CASE,
-        NOT_IN,
-        NOT_LIKE,
-        NOT_LIKE_ANY_CASE,
-        NOT_PREFIXED,
-        NOT_PREFIXED_ANY_CASE,
-        NOT_SUBSTRINGED,
-        NOT_SUBSTRINGED_ANY_CASE,
-        NOT_SUFFIXED,
-        NOT_SUFFIXED_ANY_CASE;
-    }
+    Operator value() default Operator.EQUAL;
 }
diff --git a/api/src/main/java/jakarta/data/repository/OrderBy.java b/api/src/main/java/jakarta/data/repository/OrderBy.java
@@ -118,7 +118,7 @@
      * <pre>
      * &#64;Find
      * &#64;OrderBy("age")
-     * Stream&lt;Person&gt; withLastName(&#64;By("lastName") &#64;Is(ANY_CASE) String surname);
+     * Stream&lt;Person&gt; withLastName(&#64;By("lastName") &#64;IgnoreCase String surname);
      * </pre>
      *
      * @return entity attribute name.
diff --git a/api/src/main/java/jakarta/data/repository/Repository.java b/api/src/main/java/jakarta/data/repository/Repository.java
@@ -39,7 +39,7 @@
  *
  *     &#64;Find
  *     &#64;OrderBy("price")
- *     List&lt;Product&gt; named(&#64;By("name") &#64;Is(LIKE_ANY_CASE) String namePattern);
+ *     List&lt;Product&gt; named(&#64;By("name") &#64;Is(LIKE) &#64;IgnoreCase String namePattern);
  *
  *     &#64;Query("UPDATE Product SET price = price - (price * ?1) WHERE price * ?1 &lt;= ?2")
  *     int putOnSale(float rateOfDiscount, float maxDiscount);
diff --git a/api/src/main/java/module-info.java b/api/src/main/java/module-info.java
@@ -74,8 +74,8 @@
  *     &#64;Find
  *     &#64;OrderBy("price")
  *     List&lt;Product&gt; search(
- *             &#64;By("name") &#64;Is(LIKE_ANY_CASE) String namePattern,
- *             &#64;By("price") &#64;Is(lESS_THAN_EQ) float max);
+ *             &#64;By("name") &#64;Is(LIKE) &#64;IgnoreCase String namePattern,
+ *             &#64;By("price") &#64;Is(lESS_THAN_EQUAL) float max);
  *
  *     &#64;Query("UPDATE Product SET price = price * (1.0 - ?1) WHERE yearProduced &lt;= ?2")
  *     int discountOldInventory(float rateOfDiscount, int maxYear);
@@ -767,8 +767,8 @@
  * &#64;Find
  * Vehicle[] search(String make,
  *                  String model,
- *                  &#64;By(_Vehicle.YEAR) &#64;Is(GREATER_THAN_EQ) int minYear,
- *                  &#64;By(_Vehicle.YEAR) &#64;Is(LESS_THAN_EQ) int maxYear,
+ *                  &#64;By(_Vehicle.YEAR) &#64;Is(GREATER_THAN_EQUAL) int minYear,
+ *                  &#64;By(_Vehicle.YEAR) &#64;Is(LESS_THAN_EQUAL) int maxYear,
  *                  Sort&lt;?&gt;... sorts);
  * </pre>
  *
@@ -810,7 +810,7 @@
  * &#64;Find
  * &#64;OrderBy(value = _Product.AMOUNT_SOLD, descending = true)
  * &#64;OrderBy(ID)
- * Product[] named(&#64;By(_Product.NAME) &#64;Is(LIKE_ANY_CASE) String pattern,
+ * Product[] named(&#64;By(_Product.NAME) &#64;Is(LIKE) &#64;IgnoreCase String pattern,
  *                 PageRequest pageRequest);
  * ...
  * page1 = products.named("%phone%", PageRequest.ofSize(20));
@@ -828,9 +828,9 @@
  *
  * <pre>
  * &#64;Find
- * Product[] search(&#64;By("name") &#64;Is(LIKE_ANY_CASE) String pattern,
- *                  &#64;By("price") &#64;Is(GREATER_THAN_EQ) float minPrice,
- *                  &#64;By("price") &#64;Is(LESS_THAN_EQ) float maxPrice,
+ * Product[] search(&#64;By("name") &#64;Is(LIKE) &#64;IgnoreCase String pattern,
+ *                  &#64;By("price") &#64;Is(GREATER_THAN_EQUAL) float minPrice,
+ *                  &#64;By("price") &#64;Is(LESS_THAN_EQUAL) float maxPrice,
  *                  PageRequest pageRequest,
  *                  Order&lt;Product&gt; order);
  *
@@ -848,7 +848,7 @@
  *
  * <pre>
  * &#64;Find
- * Product[] named(&#64;By("name") &#64;Is(LIKE_ANY_CASE) String pattern,
+ * Product[] named(&#64;By("name") &#64;Is(LIKE) &#64;IgnoreCase String pattern,
  *                 Limit max,
  *                 Order&lt;Product&gt; sortBy);
  *
@@ -866,7 +866,7 @@
  *
  * <pre>
  * &#64;Find
- * Product[] named(&#64;By("name") &#64;Is(LIKE_ANY_CASE) String pattern,
+ * Product[] named(&#64;By("name") &#64;Is(LIKE) &#64;IgnoreCase String pattern,
  *                 Limit max,
  *                 {@code Sort<?>...} sortBy);
  *

Original file line number	Diff line number	Diff line change
`@@ -34,7 +34,7 @@`
`34`	`34`	`*`
`35`	`35`	`* <pre>`
`36`	`36`	`* @Find`
`37`		`- * Product[] named(@By(_Product.NAME) @Is(LIKE_ANY_CASE) String namePattern,`
	`37`	`+ * Product[] named(@By(_Product.NAME) @Is(LIKE) @IgnoreCase String namePattern,`
`38`	`38`	`* Limit limit,`
`39`	`39`	`* Sort<Product>... sorts);`
`40`	`40`	`*`
Original file line number	Diff line number	Diff line change
`@@ -118,7 +118,7 @@`
`118`	`118`	`* <pre>`
`119`	`119`	`* @Find`
`120`	`120`	`* @OrderBy("age")`
`121`		`- * Stream<Person> withLastName(@By("lastName") @Is(ANY_CASE) String surname);`
	`121`	`+ * Stream<Person> withLastName(@By("lastName") @IgnoreCase String surname);`
`122`	`122`	`* </pre>`
`123`	`123`	`*`
`124`	`124`	`* @return entity attribute name.`
Original file line number	Diff line number	Diff line change
`@@ -39,7 +39,7 @@`
`39`	`39`	`*`
`40`	`40`	`* @Find`
`41`	`41`	`* @OrderBy("price")`
`42`		`- * List<Product> named(@By("name") @Is(LIKE_ANY_CASE) String namePattern);`
	`42`	`+ * List<Product> named(@By("name") @Is(LIKE) @IgnoreCase String namePattern);`
`43`	`43`	`*`
`44`	`44`	`* @Query("UPDATE Product SET price = price - (price * ?1) WHERE price * ?1 <= ?2")`
`45`	`45`	`* int putOnSale(float rateOfDiscount, float maxDiscount);`