Add Criteria-Based Filtering

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

@@ -0,0 +1,79 @@
+/*
+ * 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;
+
+
+/**
+ * Enum representing common operators used to define query conditions in Jakarta Data queries.
+ * The {@code Operator} enum provides a set of operations to specify how values should be compared,
+ * matched, or restricted when filtering data, supporting flexible and expressive querying across
+ * different contexts.
+ */
+public enum Operator {
+
+    /**
+     * Matches records where the field value is exactly equal to the specified value.
+     * Typically used for exact matching on unique identifiers, names, or other exact-value fields.
+     */
+    EQUAL,
+
+    /**
+     * Matches records where the field value is greater than the specified value.
+     * Often applied to numerical fields (e.g., dates, prices) for retrieving values above a given threshold.
+     */
+    GREATER_THAN,
+
+    /**
+     * Matches records where the field value is greater than or equal to the specified value.
+     * Useful for inclusive range queries, where the specified boundary is included in the results.
+     */
+    GREATER_THAN_EQUAL,
+
+    /**
+     * Matches records where the field value is contained within a specified collection of values.
+     * Commonly used to match against multiple possible values, such as category or status lists.
+     */
+    IN,
+
+    /**
+     * Matches records where the field value is less than the specified value.
+     * Frequently used in numerical comparisons to retrieve values below a certain threshold.
+     */
+    LESS_THAN,
+
+    /**
+     * Matches records where the field value is less than or equal to the specified value.
+     * Suitable for inclusive range queries that include the specified boundary in the results.
+     */
+    LESS_THAN_EQUAL,
+
+    /**
+     * Matches records where the field value conforms to a specified pattern, often with wildcards.
+     * Commonly applied to string fields for partial matches (e.g., names containing a substring).
+     */
+    LIKE,
+
+    /**
+     * Matches records where the field value falls within a specified range.
+     * Typically used for range-based comparisons, such as finding dates between a start and end date.
+     */
+    BETWEEN
+}
+
+
+

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

@@ -17,12 +17,12 @@
  */
 package jakarta.data;
 
-import java.util.Iterator;
-import java.util.List;
-
 import jakarta.data.metamodel.StaticMetamodel;
 import jakarta.data.repository.OrderBy;
 
+import java.util.Iterator;
+import java.util.List;
+
 /**
  * <p>Requests sorting on various entity attributes.</p>
  *
@@ -169,4 +169,4 @@ public Iterator<Sort<? super T>> iterator() {
     public String toString() {
         return sorts.toString();
     }
-}
+}

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

@@ -0,0 +1,96 @@
+/*
+ * 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;
+
+import jakarta.data.metamodel.Restriction;
+
+
+/**
+ * Represents a pattern-based restriction for matching operations, encapsulating different
+ * options such as prefix, suffix, and substring matching. This implementation
+ * allows flexibility in creating pattern-based conditions directly as {@link Restriction} instances.
+ *
+ * <p>Example usage with metadata attributes:</p>
+ * <pre>
+ * Restriction<Book> prefixIgnoreCase = _Book.title.endsWith("Guide");
+ * </pre>
+ *
+ */
+public record Pattern(String value, boolean ignoreCase) {
+
+    /**
+     * Creates a pattern for a {@link Operator#LIKE LIKE} match on the specified value.
+     * This method sets the field to `null`, allowing it to be applied
+     * later to a specific attribute.
+     *
+     * @return a Pattern instance for a pattern match.
+     */
+    public static Pattern like(String pattern) {
+        return new Pattern(pattern, false);
+    }
+
+    /**
+     * Creates a pattern for a `LIKE` match where values start with the specified prefix.
+     * The `field` is set to `null` initially, allowing it to be assigned to an attribute later.
+     *
+     * @param value the prefix to match at the beginning of the field's value.
+     * @return a Pattern instance for a prefix match.
+     */
+    public static Pattern startsWith(String value) {
+        return new Pattern( value + "%", false);
+    }
+
+    /**
+     * Creates a pattern for a `LIKE` match where values contain the specified substring.
+     * This method initializes the field to `null`, allowing the pattern to be applied to
+     * a specific attribute later.
+     *
+     * @param value the substring to match within the field's value.
+     * @return a Pattern instance for a substring match.
+     */
+    public static Pattern contains(String value) {
+        return new Pattern("%" + value + "%", false);
+    }
+
+    /**
+     * Creates a pattern for a `LIKE` match where values end with the specified suffix.
+     * The field is set to `null`, allowing assignment to a specific attribute later.
+     *
+     *
+     * @param value the suffix to match at the end of the field's value.
+     * @return a Pattern instance for a suffix match.
+     */
+    public static Pattern endsWith(String value) {
+        return new Pattern(value + "%", false);
+    }
+
+    /**
+     * Returns a new {@code Pattern} instance with case-insensitive matching.
+     * This method allows you to specify that the pattern should ignore case when matching.
+     *
+     * <pre>
+     * // Case-insensitive prefix match
+     * Restriction<Book> titlePattern = Pattern.startsWith("Hibernate").ignoringCase();
+     * </pre>
+     *
+     * @return a new Pattern instance with `ignoreCase` set to `true`.
+     */
+    public Pattern ignoringCase() {
+        return new Pattern(value, true);
+    }
+}

api/src/main/java/jakarta/data/metamodel/Attribute.java

@@ -17,6 +17,7 @@
  */
 package jakarta.data.metamodel;
 
+import jakarta.data.Operator;
 import jakarta.data.Sort;
 
 /**
@@ -32,4 +33,23 @@ public interface Attribute<T> {
      * @return the entity attribute name.
      */
     String name();
+
+    /**
+     * Creates an equality restriction for the attribute.
+     *
+     * @param value the value to match exactly.
+     * @return a Restriction representing an equality condition.
+     */
+    default Restriction<T> equal(Object value) {
+        return new SimpleRestriction<>(name(), Operator.EQUAL, value);
+    }
+
+    /**
+     * Creates a restriction for checking if the attribute is null.
+     *
+     * @return a Restriction representing the condition where the attribute is null.
+     */
+    default Restriction<T> isNull(){
+        return new SimpleRestriction<>(name(), Operator.EQUAL, null);
+    }
 }

api/src/main/java/jakarta/data/metamodel/BasicRestriction.java

@@ -0,0 +1,55 @@
+/*
+ * 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.metamodel;
+
+import jakarta.data.Operator;
+
+/**
+ * A basic restriction applies to a single field, representing conditions such as equality,
+ * comparisons, range checks, and pattern matches.
+ *
+ * <p>The {@code BasicRestriction} interface provides methods for defining simple, singular restrictions
+ * based on a specific field, an operator, and an optional comparison value. This interface supports
+ * common operators (e.g., EQUAL, GREATER_THAN) and serves as a foundation for filtering
+ * logic on individual fields.</p>
+ *
+ * @param <T> the type of the entity on which the restriction is applied.
+ */
+public interface BasicRestriction<T> extends Restriction<T> {
+
+    /**
+     * The name of the field on which this restriction is applied.
+     *
+     * @return the field name as a String.
+     */
+    String field();
+
+    /**
+     * The operator defining the type of comparison or condition for this restriction.
+     *
+     * @return the operator representing the restriction type (e.g., EQUAL, LIKE, BETWEEN).
+     */
+    Operator operator();
+
+    /**
+     * The value used for comparison in this restriction, if applicable.
+     *
+     * @return the comparison value, or {@code null} if the restriction does not use a value (e.g., IS_NULL).
+     */
+    Object value();
+}

api/src/main/java/jakarta/data/metamodel/CompositeRestriction.java

@@ -0,0 +1,72 @@
+/*
+ * 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.metamodel;
+
+import java.util.Iterator;
+import java.util.List;
+
+/**
+ * A composite restriction representing a collection of individual {@link Restriction}
+ * and {@link Restrict} instances, combined under a single logical operation.
+ *
+ * <p>This record allows multiple restrictions to be treated as a single entity, making
+ * it easy to pass complex conditions to repository methods.</p>
+ *
+ * @param <T> the entity type that the restrictions apply to.
+ */
+public record CompositeRestriction<T>(Restrict type, List<Restriction<? extends T>> restrictions) implements Iterable<Restriction<? extends T>>, MultipleRestriction<T> {
+
+    /**
+     * Constructs a composite restriction with the specified operator and list of restrictions.
+     *
+     * @param restrictions the list of restrictions to combine.
+     */
+    public CompositeRestriction {
+        restrictions = List.copyOf(restrictions); // Ensure immutability of the list
+    }
+
+    @Override
+    public Iterator<Restriction<? extends T>> iterator() {
+        return restrictions.iterator();
+    }
+
+    /**
+     * Creates a composite restriction where all specified restrictions must be true (AND logic).
+     *
+     * @param restrictions the individual restrictions to combine.
+     * @param <T>          the entity type that the restrictions apply to.
+     * @return a CompositeRestriction representing the AND combination of the provided restrictions.
+     */
+    @SafeVarargs
+    public static <T> CompositeRestriction<T> all(Restriction<T>... restrictions) {
+        return new CompositeRestriction<>(Restrict.ALL, List.of(restrictions));
+    }
+
+    /**
+     * Creates a composite restriction where any of the specified restrictions may be true (OR logic).
+     *
+     * @param restrictions the individual restrictions to combine.
+     * @param <T>          the entity type that the restrictions apply to.
+     * @return a CompositeRestriction representing the OR combination of the provided restrictions.
+     */
+    @SafeVarargs
+    public static <T> CompositeRestriction<T> any(Restriction<T>... restrictions) {
+        return new CompositeRestriction<>(Restrict.ANY, List.of(restrictions));
+    }
+
+}