Provide library with an API spec projects can reuse

[lukasj]

Is your feature request related to a problem? Please describe. GenericType class defined by the JAXRS spec is an example of a class, which other specs may wish to reuse. Right now the only option for that is to either "depend" on JAXRS - not everyone wants or needs to do that - or "copy&paste" this class to his project.

I think that by deeper inspection of existing specs, more "utility"-like/common stuff which does not necessarily belong to the given spec's API and may be useful to others can be found.

The artifact could also provide EE platform extensions to SE classes - for example extended ServiceLoader handling provider's priority,..

Describe the solution you'd like The Platform project provides an artifact, let's say jakarta.platform:jakarta.commons with a package jakarta.commons.util- with common functionality other spec projects or implementations can reuse to guarantee consistent behavior across the platform and avoid duplicating the functionality.

Spec projects should not be required to use this artifact, they should be able to opt-in/opt-out to use it at any time if they want to.

Describe alternatives you've considered

• proposing movement of this class to commons annotations project - seems to be an option but not a way to go, since CA project is more about annotations, not classes
• creating a spec project holding these "utility" classes - I think it does not make sense to "write a spec" on how a utility class should behave; it is also not expected others will ever need to "reimplement" provided stuff, so no CI other than the "default one" is expected
• depend on some 3rd party artifact - EE APIs have always been built right on top of Java SE, having a dependency on 3rd party APIs is not desirable

Additional context depending on the output related to semantic versioning and usage of OSGi annotations - there may be a need to support these annotation but it is not desirable to bring 3rd-party non-Jakarta based dependency to the spec projects; an artifact like this could have the package ie jakarta.commons.osgi with annotations from the OSGi

[tomas-langer]

GenericType - the same is javax.enterprise.util.TypeLiteral in CDI. This would also be very useful in Config (to request a generic type), and probably would find its use in any specification that needs to handle types in API, as Class<?> is limited to non-generic types.

[tomas-langer]

I think the following utilities would be useful as well (ideas to be discussed):

• Service loader supporting priorities and module system
• Prioritized interface - to allow dynamic definition of priority (as opposed to static @Priority annotation)
• Priority utility - to find priority of an object, to sort objects by priority etc. - to ensure consistent priority handling across all specs
• Builder interface (if Jakarta would go in the direction of fluent APIs with builders)

[Ladicek]

My personal opinion is that 1. the "commons" projects tend to become dumping grounds, so they should be really minimal and have a high bar for entry; 2. there's already Common Annotations, so that should be repurposed to host utility classes, because why have more than one "commons" projects?

[Emily-Jiang]

We need to first review the current annotations to see whether they are still in use. If not, deprecate them. The other issue is to ensure there are sufficient tests to cover the common apis. There should be a strategy how to ensure these apis are still in use and still useful.

[keilw]

Builder is certainly something pattern specific, but so IMO are other patterns like Repository. They may be a little more specific to CRUD type operations, but go beyond JPA or NoSQL, especially Config is another great example where this could be handy.

On the other hand the likes of Entity, Column, etc. those are probably subject to a "persistence-common" kind of spec that would benefit at least SQL and NoSQL specs under Jakarta EE.

[tomas-langer]

I have created a proposal here: https://docs.google.com/document/d/19eN3pQxtoMNoiqEKasPzbuTjUcYBC4pS0TGT12lVE3Y/edit?usp=sharing Please comment - I will open a discussion in an e-mail thread and on Jakarta platform meeting.

[Ladicek]

Since the document doesn't allow comments, I'll add mine here.

• "Introduce a new specification project" -- would it be possible to rename Jakarta Common Annotations to Jakarta Commons instead? I guess that would entail much less bureaucracy?
• Builder -- what's the point of having an interface Builder? In other words, what are the use cases for abstracting over all possible builders? [1]
• Prioritized interface -- sounds useful (CDI has this already), but instead of extending Comparable, wouldn't it be better to expose a Comparator, in the Comparator.comparing* style?
• Java Model and Introspection API look closely related, but also rather big to be a part of the "commons" project? At least it should be a separate module in the project.
• JPMS support -- frankly, I don't understand what the proposal means, so I'll abstain here :-)

Also, I think the proposal (and later a "project charter" or what would be the best place?) should spell out explicitly the rules for acceptance into "commons". And those rules should not be very lax. Something like 2 (3? 4?) specification projects agreeing on usefulness, and no specification objecting.

[1] I guess one benefit is that the interface could do the annoying self type emulation once and for all. Something like this?

interface Builder<T, THIS extends Builder<T, THIS>> {
    T build();

    @SuppressWarnings("unchecked")
    default THIS self() {
        return (THIS) this;
    }
}

From a quick experiment, this seems to add little value. Also, I've seen many people getting confused by declarations such as this, because they (rightfully so!) don't care WTH F-bounded type polymorphism is.

[tomas-langer]

I have enabled comments in the document. I will update it with yours