Doc for Jakarta RESTful Web Services (JAX-RS) 3.1 (part of EE 10)

[jim-krueger]

ID work is needed for Jakarta RESTful Web Services (JAX-RS) 3.1 as part of epic issue OpenLiberty/open-liberty#18739.

Primarily the Jakarta REST support for Open Liberty in EE10 will come from RESTEasy (Version 6.2.0-Final). However, there are some areas that we should expound upon.

• Changes in Global Handler support: Issue 22598
• Java Se Bootstrap support is new to Jakarta RESTful WS 3.1 (EE10), but it is optional and Liberty will not be supporting it: Issue 22541
• Multipart Support: We currently support multipart via internal IBM APIs that were created for previous releases. Multipart is now part of the Jakarta RESTful WS 3.1 specification and has official APIs. For now we will continue to support both and will eventually deprecate our internal mechanism. This will need to be explained.

In addition, we will be adding information to Issue 20868 as we find migration or other issues that need also may need corresponding documentation.

Also, we will be working on a Skills Transfer Education document and demo for L2 that may also be useful for crafting the doc pages for this feature. If you have any questions or concerns, please let us know. Thanks!

[dmuelle]

Thanks @jim-krueger - w/r/t Multipart, we should review this topic-
https://openliberty.io/docs/latest/send-receive-multipart-jaxrs.html

at some point I made the following note in the epic:

as part of ID for this feature, we should update the following doc to clarify that the io.openliberty.jaxrs30 Maven/Gradle dependency is not required for multipart form/data in Resftful WS 3.1 and later

not sure if that's still accurate but wanted to make a note here

[jim-krueger]

@dmuelle Absolutely. The doc you are referring to above is our initial support. We are going to want to change this to demonstrate the "spec" way of doing this.

[jim-krueger]

Adding separate comments for the individual potential documentation needs. We can update each comment as we go along with additional information etc..

[jim-krueger]

Multipart:

• Updates to https://openliberty.io/docs/latest/send-receive-multipart-jaxrs.html Update: Talked with David and since the functions in this section is being deprecated and the replacement function is defined in the specification (ie. no longer Liberty-specific APIs), then this documentation is no longer needed.

• A comment will need to be added to the "Differences between Jakarta EE 10 and 9.1" section detailing the new spec version and that we will continue to support the IBM-specific APIs for this release, but they will eventually be deprecated.

• Add an update to the Jax-RS 3.0, 2.1 and 2.0 feature pages indicating that the multipart functionality in these versions is being deprecated in RESTful Webservices 3.1 and replaced with an official spec-defined API.

[jim-krueger]

Global Handlers:

In previous Liberty feature versions of RESTful Web Services (JAXRS) and XML Web Services (JAXWS), the Web Services Global Handler SPI package com.ibm.wsspi.webservices.handler was automatically enabled .
Starting in Jakarta EE 10, Global Handlers are disabled by default. As with previous versions, users will need to create a user feature to configure a Global Handler. However, users will now be required to add the io.openliberty.globalhandler-1.0 protected Liberty feature to their user feature's manifest file in order to enable the SPI package.

Manifest-Version: 1.0
Subsystem-Type: osgi.subsystem.feature
IBM-Feature-Version: 2
Subsystem-Version: 1.0.0
Subsystem-Content: MySimpleGlobalHandler.jakarta;version="1.0.0",
io.openliberty.globalhandler-1.0; type="osgi.subsystem.feature"
Subsystem-SymbolicName: MySimpleGlobalHandlerFeature;visibility:=public
Subsystem-ManifestVersion: 1.0
IBM-ShortName: MySimpleGlobalHandlerFeature

[jim-krueger]

Java Se Bootstrap:

This is a new (Optional API) in Jakarta Rest 3.1. Open Liberty will not be supporting this, however we will be adding a new warning message indicated that this function is not supported.
Update: Rather than a warning message, we went with throwing an UnsupportedOperationException. See https://github.com/OpenLiberty/open-liberty/pull/23004

[jim-krueger]

Mandatory usage of JSONB instance provided by user's ContextResolver:

• Comment needed for "Differences between Jakarta EE 10 and 9.1" section.
• Info: jakarta issue 742

[jim-krueger]

Automatic service provider registration

• Likely just a "Differences between Jakarta EE 10 and 9.1" section comment.

[jim-krueger]

Default exception mapper

• Likely just a "Differences between Jakarta EE 10 and 9.1" section comment.

[jim-krueger]

Fields and Bean Properties:

• Array types may be specified for @CookieParam , @FormParam , @HeaderParam ,
  @MatrixParam and @QueryParam parameters.

• Likely just a "Differences between Jakarta EE 10 and 9.1" section comment.

[jim-krueger]

New method #hasProperty(String) wherever #getProperty(String) exists

• Likely just a "Differences between Jakarta EE 10 and 9.1" section comment.

[jim-krueger]

New method #hasProperty(String) wherever #getProperty(String) exists

• Likely just a "Differences between Jakarta EE 10 and 9.1" section comment.

[jim-krueger]

Response.created(URI) now resolves relative URIs into an absolute URI against the base URI, not against the request URI anymore:

• Likely just a "Differences between Jakarta EE 10 and 9.1" section comment.

[jim-krueger]

Declaring Media Type Capabilities:

• Clarified resource matching when Content-Type or Accept are missing in request.
• Likely just a "Differences between Jakarta EE 10 and 9.1" section comment.

[jim-krueger]

Constructors of Cookie class are deprecated in favor of new Cookie.Builder class

Constructors of NewCookie are deprecated in favor of new NewCookie.Builder class

• Likely just a "Differences between Jakarta EE 10 and 9.1" section comment.

[jim-krueger]

@dmuelle Please see the update to the Global Handlers comment above and let me know if you have any questions. Thanks

[jim-krueger]

Servlet:

In previous Liberty feature versions of RESTful Web Services (JAXRS) and RESTful Web Services Client, the Servlet APIs were made available to any Open Liberty application.
Starting with Jakarta EE 10, Open Liberty applications that require Servlet APIs must additionally add the servlet-6.0 feature to their server.xml file.

[jim-krueger]

Concurrency:

In previous Liberty feature versions of RESTful Web Services (JAXRS) and RESTful Web Services Client, the Concurrency APIs were made available to any Open Liberty application.
Starting with Jakarta EE 10, Open Liberty applications that require Concurrency APIs must additionally add the servlet-6.0 feature to their server.xml file.

[dmuelle]

Hi @jim-krueger - for the global handlers update, what specifically does this information show? is it the content that the user needs to add to their user feature manifest file?

Manifest-Version: 1.0
Subsystem-Type: osgi.subsystem.feature
IBM-Feature-Version: 2
Subsystem-Version: 1.0.0
Subsystem-Content: MySimpleGlobalHandler.jakarta;version="1.0.0",
io.openliberty.globalhandler-1.0; type="osgi.subsystem.feature"
Subsystem-SymbolicName: MySimpleGlobalHandlerFeature;visibility:=public
Subsystem-ManifestVersion: 1.0
IBM-ShortName: MySimpleGlobalHandlerFeature

[jim-krueger]

@dmuelle - That is a sample of a manifest file for a user feature. In my example above I put in bold the only line that needs to be added to the Subsystem-Content:
io.openliberty.globalhandler-1.0; type="osgi.subsystem.feature"

If possible I think making that line bold and red would help.

[dmuelle]

Thanks Jim- I believe I have all these changes on draft now:

https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/jakarta-ee10-diff.html#restfulws

If possible I think making that line bold and red would help.

We can't use red due to accessibility concerns and bold isnt showing up in the code block. But I tweaked the description to make it more obvious that is the line you need to add. Let me know if any further changes are needed. If not, you can add the technical reviewed label to this issue to sign off and the changes will publish when EE10 is Ga. Thanks

[jim-krueger]

@dmuelle , The review looks good except for Concurrency. Here is an update for that:

When the restfulWS-3.0 and restfulWSClient-3.0 Liberty features are enabled, the Concurrency APIs are available to any Open Liberty application by default.

Starting with RESTful Web Services 3.1 and RESTful Web Services Client 3.1, the Concurrency APIs are no longer available by default. For Open Liberty applications that require Concurrency APIs, you must also add the concurrent-3.0 feature to the server.xml file.

[dmuelle]

Thanks for reviewing- I've made that update in the draft

https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/jakarta-ee10-diff.html#_concurrency_apis_availability

[dmuelle]

@ramkumar-k-9286 this is ready for peer review:

https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/jakarta-ee10-diff.html#restfulws

[ramkumar-k-9286]

Peer Review

Add io.openliberty.globalhandler-1.0; type="osgi.subsystem.feature" to your user feature manifest file, as shown in the following manifest file example:
->
Add io.openliberty.globalhandler-1.0; type="osgi.subsystem.feature" to your user feature manifest file, as shown in the following manifest file example**.**

Support for array types as parameters is added to the following field and bean property annotations:
->
Support for array types as parameters is added to the following field and bean property annotations**.**

[dmuelle]

@ramkumar-k-9286 thanks, fixed.