Differences between Jakarta EE 9.1 and 8.0
If you are updating your application from using Jakarta EE 8.0 features to using Jakarta EE 9.1 features, changes in API behavior might require you to update your application code. Furthermore, the names and version numbers of some of the Open Liberty features that support the Jakarta EE platform are updated for the Jakarta EE 9.1 release.
For more information about feature name changes in Jakarta EE 9.1, see Jakarta EE 9.1 feature updates.
Differences between Jakarta RESTful Web Services 3.0 and Java Restful Services (JAX-RS)
With the release of the Jakarta RESTful Web Services 3.0 feature (restfulWS-3.0
) as part of Jakarta EE 9.1, the underlying Jakarta RESTful Web Services implementation for Open Liberty changed from Apache CXF to RESTEasy. This change results in certain API behavior changes that might require you to update your application code.
Jakarta RESTful Web Services, formerly known as JAX-RS, is a Jakarta EE platform API. In Open Liberty 21.0.0.12 and later, you can use Jakarta RESTful Web Services 3.0 functions by enabling the RESTful Web Services 3.0 feature. The JAX-RS 2.0 and 2.1 implementations are available through the Java RESTful Services feature (jaxrs-2.0 and jaxrs-2.1). The change in feature name and version reflects the change in API package name prefixes from javax.*
to jakarta.*
, which is common to all Jakarta EE 9.1 features. The underlying JAX-RS implementation for Open Liberty also changed from Apache CXF to RESTEasy.
If you are updating your server configuration from using the jaxrs-2.1
feature to the restfulWS-3.0
feature, certain changes in API behavior might require you to update your application code. The following sections detail changes in behavior between the jaxrs-2.1
and restfulWS-3.0
features.
CDI injection with the Application.getSingletons() method
- jaxrs-2.1 behavior
You can create an instance of a singleton class and a second instance is generated from CDI to inject into the singleton classes.
- restfulWS-3.0 behavior
You are required to get an instance of your singleton class from CDI if you want CDI injection into the singleton classes.
Server-side asynchronous support
- jaxrs-2.1 behavior
Server-side asynchronous behavior is automatically supported.
- restfulWS-3.0 behavior
If the application does not include a
web.xml
file, or if it includes aweb.xml
file that contains only the servlet name, asynchronous behavior is automatically supported.If the application includes a
web.xml
file that contains a servlet class or other configuration options, you must specify<async-supported>true</async-supported>
in theweb.xml
file to get server-side asynchronous support. This requirement does not exist for thejaxrs-2.1
feature.
Null properties in the jakarta.ws.rs.client API
- jaxrs-2.1 behavior
A client property with a null value is maintained as part of the client internal configuration state.
- restfulWS-3.0 behavior
A client property with a null value is removed from the client internal configuration state.
For example, with the jaxrs-2.1
feature, the following code returns containsProp? true
. With the restfulWS-3.0
feature, it returns containsProp? false
.
ClientBuilder cb = ClientBuilder.newBuilder().property("someProp", null);
System.out.println("containsProp? " + cb.getConfiguration().getProperties().containsKey("someProp"));
Liberty ClientBuilder properties are deprecated
- jaxrs-2.1 properties
com.ibm.ws.jaxrs.client.receive.timeout
propertycom.ibm.ws.jaxrs.client.connection.timeout
property
- restfulWS-3.0 alternatives
ClientBuilder.connectTimeout(long timeout, TimeUnit unit)
methodClientBuilder.readTimeout(long timeout, TimeUnit unit)
method
RESTful Web Services parameter non-CDI injection
- jaxrs-2.1 behavior
JAX-RS parameters can be injected into a resource class constructor.
- restfulWS-3.0 behavior
JAX-RS parameters cannot be injected into a resource class constructor. Resources are CDI beans. Only CDI injection can occur in resource class constructors.
For example, the following code is valid for an application that runs on a server that specifies the jaxrs-2.1
feature, but not for the restfulWS-3.0
feature.
@Path("myPath")
public class MyResource {
private String q1;
public MyResource(@QueryParam("q1") String q1) {
this.q1 = q1;
}
@GET
public Response get() {
doSomethingWith(q1);
// ...
}
}
For an application that runs on a server that specifies the restfulWS-3.0
feature, you must rewrite the code similar to the following example.
@Path("myPath")
public class MyResource {
@GET
public Response get(@QueryParam("q1") String q1) {
doSomethingWith(q1);
// ...
}
}
Subresource locator methods path names
- restfulWS-3.0 behavior
Subresource locator methods can share the same path as a regular subresource method.
- jaxrs-2.1 behavior
Subresource locator methods must not share the same path as a regular subresource method.
For example, the following code is valid for an application that runs on a server that specifies the jaxrs-2.1
feature, but results in an error with the restfulWS-3.0
feature.
@Path("/root")
public class MyRootResource {
/*
* Subresource locator method.
*/
@Path("subresource")
public MyObject postSub() {
return new MyObject();
}
public static class MyObject {
@POST
public String hello() {
return "MyObject.hello()";
}
}
/*
* Subresource method.
*/
@GET
@Path("subresource")
public String getSub() {
return "MyRootResource.getSub()";
}
}
With the restfulWS-3.0
feature, this code returns an error that is similar to the following example.
[6/16/21, 13:48:03:249 CDT] 00000050 org.jboss.resteasy.resteasy_jaxrs.i18n
Application subclasses that use CDI injection must be annotated with the @ApplicationPath annotation
- jaxrs-2.1 behavior
Application subclasses are treated as managed beans and do not require the
@ApplicationPath
annotation for CDI injection.- restfulWS-3.0 behavior
Application subclasses are not treated as managed beans and therefore require the
@ApplicationPath
annotation to include CDI injection. Resources are now CDI beans. Only CDI injection can occur only in resource class constructors.
CDI and bean-defining annotations
- jaxrs-2.1 behavior
To use CDI in applications, users must explicitly enable CDI with the Contexts and Dependency Injection feature.
- restfulWS-3.0 behavior
RESTful web services always use CDI.
The
@ApplicationPath
,@Path
, and@Provider
annotations are now CDI bean-defining annotations.By default, RESTful web services that are annotated with the
@Path
annotation are request-scoped.By default, RESTful web services that are annotated with the
@Provider
or@ApplicationPath
annotations are application-scoped.
EJBs that are listed in the getClasses() method for an application subclass
- jaxrs-2.1 behavior
Local interfaces of the EJB bean that are listed in the
getClasses()
method are ignored.- restfulWS-3.0 behavior
Local interfaces of the EJB bean that are listed in the
getClasses()
method cause an exception that prevents the application from starting.
Wildcard characters in the @ApplicationPath annotation
- jaxrs-2.1 behavior
Wildcard characters are accepted for the
@ApplicationPath
annotation, for example,@ApplicationPath(value="/rest1/*")
.- restfulWS-3.0 behavior
Wildcard characters are not accepted for the @ApplicationPath annotation. All such requests are rejected.