Add Criteria-Based Filtering

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

@@ -0,0 +1,67 @@
+/*
+ * 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;
+
+/**
+ * Represents a criteria condition for repository queries, defining a field, an operator,
+ * a comparison value, and an optional negation flag for flexible query construction.
+ */
+public record Criteria(String field, FilterType operator, Object value, boolean negate) {
+
+    /**
+     * Constructs a criteria condition without negation.
+     *
+     * @param field    the name of the field to apply the criteria to (e.g., "title" or "publicationDate").
+     * @param operator the operator defining the comparison or condition (e.g., `FilterType.Like`).
+     * @param value    the value to compare the field against.
+     */
+    public Criteria(String field, FilterType operator, Object value) {
+        this(field, operator, value, false);
+    }
+
+
+    /**
+     * Creates a basic criteria condition without negation.
+     */
+    public static Criteria where(String field, FilterType operator, Object value) {
+        return new Criteria(field, operator, value, false);
+    }
+
+    /**
+     * Creates a criteria condition with negation.
+     */
+    public static Criteria not(String field, FilterType operator, Object value) {
+        return new Criteria(field, operator, value, true);
+    }
+
+    /**
+     * Creates a LIKE criteria with a pattern, without negation.
+     */
+    public static Criteria like(String field, String pattern) {
+        return new Criteria(field, FilterType.LIKE, pattern, false);
+    }
+
+    /**
+     * Creates a BETWEEN criteria for range queries, without negation.
+     */
+    public static Criteria between(String field, Object start, Object end) {
+        return new Criteria(field, FilterType.BETWEEN, List.of(start, end), false);
+    }
+}

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

@@ -0,0 +1,76 @@
+/*
+ * 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 filter types used to compare, match, or restrict values in Jakarta Data queries.
+ * The {@code FilterType} enum defines a set of operators to specify how values should be compared or matched
+ * in data filtering, providing flexibility for various querying needs across different contexts.
+ */
+public enum FilterType {
+    /**
+     * Matches records where the field value is exactly equal to the specified value.
+     * Often used for precise matching on identifiers, names, or other exact-value fields.
+     */
+    EQUAL,
+
+    /**
+     * Matches records where the field value is greater than the specified value.
+     * Commonly used for numerical fields (e.g., dates, prices) to retrieve values above a threshold.
+     */
+    GREATER_THAN,
+
+    /**
+     * Matches records where the field value is greater than or equal to the specified value.
+     * Useful for inclusive range queries to include a specified boundary.
+     */
+    GREATER_THAN_EQUAL,
+
+    /**
+     * Filters records where the field value is contained within a specified collection or set of values.
+     * Often applied to match multiple values (e.g., category lists, status collections).
+     */
+    IN,
+
+    /**
+     * Matches records where the field value is less than the specified value.
+     * Frequently used in numerical comparisons to retrieve values below a 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.
+     */
+    LESS_THAN_EQUAL,
+
+    /**
+     * Matches records where the field value conforms to a specified pattern, often utilizing wildcards.
+     * Commonly applied to string fields, allowing partial matches (e.g., names containing a substring).
+     */
+    LIKE,
+
+    /**
+     * Matches records where the field value falls within a specified range of values.
+     * Typically used for range comparisons, such as finding dates within a start and end period.
+     */
+    BETWEEN;
+}
+
+

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

@@ -0,0 +1,118 @@
+/*
+ * 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.Criteria;
+
+import java.util.Collection;
+
+/**
+ * Represents an entity attribute in the {@link StaticMetamodel} that supports filtering conditions.
+ * This interface provides methods for defining common query conditions, allowing the attribute to be used
+ * in filtering expressions such as `_Book.title.like("Jakarta Data%")`.
+ *
+ * <p>Example usage:</p>
+ * <pre>{@code
+ * // Define criteria for filtering
+ * Criteria titleCriteria = _Book.title.like("Jakarta Data%");
+ * Criteria dateCriteria = _Book.publicationDate.between(pastDate, LocalDate.now());
+ * Criteria authorCriteria = _Book.author.equal("John Doe");
+ *
+ * // Apply criteria in a repository query
+ * repo.books(List.of(titleCriteria, dateCriteria, authorCriteria));
+ * }</pre>
+ *
+ * @param <T> the type of the entity class in the static metamodel.
+ * @param <V> the type of the attribute's value.
+ */
+public interface FilterableAttribute<T, V> extends Attribute<T> {
+
+    /**
+     * Creates an equality condition for the attribute, matching the specified value.
+     *
+     * @param value the value to compare with the attribute.
+     * @return a criteria condition representing "attribute = value".
+     */
+    Criteria equal(V value);
+
+    /**
+     * Creates an inequality condition for the attribute, excluding the specified value.
+     *
+     * @param value the value to exclude.
+     * @return a criteria condition representing "attribute != value".
+     */
+    Criteria notEqual(V value);
+
+    /**
+     * Creates a "like" condition for textual attributes, matching the specified pattern.
+     * This is typically used for partial matches in string fields.
+     *
+     * @param pattern the pattern to match, often using wildcards.
+     * @return a criteria condition representing "attribute LIKE pattern".
+     */
+    Criteria like(String pattern);
+
+    /**
+     * Creates a "greater than" condition for the attribute, matching values greater than the specified value.
+     *
+     * @param value the minimum value to match.
+     * @return a criteria condition representing "attribute > value".
+     */
+    Criteria greaterThan(V value);
+
+    /**
+     * Creates a "greater than or equal to" condition for the attribute, matching values greater than or equal to the specified value.
+     *
+     * @param value the minimum value to match inclusively.
+     * @return a criteria condition representing "attribute >= value".
+     */
+    Criteria greaterThanOrEqual(V value);
+
+    /**
+     * Creates a "less than" condition for the attribute, matching values less than the specified value.
+     *
+     * @param value the maximum value to match.
+     * @return a criteria condition representing "attribute < value".
+     */
+    Criteria lessThan(V value);
+
+    /**
+     * Creates a "less than or equal to" condition for the attribute, matching values less than or equal to the specified value.
+     *
+     * @param value the maximum value to match inclusively.
+     * @return a criteria condition representing "attribute <= value".
+     */
+    Criteria lessThanOrEqual(V value);
+
+    /**
+     * Creates a "between" condition for the attribute, matching values within the specified range.
+     *
+     * @param start the lower bound of the range.
+     * @param end   the upper bound of the range.
+     * @return a criteria condition representing "attribute BETWEEN start AND end".
+     */
+    Criteria between(V start, V end);
+
+    /**
+     * Creates an "in" condition for the attribute, matching any of the specified values.
+     *
+     * @param values the collection of values to match.
+     * @return a criteria condition representing "attribute IN (values)".
+     */
+    Criteria in(Collection<V> values);
+}

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

@@ -0,0 +1,83 @@
+/*
+ * 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 jakarta.data.Criteria;
+import jakarta.data.page.Page;
+import jakarta.data.page.PageRequest;
+
+import java.util.List;
+
+/**
+ * Repository interface that extends {@link DataRepository} to add support for dynamic filtering
+ * using {@link Criteria} objects with optional pagination.
+ *
+ * <p>This repository allows flexible querying by accepting varargs of criteria conditions
+ * for filtering and supports pagination to retrieve results in pages or as a full list.</p>
+ *
+ * <p>Example usage:</p>
+ *
+ * <pre>
+ * &#64;Inject
+ * DriverLicenses licenses;
+ *
+ * // Define and apply criteria using metamodel attributes
+ * PageRequest pageRequest = PageRequest.of(0, 10);
+ * Page<DriverLicense> pagedResults = licenses.findByCriteria(pageRequest,
+ *     _DriverLicense.license.like("ABC%"),
+ *     _DriverLicense.expiry.greaterThan(LocalDate.now())
+ * );
+ *
+ * // Fetch results without pagination
+ * List<DriverLicense> allResults = licenses.findByCriteria(
+ *     _DriverLicense.license.like("ABC%"),
+ *     _DriverLicense.expiry.greaterThan(LocalDate.now())
+ * );
+ * </pre>
+ *
+ * @param <T> the type of the primary entity class of the repository.
+ * @param <K> the type of the unique identifier field or property of the primary entity.
+ */
+public interface CriteriaRepository<T, K> extends DataRepository<T, K> {
+
+
+    /**
+     * Finds entities by applying the specified criteria conditions, with support for pagination.
+     *
+     * @param pageRequest the pagination information including page number and size.
+     * @param criteria    the varargs of criteria conditions to filter the results.
+     * @return a page of entities that match the criteria.
+     */
+    Page<T> filter(PageRequest pageRequest, Criteria... criteria);
+
+    /**
+     * Finds all entities by applying the specified criteria conditions, returning results as a list without pagination.
+     *
+     * @param criteria the varargs of criteria conditions to filter the results.
+     * @return a list of entities that match the criteria.
+     */
+    List<T> filter(Criteria... criteria);
+
+    /**
+     * Counts entities by applying the specified criteria conditions.
+     *
+     * @param criteria the varargs of criteria conditions to filter the results.
+     * @return the count of entities that match the criteria.
+     */
+    long countBy(Criteria... criteria);
+}