From d3b124cfe0b8fd48646917c1e7aa8293834f4a75 Mon Sep 17 00:00:00 2001 From: Romuald Lemesle Date: Fri, 28 Nov 2025 22:44:11 +0100 Subject: [PATCH 1/4] [backend] docs(queryable): Add javadoc on Queryable annotation --- .../java/io/openaev/annotation/Queryable.java | 40 +++++++++++++++++-- 1 file changed, 37 insertions(+), 3 deletions(-) diff --git a/openaev-model/src/main/java/io/openaev/annotation/Queryable.java b/openaev-model/src/main/java/io/openaev/annotation/Queryable.java index 7dfed969bd4..c14d6ffe1a7 100644 --- a/openaev-model/src/main/java/io/openaev/annotation/Queryable.java +++ b/openaev-model/src/main/java/io/openaev/annotation/Queryable.java @@ -6,21 +6,51 @@ import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; +/** + * Annotation used to describe whether a JPA bean property can be searched, filtered, sorted or + * dynamically resolved by the query engine. + * + *

This annotation provides metadata to drive the construction of dynamic Spring Specifications + * and to expose query capabilities to higher-level components (API, UI, query builders, etc.). + * + *

It can be applied to fields or getter methods. + */ @Retention(RetentionPolicy.RUNTIME) @Target({ElementType.FIELD, ElementType.METHOD}) public @interface Queryable { + + /** + * Enables free-text search on this property (e.g. using LIKE/ILIKE operators depending on the + * backend). + */ boolean searchable() default false; + /** Allows filtering this property using supported filter operators. */ boolean filterable() default false; + /** + * Indicates that the property refers to another entity stored in the database, meaning its + * possible filter values must be retrieved dynamically. Typically used for relations (ManyToOne, + * OneToMany, etc.). + */ boolean dynamicValues() default false; + /** Allows sorting results based on this property. */ boolean sortable() default false; + /** Human-readable label used for documentation or UI generation. */ String label() default ""; + /** + * Defines the JPA path used to query this property. Follows Spring Data Specification conventions + * (e.g. {@code "organization.id"}). + */ String path() default ""; + /** + * Defines multiple possible JPA paths, when the property can be resolved through different + * relationships or aliases. + */ String[] paths() default {}; Filters.FilterOperator[] overrideOperators() default {}; @@ -29,8 +59,12 @@ Class refEnumClazz() default Unassigned.class; - // use this absolutely specific class as a "null" value for class, refEnumClazz - // don't use Void here because that is a legitimate return type - // although there is little to justify having a queryable void method + /** + * Special sentinel class used to represent an "unassigned" state for {@link #clazz()} and {@link + * #refEnumClazz()}. + * + *

We cannot use {@code Void.class} here since {@code void} is a valid type and could lead to + * ambiguity. + */ class Unassigned {} } From e15cb1e9a97a98d32bea45c2e3c78687fa2820b2 Mon Sep 17 00:00:00 2001 From: Romuald Lemesle Date: Mon, 1 Dec 2025 09:04:00 +0100 Subject: [PATCH 2/4] [backend] docs(queryable): Add javadoc on Queryable annotation --- openaev-model/src/main/java/io/openaev/annotation/Queryable.java | 1 + 1 file changed, 1 insertion(+) diff --git a/openaev-model/src/main/java/io/openaev/annotation/Queryable.java b/openaev-model/src/main/java/io/openaev/annotation/Queryable.java index c14d6ffe1a7..8529addf8b6 100644 --- a/openaev-model/src/main/java/io/openaev/annotation/Queryable.java +++ b/openaev-model/src/main/java/io/openaev/annotation/Queryable.java @@ -44,6 +44,7 @@ /** * Defines the JPA path used to query this property. Follows Spring Data Specification conventions * (e.g. {@code "organization.id"}). + * Path should end by a primitiv value or this can lead to UnsupportableOperation. */ String path() default ""; From e3415c9ec4ce6f5542b2ba1d321c0fa2472939a4 Mon Sep 17 00:00:00 2001 From: Antoine MAZEAS Date: Mon, 1 Dec 2025 09:31:23 +0100 Subject: [PATCH 3/4] add doc for remaining Queryable attributes Signed-off-by: Antoine MAZEAS --- .../java/io/openaev/annotation/Queryable.java | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/openaev-model/src/main/java/io/openaev/annotation/Queryable.java b/openaev-model/src/main/java/io/openaev/annotation/Queryable.java index 8529addf8b6..85b08ad8e31 100644 --- a/openaev-model/src/main/java/io/openaev/annotation/Queryable.java +++ b/openaev-model/src/main/java/io/openaev/annotation/Queryable.java @@ -43,8 +43,8 @@ /** * Defines the JPA path used to query this property. Follows Spring Data Specification conventions - * (e.g. {@code "organization.id"}). - * Path should end by a primitiv value or this can lead to UnsupportableOperation. + * (e.g. {@code "organization.id"}). Path should end by a primitiv value or this can lead to + * UnsupportableOperation. */ String path() default ""; @@ -54,10 +54,21 @@ */ String[] paths() default {}; + /** + * Defines the complete list of operators available for filtering a collection by the decorated + * property. If undefined, the client is responsible for guessing which operators are applicable + * according to the decorated property type. + */ Filters.FilterOperator[] overrideOperators() default {}; + /** + * Define a value here to specify a type hint for clients to treat the decorated property as this + * type. Example: String[].class; clients parsing this hint will be encouraged to treat the value + * of the decorated property as an array of strings. + */ Class clazz() default Unassigned.class; + /** Defines the Enum source for the allowed values of the decorated property, if applicable. */ Class refEnumClazz() default Unassigned.class; /** From 4697bcae1c5cea9f059fa0f6f70b3ce6e4d19024 Mon Sep 17 00:00:00 2001 From: Antoine MAZEAS Date: Mon, 1 Dec 2025 09:33:14 +0100 Subject: [PATCH 4/4] fix exception name Signed-off-by: Antoine MAZEAS --- .../src/main/java/io/openaev/annotation/Queryable.java | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/openaev-model/src/main/java/io/openaev/annotation/Queryable.java b/openaev-model/src/main/java/io/openaev/annotation/Queryable.java index 85b08ad8e31..23a8f362f54 100644 --- a/openaev-model/src/main/java/io/openaev/annotation/Queryable.java +++ b/openaev-model/src/main/java/io/openaev/annotation/Queryable.java @@ -43,8 +43,8 @@ /** * Defines the JPA path used to query this property. Follows Spring Data Specification conventions - * (e.g. {@code "organization.id"}). Path should end by a primitiv value or this can lead to - * UnsupportableOperation. + * (e.g. {@code "organization.id"}). Path should end by a primitive value or this can lead to + * UnsupportedOperationException. */ String path() default "";