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 a web.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 the web.xml file to get server-side asynchronous support. This requirement does not exist for the jaxrs-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"));

HttpHeaders.getRequestHeader(String headerName) method return when the specified headerName value does not exist

jaxrs-2.1 behavior

The method returns null.

restfulWS-3.0 behavior

The method returns an empty String object.

Response.readEntity() method return when it is called on an empty entity

jaxrs-2.1 behavior

The method returns an IllegalStateException exception.

restfulWS-3.0 behavior

The method returns an empty String object.

Liberty ClientBuilder properties are deprecated

jaxrs-2.1 properties

  • com.ibm.ws.jaxrs.client.receive.timeout property

  • com.ibm.ws.jaxrs.client.connection.timeout property

restfulWS-3.0 alternatives

  • ClientBuilder.connectTimeout(long timeout, TimeUnit unit) method

  • ClientBuilder.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.

See also