Introduce new jakarta servlet related APIs

Hi devs,

We currently have 3 main areas where we expose servlet related APIs:

  1. XWikiContext/Context#request/response
  2. $request/$response bindings in the script context
  3. through the org.xwiki.container.Container component by casting Request and Response to ServletRequest and ServletResponse

In the context of the javax → jakarta move I would like to propose to deprecate, but not remove, any of the existing APIs which expose javax APIs and to bridge them as much as possible.

It’s used in many important extensions, a good example being authenticators, so just changing the package would be a huge breakage and I believe we can manage to implement a good enough bridge, at least for most used things in the XWiki ecosystem.

This means introducing new APIs to access the jakarta flavor of the servlet APIs and I would like to propose the following:

  • as an alternative to $request/$response script bindings, introduce a new container script service (something like $services.container.request/response), I know $services.container.request is clearly longer than $request but, like everything else, $services.container.request is definitely what we would have done if the concept was introduced now, so it’s more consistent with the rest of XWiki script APIs
  • for the Java side of things the idea would also be to abandon XWikiContext and focus on xwiki-platform-container-servlet API entry point, I’m just not sure yet if the best are new methods in the existing org.xwiki.container.servlet.ServletRequest along with the javax ones or some entirely new org.xwiki.container.servlet.HttpServletRequest for example (the benefit being to have a new, clean API which does not contain any old stuff)

I don’t want to discuss all the details of some new API now, they will come later. For now, I would “just” like to be sure that we agree (or not) on the principal of considering any access to Servlet APIs through oldcore APIs like XWikiContext and the direct $request/$response script bindings as legacy and that people should always go through org.xwiki.container.* APIs or a new container script service in the jakarta era of XWiki.


Do you propose to try moving them to legacy already (i.e. perform all refactoring in XS to use alternative during 16.x) or do you think it would be too much of work?
There’s probably a big bunch of doc / snippets to update as well once we deprecate them.


Feels like it would be easier for maintenance on the long run.


It’s indeed huge work, so not sure about the timing, but in theory yes the general idea is to move them to an actual legacy module eventually.