Jaxrs-api: Jakarta REST 3.1 Planning

[spericas]

Creating this issue for the purpose of planning the 3.1 release. As I understand it, EE 9.1 is currently scheduled for Q1 2021. There have been a number of topics under discussion for 3.1, some of which we all agree on and some of which we do not. I propose that we use this issue to finalize the discussion and formalize a plan for 3.1.

Planning for Jakarta REST 3.1

1. Bootstrap API
2. Clarifications and minor additions
   https://github.com/eclipse-ee4j/jaxrs-api/issues?q=is%3Aissue+milestone%3A3.1+
3. Deprecations in preparation for CDI changes in 4.0?
4. Deprecations in anticipation of matching algorithm changes?

I believe we are mostly in agreement about (1) and (2). @arjantijms created a wiki that relates to (3) and there has been an issue filed about (4) #468. Also please make sure all issues in scope are targeted to the 3.1 milestone.

[spericas]

From @arjantijms's wiki that relate to (3):

Proposed Changes

• Implementations MUST support @Inject.
• Application MAY use @Inject.
• Support for ContextResolver

Open Questions

• Implementations MUST bring a bundled CDI 2.0 implementation? Alternative is that application has choice of CDI 2.0 implementation and Jakarta REST implementation MUST provide a CDI 2.0 Extension to support it.

[andymc12]

I've been hearing that EE 9.1 is not intending to include any API changes, and is primarily focussed on the move to Java 11. That said, it should not prevent us from releasing 3.1 - but the 3.1 release may not be pulled into an EE release until 9.2 or 10 (whichever comes first).

Open Questions

• Implementations MUST bring a bundled CDI 2.0 implementation? Alternative is that application has choice of CDI 2.0 implementation and Jakarta REST implementation MUST provide a CDI 2.0 Extension to support it.

I'm very much in favor of mandating that implementations bring their own CDI 3.0 (or maybe 3.X to allow for the CDI spec to increment too?) implementation. From an implementation point of view, it's annoying and difficult to maintain all of the if-CDI-is-available-do-this-if-not-do-that logic, and I can imagine that it is frustrating for users too (i.e. "all I did was add CDI and now my REST app works differently!"). I think we will end up simplifying a lot of things in the spec by mandating the dependency on CDI.

That said, I know that some users think CDI is too heavyweight for simpler apps. My hope is that the extra weight of CDI would be offset somewhat by removing the dependency injection and lifecycle management code out of vanilla-JAX-RS implementations.

On the roadmap, we had a stretch goal of adding Multipart support. I'd still like to keep that on the radar - and I'm hoping to have some time to put together a proposal for it in January.

[spericas]

I've heard the same about 9.1, and hope is not true :) Doing a full EE release takes a lot of time and effort, and just doing this for JDK 11 is hardly innovative IMO. It would be the third Eclipse release in which nothing "truly" new is delivered.

On the topic of CDI, as I understand it, there's also the possibility of a "lighter one" coming in the future. Alignment with such a version should help mitigate the criticism.

[arjantijms]

As far as I understood, point releases can be included, although they should definitely not contain major breaking changes. E.g. the Faces 4.0 as we have planned (where we fully remove the native managed bean system) would not be in scope for Jakarta 9.1, so neither would be Jakarta REST 4.0 as planned.

I wonder btw, is CDI indeed actually heavyweight, or is it a rumour being spread by people who maybe have other interests? If it's really the case, heavyweight in what? Conceptual API? Footprint on disk? Startup time?

Jersey now contains for instance HK2, which as you of course know is a DI container as well. It maintains beans, it does lookups, it has scopes and injection and even has a few things CDI does not have like the server wide scopes. What in particular do those some people think is more heavyweight in CDI compared to HK2?

[chkal]

I've heard the same about 9.1, and hope is not true :) Doing a full EE release takes a lot of time and effort, and just doing this for JDK 11 is hardly innovative IMO.

+100

• Implementations MUST bring a bundled CDI 2.0 implementation? Alternative is that application has choice of CDI 2.0 implementation and Jakarta REST implementation MUST provide a CDI 2.0 Extension to support it.

One quick thought. For what @spericas proposed above (especially Implementations MUST support @Inject) we actually don't have any dependency on CDI at all. It's just about Jakarta Dependency Injection 2.0 (previously JSR 330). Maybe this is sufficient for a first step?

[mkarg]

I recently had a discussion with @ivar grimstad, and he told me that we can publish releases freely as we like. It is up to the platform to decide into which EE release they do adopt a particular release of a subproject. So my opinion is, we should not assume or discuss what EE wants / plans, but go our own way simply.

[arjantijms]

One quick thought. For what @spericas proposed above (especially Implementations MUST support @Inject) we actually don't have any dependency on CDI at all. It's just about Jakarta Dependency Injection 2.0 (previously JSR 330). Maybe this is sufficient for a first step?

Could be, but that's potentially more confusing still.

If it's explicitly defined to be injected by CDI, this means users can obtain references via the CDI bean manager, decorate injected beans, veto them via extensions, etc etc.

[m-reza-rahman]

Firstly, it is truly encouraging to see the Jakarta REST team moving the technology forward. I hope many folks will chime in with their thoughts. Might it be a good thing to post a notification on the user alias: https://accounts.eclipse.org/mailing-list/jaxrs-dev?

I think the Ambassadors' Jakarta EE 10 Contribution Guide current draft summarizes the potential big ticket items for Jakarta REST well: https://docs.google.com/document/d/1uZFBoIujXCc-gQhCzh_ZdlKEsrsV0yVVIHzBTI3usF8/edit?usp=sharing:

• Using CDI/@Inject instead of @Context injection.
• Provide a Java SE/standalone bootstrap API.
• Add native support for multipart/form-data.

I hope this helps. Again, kudos to the team for moving things forward.

Reza Rahman
Jakarta EE Ambassador, Author, Blogger, Speaker

Please note views expressed here are my own as an individual community member and do not reflect the views of my employer.

[jansupol]

Do I get it right that Jakarta EE 9.1 specs review is planned for January 31, so if Jakarta REST 3.1 is to be part of it, the review ballot for 3.1 is to start on January 31, latest?

[mkarg]

Do I get it right that Jakarta EE 9.1 specs review is planned for January 31, so if Jakarta REST 3.1 is to be part of it, the review ballot for 3.1 is to start on January 31, latest?

No that is not a spec review, this is a plan review. This means, we must tell what our plan is. Example: "3.1 = 3.0 + Java SE + minor additions + another TCK for that; we have it mostly done and can deliver it until end of February.".

I do not see a problem with that deadline. I already hacked some minimal purely Java SE + JUnit based TCK for SeBootstrap which I can finish and we can review quickly in Q1. This also includes some minor wording for the spec. Problems would only occur if anybody insists on having the tests being incorporated into the orginal platform TCK - which I think is already ruled out IIUC.

[mkarg]

As the major target for Jakarta EE 9.1 (and as such, for Jakarta RESTful Web Services .1) is to allow applications to be written in Java 11, we maybe should put that prominently on our documentation, or even in the spec?

[spericas]

@mkarg Yes, we can mention something about Java 11 in the spec.

@jansupol My understanding is the same is inline with @mkarg's. We should finish up and present our plan by the end of January. That is the main purpose of this issue.

[spericas]

Open Questions

• Implementations MUST bring a bundled CDI 2.0 implementation? Alternative is that application has choice of CDI 2.0 implementation and Jakarta REST implementation MUST provide a CDI 2.0 Extension to support it.

I'm very much in favor of mandating that implementations bring their own CDI 3.0 (or maybe 3.X to allow for the CDI spec to increment too?) implementation. From an implementation point of view, it's annoying and difficult to maintain all of the if-CDI-is-available-do-this-if-not-do-that logic, and I can imagine that it is frustrating for users too (i.e. "all I did was add CDI and now my REST app works differently!"). I think we will end up simplifying a lot of things in the spec by mandating the dependency on CDI.

I agree that this would make things easier for everyone. However, it seems like a big change for a dot release; also not certain about the implications related to the integration of Jakarta REST into EE. Perhaps we can enforce @Inject support in our TCKs without this type of bundling --at least not yet.

That said, I know that some users think CDI is too heavyweight for simpler apps. My hope is that the extra weight of CDI would be offset somewhat by removing the dependency injection and lifecycle management code out of vanilla-JAX-RS implementations.

I believe is the fact that CDI goes beyond DI and that it is very dynamic. It supports extensions, events, decorators, interceptors, etc. These are all great, but arguably not necessary in all applications --while basic DI typically is. There's something to be said about separating these parts and letting application developers pick what they need. The other aspect against CDI is startup time: everything is done dynamically which makes it very flexible but not suited for certain types of apps that require very fast restarts.

On the roadmap, we had a stretch goal of adding Multipart support. I'd still like to keep that on the radar - and I'm hoping to have some time to put together a proposal for it in January.

That would be great.

[arjantijms]

The other aspect against CDI is startup time: everything is done dynamically which makes it very flexible but not suited for certain types of apps that require very fast restarts.

Not necessarily. Any jar that contains an extension isn't scanned by CDI at all, and that extension can directly add types, which is quite similar what you do when you add types in HK2 to the Habitat/ServiceLocator. A beans.xml can disable scanning for the application completely.

HK2 has events as well (publishers and subscribers, which you publish via a Topic). HK2 even has an eventing SPI.

In HK2 you would do:

@Inject 
private Topic<MyEvent> myEventPublisher; 

myEventPublisher.publish(new SomeEvent()); 

HK2 has interceptors as well, see e.g. org.glassfish.hk2.api.InterceptionService

[spericas]

@arjantijms I was not trying to compare it with HK2 (which is not related to Jakarta REST, but Jersey), but instead to the DI part of Jakarta REST. Extensions are not the only issue in restarts: all beans are discovered dynamically which is very flexible but not ideal in _some_ environments.

In any case, I'm not personally against CDI in any way, I'm just relaying the message of those that are skeptical.

[arjantijms]

I was not trying to compare it with HK2 (which is not related to Jakarta REST, but Jersey),

I understand, but HK2 was just used as an example since I'm familiar with it (via Payara/GlassFish) and it's indeed used for at least 1 Jakarta REST implementation. HK2 (to the best of my knowledge) was never used as an argument against Jersey being heavyweight.

all beans are discovered dynamically which is very flexible but not ideal in some environments.

Not necessarily as I mentioned in the comment above. Via a beans.xml you can disable scanning, and archives with extensions aren't scanned regardless.

I'm just relaying the message of those that are skeptical.

I understand that too ;) It's just that people often are quick to call something heavyweight.

[spericas]

all beans are discovered dynamically which is very flexible but not ideal in some environments.

Not necessarily as I mentioned in the comment above. Via a beans.xml you can disable scanning, and archives with extensions aren't scanned regardless.

Sure, you can, but I don't think that's the point. As I understand it, they want automatic scanning of the beans and injection points but with minimal runtime impact.

[arjantijms]

they want automatic scanning of the beans and injection points but with minimal runtime impact.

For a previous project I created a maven plugin that scanned classes during the build, and prepared an index file. That index file was then directly read by a CDI extension for minimal runtime impact. Incidentally, that's, again, what HK2 does as well (with the org.glassfish.hk2:hk2-inhabitant-generator plugin).

Of course that adds a build-time requirement, which we all decided around 2003 (when EJB used that) to not want.

[spericas]

Back to the planning topic ... After discussing EE 9.1 with a few people it seems that, realistically, we should probably focus on a plan around the first two topics of my original post, namely:

1. Bootstrap API
2. Clarifications and minor additions https://github.com/eclipse-ee4j/jaxrs-api/issues?q=is%3Aissue+milestone%3A3.1+

Anything beyond this will likely be hard to get into EE 9.1, and there may be some pushback for any new additions.

Alternatively, we can do a _simple_ release for EE 9.1 and focus on another release after that with more changes than those above. Personally, I would like to get something "new" into EE 9.1.

On the topic of TCKs, I understand that @mkarg is working on some of them as a standalone set. I believe we may need to get these integrated into the TCK repository as well to get into EE 9.1. I can volunteer to work on porting some of our standalone tests to the TCK repository if so required.

Please provide feedback on these options:

[A] Propose plan to deliver Jakarta REST 3.1 with (1) and (2) into EE 9.1
[B] Simple _no-new-content_ release for EE 9.1 and work on standalone Jakarta REST release after that

Or, alternatively, propose a different plan. It would be good if we can agree on a direction in the next few days.

[mkarg]

[C] Use whatever is already merged to master for Jakarta EE 9.1 plus its documentation.

TCK: I would prefer to not backport into the platform TCK. Even after explicitly asking for it, nobody at the EF has effectively asked us to either do so, neither have we been asked to provide a single executable for the TCK. So it seems, it is pretty OK for the EF, that we keep old and new stuff separated. The WG's rules are that each spec must have a TCK, not that it must be in a single executable, nor that it must be a common repository. So we could simply publish the new TCK on Maven Central and let it be a <dependency> of the old TCK which is just downloaded and executed as part of the big run.

[andymc12]

I agree that we should deliver something new in Jakarta REST 3.1, but based on what I've been seeing in the platform communications, it doesn't look like they will take new function in the EE 9.1 release. That said, it would be nice to at least give them a choice - take either 3.0 or 3.1. So the net is, I'm in favor of option A.

[mkarg]

The only probem I have with that is (compared to just delivering what we already have in master): Do we have the time to fulfil that plan, as it implies things not yet contributed and merged.

[spericas]

The only probem I have with that is (compared to just delivering what we already _have_ in master): Do we have the time to fulfil that plan, as it implies things not yet contributed and merged.

I don't disagree with this. We may need to leave some of the issues in (2) out of the release, but at least we'd have some new functionality.

[Thihup]

I like the idea of enabling CDI by default. But from what I can tell a lot of old deployments just don't work with CDI enabled, mostly because of using an implementation way of using @Inject or using Guice.
Just enabling the CDI the startup time gets increased a lot and (usually) fails in the end. I know this is not fully related, but enabling CDI has caused a lot of pain to me.
In that cases the easiest thing to do is include a Jakarta REST implementation in the packing, enabling it via web.xml and running in a servlet container, where with a web profile / full profile server it just doesn't work.

[mkarg]

@Thihup

In that cases the easiest thing to do is include a Jakarta REST implementation in the packing, enabling it via web.xml and running in a servlet container, where with a web profile / full profile server it just doesn't work.

I assume you mean having a CDI implementation in the packaging.

I wonder if todays this is still a problem, since CDI is auto-enabled since Java EE 7. So maybe we can auto-enabled it, too, but provide a standard option to actively disable it if not wanted. That would be in line with Jakarta EE platform behavior.

[Thihup]

I assume you mean having a _CDI_ implementation in the packaging.

Actually, I mean saying a REST implementation, in my case, I usually packaged Jersey 1 or 2 to be able to run REST endpoints. Including the CDI implementation in the package would include the same troubles as deploying the application in a Jakarta EE web/full profile.

Having a standard way of disabling the CDI in the whole deployment might help. Enabling it by default wasn't a good choice for deployments where we don't have control of the binary, like, Apache Archiva, Jenkins, and XWiki, to name a few.

However, this may be off this topic and more related to CDI itself, but as the new spec might enable it by default it can cause some trouble for some.

[spericas]

As @andymc12 mentioned about a month ago, the main focus of EE 9.1 is moving to JDK 11. My understanding is that in the latest platform discussions, the overwhelming preference is _not_ to introduce any API changes in EE 9.1.

I'm more and more leaning towards the idea of Jakarta REST 3.1 being a _standalone release_; likely the better option for us to resolve the outstanding issues too.

[mkarg]

I'm more and more leaning towards the idea of Jakarta REST 3.1 being a _standalone release_; likely the better option for us to resolve the outstanding issues too.

The decision which version of Jakarta REST is part of Jakarta EE 9.1 is not up to us but up to the Jakarta EE Platform project. We simply go on with our release 3.1 as we planned it, and they can choose to pick it or not.

[spericas]

I'm more and more leaning towards the idea of Jakarta REST 3.1 being a _standalone release_; likely the better option for us to resolve the outstanding issues too.

The decision which version of Jakarta REST is part of Jakarta EE 9.1 is not up to _us_ but up to the Jakarta EE Platform project. We simply go on with our release 3.1 as we planned it, and they can choose to pick it or not.

Well, yes, but there are some tasks that are specific to EE 9.1 such as presenting a plan and working on the TCK integration into the platform. As I understand it, standalone TCKs that aren't part of the official repo won't be accepted in 9.1.

[mkarg]

Well, yes, but there are some tasks that are specific to EE 9.1 such as presenting a plan and working on the TCK integration into the platform. As I understand it, standalone TCKs that aren't part of the official repo won't be accepted in 9.1.

Until today I have requested multiple times in different places that we get told what we actually MUST provide and whether your above assumptions are official resolution of the PMC / WG, but did not receive an official answer. Until then, I do ignore such rumors.

[edbratt]

Any changes to TCKs for Jakarta EE 9.1 MUST be reflected in the Platform TCK. The 9.1 plan does not provide scope for changing any of the operational characteristics or requirements of compatibility testing. This requirement is derived from the Platform TCK feature that allows compatible platforms to certify component compatibility based on the list of components enumerated in the Jakarta EE Platform TCK Users Guide, Section 1.2.1 "Jakarta EE 9 Technologies Tested with Jakarta EE 9 Platform TCK." The stand-alone TCK requirements for DI, CDI, and BV are listed in Platform TCK rule EE21 (section 2.2.2, Rules for Jakarta Platform Enterprise Edition version 9 Products). [Or EE-WP21 for Web Profile in section 3.2.2 of the same guide].

A functional update to RESTful Web Services could be contemplated in a 9.x release, but the TCK changes must be directly implemented into the Platform TCK (and a revised stand-alone RESTful web services TCK until there is agreement between the platform and component teams, probably along with verification that the replacement mechanism is ready to be delivered. This could be done in parallel with development of a completely stand-alone TCK.

I don't intend this to discourage refactoring of the tests. Only to point out that it is almost certainly out of scope and not feasible to incorporate changes that might provide for an additional, external TCK suite (similar to DI for example) in 9.1. The platform team will need coordinate changes such as this when we do get to the point a replacement RESTful Web Services TCK test suite is ready to be factored into the Platform.

[mkarg]

@edbratt AFAIK the original decision was that platform TCK is intended to be split up and replaced by TCKs per spec, not vice versa. So I do not understand why you think we plan a replacement to be factored into the platform. This is not what we strive for. The idea is that Jakarta REST provides new tests in their repo, and the platform team can depend on that binary in the platform TCK.

[spericas]

@mkarg I believe what you're saying has been discussed but is currently _not in scope_ for 9.1.

[mkarg]

@mkarg I believe what you're saying has been discussed but is currently _not in scope_ for 9.1.

That is correct, but this PR is about Jakarta REST 3.1, not about Jakarta EE 9.1. What I like to say is: As the platform doesn't want new APIs at all in 9.1, they anyways cannot adopt Jakarta REST 3.1. So it is irrelevant what is in scope for EE 9.1 or not.

[spericas]

@mkarg I believe what you're saying has been discussed but is currently _not in scope_ for 9.1.

That is correct, but _this_ PR is about Jakarta REST 3.1, not about Jakarta EE 9.1. What I like to say is: As the platform doesn't want new APIs at all in 9.1, they _anyways cannot_ adopt Jakarta REST 3.1. So it is irrelevant what is in scope for EE 9.1 or not.

First, this is an issue and not a PR. Second, I created this issue to discuss EE 9.1 among other things (clearly covered in many comments above). In any case, at this time, we shall continue the discussion of 3.1 without focusing on EE 9.1 anymore.

[edbratt]

@markus the consideration for changing the testing mechanics for the Platform must be coordinated with the Platform committer team. The Platform Spec. (Specifically the TCK User Guide) says that the Platform TCK suffices to verify compatibility of Restful Web Services. If Restful Web Services creates a new TCK with tests that are not included in the Platform TCK then that requirement is not met.
A change like this can be contemplated, but not unilaterally and, the Platform committer team has deemed changes like this, out of scope for 9.1. The opportunity for comment on this is almost certainly past now.
Restful Web Services can create a new TCK for 3.1, but that isn't (currently) going to be pulled in to the platform Spec. So, 9.1 would maintain the Restful Web Services 3.0 requirement. Restful Web Services can release a new Spec. and separate TCK on its own time-line. Implementations (e.g. Jersey) could create versions to suffice for the Compatible Implementation requirement, separate from the Platform. On a separate timeline, the Platform Spec will evolve to bring that new TCK in. Just not (likely) in the Platform 9.1 release.

[mkarg]

@edbratt 100% agreed. But as I told already, as Jakarta EE 9.1 does not want API changes at all, the platform cannot adopt JAX-RS 3.1 at all, so this is irrelevant.

[edbratt]

Irrelevant? I hope this gives some insight into what must happen to make the kind of change that is being contemplated and provides some of the written basis for what requirements must be satisfied and/or changed

[mkarg]

BTW, for the records: Any specification CAN unilaterally decide about their own TCK, but possibly with the result that it is not part of the EE platform anymore, at least for some time.

[mkarg]

@edbratt "Irrelevant" means, as you talk about implications in the EE 9.1 context only, and as RS 3.1 CANNOT be part of of EE 9.1, there is nothing that MUST be satisfied or changed.

[mkarg]

@mkarg I believe what you're saying has been discussed but is currently _not in scope_ for 9.1.

That is correct, but _this_ PR is about Jakarta REST 3.1, not about Jakarta EE 9.1. What I like to say is: As the platform doesn't want new APIs at all in 9.1, they _anyways cannot_ adopt Jakarta REST 3.1. So it is irrelevant what is in scope for EE 9.1 or not.

First, this is an issue and not a PR. Second, I created this issue to discuss EE 9.1 among other things (clearly covered in many comments above). In any case, at this time, we shall continue the discussion of 3.1 without focusing on EE 9.1 anymore.

First, people DO make typos sometimes. ;-)

Second, the title of this issue is "REST 3.1 Planning", not "Jakarta EE 9.1 Planning" and while the description does mention some thoughts upon 9.1, it does not necessarily bind this discussion to EE 9.1. So I want to kindly ask to have two separate isses, one for 3.1, and one for 9.1. Thanks.

[spericas]

@mkarg I believe what you're saying has been discussed but is currently _not in scope_ for 9.1.

That is correct, but _this_ PR is about Jakarta REST 3.1, not about Jakarta EE 9.1. What I like to say is: As the platform doesn't want new APIs at all in 9.1, they _anyways cannot_ adopt Jakarta REST 3.1. So it is irrelevant what is in scope for EE 9.1 or not.

First, this is an issue and not a PR. Second, I created this issue to discuss EE 9.1 among other things (clearly covered in many comments above). In any case, at this time, we shall continue the discussion of 3.1 without focusing on EE 9.1 anymore.

First, people DO make typos sometimes. ;-)

Second, the title of this issue is "REST 3.1 Planning", not "Jakarta EE 9.1 Planning" and while the description does _mention_ some thoughts upon 9.1, it does not necessarily _bind_ this discussion to EE 9.1. So I want to kindly ask to have two separate isses, one for 3.1, and one for 9.1. Thanks.

I will not. It's already been discussed here, which was the original intent.

[mkarg]

So given 3.1 will get skipped for EE 9.1, what is the further topic of this issue, RS 3.1 or EE 9.1?

[edbratt]

Planning for 3.1 ought to continue. It is perfectly okay to propose something and decide, during the planning phase, that that part of the proposal is not going to be feasible. I would hope that this record would help guide readers in a subsequent plan to accomplish the things that were deemed out of scope, for this particular plan.

[edbratt]

Also, the EE 9.1 planning documents are owned by the Platform team -- headed by Kevin. The original Google Doc is here. It is supposed to be moved here, but I don't think that's quite happened just yet. FWIW, I wasn't thrilled with the short window for component team comments, but I recognize the need to swiftly complete the goals as stated in the 9.1 plan.

[mkarg]

@edbratt Thank you for this background information. In fact, both links show the following content:

Jakarta EE 9.1 Release Plan
TBD…

Scope
FAQ

...and nothing else.

[edbratt]

I fixed the google doc. link. Sorry, I was surprised by the TBD page and bungled my copy-paste of the links. The doc. seems to be in some transitional state. I don't think you will find content here that you have not already seen though

[mkarg]

I fixed the google doc. link. ... I don't think you will find content here that you have not already seen though

I know that document very well and it proofs my claim when it literally says: "no Specification API updates will be included in 9.1" and literally "Jakarta RESTful Web Services 3.0" (not "3.1" or "3.x"). So we can simply go on with 3.1 without spending any time in thinking about any 9.1-related arguments.

[edbratt]

works for me