[clarification]: Shall We Introduce an Annotation to Mark Projection Records, or Leave It to Jakarta Data Providers?

[otaviojava]

Specification

https://github.com/jakartaee/data/blob/main/api/src/main/java/jakarta/data/repository/Find.java

I need clarification on ...

Jakarta Data supports projections using Java records with @Select to map entity attributes:

public record Name(String firstName,
                   String middleName,
                   @Select("lastName") String surname) {}

Currently, there is no annotation to explicitly declare a record as a projection target. This creates ambiguity for annotation processors and tooling that aim to generate metadata or validate mappings at compile time.

Should Jakarta Data define a dedicated annotation (e.g., @Projection) to mark these records as intended for projections, or should it be left to individual Jakarta Data providers to infer and handle this as needed?

This would not impact runtime behavior but would enhance compile-time clarity and tooling support.

Additional information

No response

[gavinking]

I recently ran into a reason why we might need this: for execution on Graal VM, classes which should be exposed for reflection need to be explicitly marked as such. For entities and embeddables we have @Entity and @Embeddable, but we have no such thing for these little projection objects.

@Sanne brought this up.

[njr-11]

One scenario to think about here will be when a user wants to use a third-party record class that they don't control and to which they cannot add annotations. We currently allow for that because @Select can be declared on the repository method instead. Preserving that ability will need to be weighed against the needs/advantages brought up in this issue.

[gavinking]

Yeah, sure, I'm not arguing that we should require this.

[otaviojava]

Have an annotation for the providers that won't work with Reflection or need to use it with GraalVM.

[Sanne]

If it's not going to be required then I'm not sure how helpful it would be for GraalVM: in terms of opt-in users already have solutions. It just gets very tricky, with misleading error messages, when one forgets to declare the right registrations.

[otaviojava]

I will write down the annotation, so we can discuss.
What I have on my mind:

• The annotation is mandatory
• It is free to the Jakarta Data provider to support Projection without the annotation.

[gavinking]

So if we're going to introduce this thing, then we need to reconsider the value() member we added to @Find, and probably remove it.

Because this new annotation, @Selection, for consistency with @Select (unless we rename @Select back to @Project), could be used in two ways:

In the most common case, it would be applied to the record type itself:

@Selection(Book.class)
record BookSummary(String isbn, String title) {}

@Find
List<BookSummary> summaries();

Less commonly, it could be applied directly on the repository method:

record BookSummary(String isbn, String title) {}

@Find
@Selection(Book.class)
List<BookSummary> summaries();

Note that the argument Book.class would default to the primary entity type of the repository if not explicitly specified.

[njr-11]

So if we're going to introduce this thing

It would be fine with me if we didn't. I liked what we had before adding it, with only the Select annotation for the user to be concerned with, and even that being optional when inferring names from record components.

[gavinking]

It would be fine with me if we didn't.

I agree that we have not made any decision to go down this path, which is why I was a little bit surprised to see a pull request already.

[Don't get me wrong, it's sometimes very useful to have a pull request to demonstrate a straw man proposal when the proposal is complicated and confusing, but I don't think that's the case here.]

[Sanne]

It would be fine with me if we didn't.

I agree as well: to be clear, I didn't mean to push for this - just pointing out the problem with GraalVM for your awareness.

It would be odd to have to impose restrictions just for the sake of GraalVM users. It would be ideal to find a better solution, or to have this have some additional value for non-GraalVM users as well to have a stronger rationale.

[gavinking]

@Sanne, let's say we didn't do this.

What would the user have to write in order to register the record for reflection in Graal VM?

[gavinking]

And, another question: couldn't a, say, Quarkus build step just inspect all repository methods and automatically register the return types?