Skip to main content

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
Re: [jakartaee-platform-dev] [External] : Re: Simplifying the platform by merging some specs?


In the end, I think what Arjan advocates for and most of the people here agree with, is simplifying Jakarta EE for users. I think that boils down to basically 2 major things.

One is documentation and how Jakarta EE is presented. We should make it easy to understand the holistic view which Jakarta EE Platform users care about. Most of the time they aren't really interested how these holistic concepts are separated into individual specs.

Another major thing is that there's no logical or formal grouping of specifications. Even though there are many specifications that touch similar topics (JSON-P and JSON-B, or DI and CDI, or the 3 Security specs), they are completely independent in the same way as any other spec.

We could improve documentation so that it revolves around high level topics like Security, JSON, rather than specs. The Jakarta EE tutorial already does that pretty well already. But when we promote amd advocate about Jakarta EE, most of the time, only either the whole platform or individual specs/implementations are promoted and blogged about. We should start showing how things fit together when we talk, blog and present at conferences about Jakarta EE.

That leads me to the second thing, and that is formal grouping of similar specs and codumentation projects. If we officially recognize some spec groups, (e.g. Security, JSON, HTTP, DI, etc. ), it would be easier to evolve them, promote and talk about them in unified groups than about individual specifications. To distinguish them with the platform or profiles, I would call them frameworks but that's a matter of taste really.

On top of that, I think that we should consideer merging or grouping some documentation utility projects in EE4J. There are Jakarta EE tutorial and First Cup tutorial (part of EE platform), then CargoTracker, Eclipse Starter for Jakarta EE, and Examples for Jakarta EE as separate Eclipse projects. This is far too many and scattered. If something's worth merging, then all these developer-oriented projects with tools and examples, so that it's easier to maintain them, contribute to them, and also integrate them well together, hopefully at a prominent place in, e.g.

As Romain concluded, merging specs if the result for users is the same (e.g. spec A and B become module A and module B of the same spec), only brings advantage internally (simplifies the release, makes it easier for the same committers to work on both APIs, maintain a single TCK and spec document, etc.) It's not necessary to merge specs in order to help the users. I think we should focus on the end result that matter's most and that's clarity, usability, and good developer documentation.

Kind regards,

Ondrej Mihályi

Senior Payara Service Engineer
Payara - Supported Enterprise Software for Jakarta EE and MicroProfile Applications
US: +1 415 523 0175 | UK: +44 207 754 0481


Payara is a proud recipient of the prestigious Queen's Award for Enterprise: International Trade 2021

Payara-Tech LDA, Registered Office: Rua Nova de São Pedro no. 54, 2nd floor, room “D”, 9000 048 Funchal, Ilha da Madeira, Portugal

VAT: PT 515158674 | | info@xxxxxxxxxxx | @Payara_Fish

From: jakartaee-platform-dev <jakartaee-platform-dev-bounces@xxxxxxxxxxx> on behalf of Romain Manni-Bucau <rmannibucau@xxxxxxxxx>
Sent: 08 March 2022 12:54
To: jakartaee-platform developer discussions <jakartaee-platform-dev@xxxxxxxxxxx>
Subject: Re: [jakartaee-platform-dev] [External] : Re: Simplifying the platform by merging some specs?

Le mar. 8 mars 2022 à 12:45, arjan tijms <arjan.tijms@xxxxxxxxx> a écrit :

On Tue, Mar 8, 2022 at 8:50 AM Romain Manni-Bucau <rmannibucau@xxxxxxxxx> wrote:
The only gain I see is to make the release smoother.

The gain I see is also for the user, who can start using just "JSON" or "Security". As mentioned, users have been asking me time and again why Jakarta EE has 3 different security frameworks, while Spring just has "Spring Security".

Hmm, can be wrong but I see it as a side solution instead of a real solution.
There are too much "incompatible" (they are bridged more than linked) specs? let's deprecate N-1 specs and keep only one strong basis others can be built on.
So it is more about cleaning the ecosystem than merging inconsistent rooms, no?

Partially it's also a matter or presententing ourselves to our users and organizing our documentation, but documentation typically follows the spec/API organisation.

Agree on the goal but it does not prevent the spec to be independent. This always had been the EE (all) role to do that job so I guess it is the same there. Sub-spec should just let them be eaten easily in a more global website/pdf so adopting accross the board a standard format (out of my head adoc, md, latex etc) + a few human investment would solve that better than a merge of a few spec which rolls the ball just a bit further but does not fully solve the issue no?

Just as an example, this one is overwhelming and confusing to users it seems:

The response I got was, as mentioned, "why are there 3 security frameworks?", but also "why are there 2 dependency injection frameworks?" and "Why are there two JSON frameworks?".

And I guess you always had been able to answer it properly and even justify it -  at least the last two ;).
So it sounds like a comm issue more than anything.
If you merge spec in a repo but still deliver the modular jars you will get the same issue until it is properly documented and as you pointed there, it is at EE level to do that, not in subspecs I think.

So overall I agree with all your points but don't think the merge will solve any of them for end users, this is why I think the only gain can be at release time and I think it is not worth it.
Now if you create another thread to discuss these issues we can surely find other solutions but sticking to the root topic I think it is not helping.

Hope it makes sense.

Kind regards,
Arjan Tijms

jakartaee-platform-dev mailing list
To unsubscribe from this list, visit

Back to the top