[clarification]: Consider rationalizing the zoo of possible query return types

[gavinking]

Specification

Data

I need clarification on ...

do we really need so many?

Additional information

In the Javadoc of @Find, and in the module-level documentation, we find some rather long lists of possible things that users might want to return, depending on the semantics of their query, their own personal aesthetic sensibilities, and, apparently, on the phase of the moon and the price of West Texas Crude:

• List
• Page
• Slice
• KeysetAwarePage
• KeysetAwareSlice
• Set
• Stream
• Streamable
• Iterable
• Collection
• Optional (for single instances)
• The entity type itself (for single instances)
• Array of the entity type

The module-level doc even sneaks in LinkedHashMap as an option!

Some of these options are needed. Some of them, IMO, aren't:

• Collection is a worse List
• Streamable is an even worse List
• Iterable is the worst List
• Set doesn't really seem necessary either—if the caller wants to put the results in a Set, it can quite easily call new HashMap()
• LinkedHashMap looks like he got drunk and gatecrashed a party full of posh people

I would kick at least some of these guys out.

[njr-11]

I would say that Set is the worst of all of these because it even loses the order (unless it is something like a LinkedHashSet, but it doesn't say it is that). We should definitely get rid of Set.

Collection and Iterable seem unnecessary given that a repository can define the return type as List and a user can still write code that treats it as a Collection or Iterable if they want. We can get rid of these.

LinkedHashMap probably should have been removed already. It is likely left over from when we were exploring all the different options that could be possible as return types. If a user really wants the LinkedHashMap behavior, they could implement it themselves by accepting a List and putting the elements into a LinkedHashMap of their own. I don't see why we should make the Jakarta Data provider do this for them.

Getting rid of the above doesn't stop any vendors from supporting the extra return types on their own.

I believe Streamable is something that Spring asked for (they have a similar interface) and Micronaut also liked. @otaviojava worked on this one and might have more background information from them on it.

At first glance, it looks like a way to obtain multiple streams for the same result, but you can already do that by just returning a List and obtaining multiple streams from the list. If we keep it, it would be nice if its JavaDoc could include an example illustrating the additional value that it provides.

[gavinking]

I believe Streamable is something that Spring asked for (they have a similar interface) and Micronaut also liked. @otaviojava worked on this one and might have more background information from them on it.

At first glance, it looks like a way to obtain multiple streams for the same result, but you can already do that by just returning a List and obtaining multiple streams from the list. If we keep it, it would be nice if its JavaDoc could include an example illustrating the additional value that it provides.

I mean I guess I would say that if Java really needs an API for a cached stream—and I'm really not sure it does—then Jakarta Data is not the right place to define it. If it's so useful then I wonder why it's not in java.util.stream where it would seem to belong.

And so I agree with you that if this is what you want to do then List is sitting right there in java.util staring you in the face, asking you if it's chopped liver.

[gavinking]

This was fixed by #511.