Add Criteria-Based Filtering

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

@@ -0,0 +1,53 @@
+/*
+ * 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;
+
+/**
+ * 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/CompositeRestriction.java

@@ -0,0 +1,49 @@
+/*
+ * 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 java.util.List;
+
+/**
+ * A composite restriction that combines multiple {@link Restriction} instances using logical operators.
+ *
+ * <p>The {@code MultipleRestriction} interface allows for combining multiple restrictions, enabling complex
+ * filtering scenarios where multiple conditions must be satisfied. Each contained {@link Restriction}
+ * can be evaluated based on the logical operator specified by the {@link CompositeRestrictionType} type.</p>
+ *
+ * <p>This interface is useful for defining AND/OR conditions where multiple fields and restrictions
+ * are evaluated together in a repository query.</p>
+ *
+ * @param <T> the type of the entity on which the restriction is applied.
+ */
+public interface CompositeRestriction<T> extends Restriction<T> {
+
+    /**
+     * The list of restrictions that are combined in this composite restriction.
+     *
+     * @return a list of individual restrictions.
+     */
+    List<Restriction<? extends T>> restrictions();
+
+    /**
+     * The logical operator used to combine the contained restrictions, such as AND or OR.
+     *
+     * @return the logical combination type for this composite restriction.
+     */
+    CompositeRestrictionType type();
+}

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

@@ -0,0 +1,73 @@
+/*
+ * 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 java.util.Iterator;
+import java.util.List;
+
+/**
+ * A composite restriction representing a collection of individual {@link Restriction}
+ * and {@link CompositeRestrictionType} 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.
+ */
+record CompositeRestrictionRecord<T>(CompositeRestrictionType type, List<Restriction<? extends T>> restrictions)
+        implements Iterable<Restriction<? extends T>>, CompositeRestriction<T> {
+
+    /**
+     * Constructs a composite restriction with the specified operator and list of restrictions.
+     *
+     * @param restrictions the list of restrictions to combine.
+     */
+    public CompositeRestrictionRecord {
+        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> CompositeRestrictionRecord<T> all(Restriction<T>... restrictions) {
+        return new CompositeRestrictionRecord<>(CompositeRestrictionType.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> CompositeRestrictionRecord<T> any(Restriction<T>... restrictions) {
+        return new CompositeRestrictionRecord<>(CompositeRestrictionType.ANY, List.of(restrictions));
+    }
+
+}

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

@@ -0,0 +1,43 @@
+/*
+ * 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;
+
+
+/**
+ * Represents the logical operators used to combine multiple restrictions in a query.
+ *
+ * <p>The `Restrict` enum defines two types of logical combinations:</p>
+ * <ul>
+ *   <li><b>ALL</b> - Requires that all contained restrictions are satisfied (logical AND).</li>
+ *   <li><b>ANY</b> - Requires that at least one of the contained restrictions is satisfied (logical OR).</li>
+ * </ul>
+ *
+ * <p>This enum is typically used in {@link CompositeRestriction} to specify how its list of
+ * restrictions should be combined, allowing for flexible and complex query conditions.</p>
+ */
+public enum CompositeRestrictionType {
+    /**
+     * Requires that all contained restrictions must be satisfied (logical AND).
+     */
+    ALL,
+
+    /**
+     * Requires that at least one of the contained restrictions must be satisfied (logical OR).
+     */
+    ANY
+}

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();
     }
-}
+}