This article discusses backward-incompatible changes in Jersey 3.1.0. While Jersey tries to minimize these incompatible changes, the changes are forced by the Platform Specification Project, API project, security reasons, or an unstoppable evolution.
Jersey 3.1.0 drops compatibility with JDK 8.
Jakarta EE 10 defines a minimum JDK 11 runtime to be supported and many Jakarta EE 10 APIs and their implementations will drop JDK 8 support, too. Only Jersey 2.x will continue supporting JDK 8. The JDK version support in Jakarta EE was decided during a community vote, and many community members supported JDK 17 as a minimum JDK version. While it looks like a big jump forward, it is possible that JDK 17 will become the minimum supported JDK version in Jakarta EE 11, which should come next year.
The default HttpUrlConnector no longer supports HTTP Patch on JDK 16+.
The default HttpUrlConnection supports only HTTP 1.1 request methods. Other methods, such as HTTP Patch, are not supported by the HttpUrlConnection and Jersey overcomes the issue using reflection, if configured using the SET_METHOD_WORKAROUND property, for instance:
client.property(HttpUrlConnectorProvider.SET_METHOD_WORKAROUND, true)Starting with JDK 16, reflection on JDK internal classes is not allowed, and HTTP Patch can no longer be used with the default HttpUrlConnector. This applies to Jersey 2.x, 3.0.x, too, but it is worth mentioning it here.
One solution is to use any other Jersey connector.
Another solution is to use the X-HTTP-Method-Override HTTP header.
Please be aware of possible exploits.
The uncaught exception is never propagated to the underlying I/O container.
Jakarta REST 3.1 defines a new requirement for a default ExceptionMapper<Object> so that the Exception is never propagated to the Servlet Container or any other container Jersey integrates with. This is important for frameworks integrating Jersey. The exception is still logged, and users will see the exception in the (server) log as they are used to.
No Jackson 1 support.
Jackson 1 support is dropped in Jersey 3.1.0. Jackson 1 is unmaintained for some time, and Jackson 2 is recommended to be used.
GitHub repository change
The historical Jersey (pre-Eclipse) repository was moved from https://github.com/jersey/jersey to https://github.com/javaee/jersey and the repository is read-only.
The current repository is located at https://github.com/eclipse-ee4j/jersey. However, since all projects are asked to move from eclipse-ee4j GitHub organization to jakartaee GitHub organization, the current repository URL can change in the future. Similarly, the Jakarta REST API GitHub repository moved from https://github.com/eclipse-ee4j/jaxrs-api to https://github.com/jakartaee/rest. Fortunately, the redirect works well.
Jersey GitHub master branch will no longer contain Jersey 2.x.
The repository uses several branches, master is used for 2.x, 3.x is used for 3.0.x, branch 3.1 is used for 3.1.x releases. The current plan is to use master for the latest development, similar to other projects.
Documentation URL
The original Jersey documentation has been accessible from https://jersey.github.io. The URL still provides a redirect to the current https://eclipse-ee4j.github.io/jersey/ documentation website.
While Jersey 2.x used URI https://eclipse-ee4j.github.io/jersey.github.io/documentation/latest/index.html, Jersey 3.0.x uses https://eclipse-ee4j.github.io/jersey.github.io/documentation/latest3x/index.html.
This possibly changes two ways. First, the https://eclipse-ee4j.github.io prefix will change because of the GitHub repository change discussed above. Second, the latest/index.html will be used for the documentation of the highest Jersey version. Jersey 2.x documentation will be in latest2x/index.html.
Changes in processing JAX-RS code by Jersey
Since Jersey 3.1.0, ClientRequest#getRequestHeader(String) returns null instead of an empty list in case the specified header does not exist. This change is a reflection of the Jakarta REST requirement coming with the new Specification.
Another change comes with a resource method returning CompletionStage, for instance
@GET
public CompletionStage> getMethod() {...} In Jersey 2.x, the message body provider receives entity type CompletionStage<List<String>>, which is not properly handled by most entity providers. The property ServerProperties.UNWRAP_COMPLETION_STAGE_IN_WRITER_ENABLE set to true ensures List<String> is passed to the message body provider. In Jersey 2.x, it is kept like this for backward compatibility with older Jersey versions. Jersey 3.1.0 sets the default value of this property to true, and the List<String> is passed to providers by default, as would be expected.
Deprecated Application#getSingletons()
Jakarta REST 3.1 deprecates Application#getSingletons() which can cause warnings with the older applications.
Summary
There are minor incompatibility changes coming with the Jersey 3.1.0 release. But we believe the changes impact the Jersey customers only by a minimum. As always, if you have any concerns, let us know on our issue tracker.