Jakarta RESTful Web Services Client3.13.02.12.0
This feature enables support for the Jakarta RESTful Web Services 3.1 Client API.
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 client functions by enabling the RESTful Web Services Client 3.0 feature. The JAX-RS 2.0 and 2.1 client implementations are available through the Java RESTful Services Client feature (jaxrsClient-2.0 and jaxrsClient-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. For more information, see Differences between Jakarta RESTful Web Services 3.0 and Java Restful Services (JAX-RS).
Enabling this feature
To enable the Jakarta RESTful Web Services 3.1 Client feature, add the following element declaration into your server.xml
file, inside the featureManager
element:
<feature>restfulWSClient-3.1</feature>
Examples
With the RESTful Web Services Client APIs, you can specify properties on the client that configure settings like timeouts, proxy hosts, and SSL properties. You can set these properties in the Java code or in the server configuration. The following examples show how you can set webTarget
values in the server.xml
file so that you can change them without the need to edit and recompile the Java code.
Change settings when an application moves from development to production environments
If the application is deployed in a different environment, certain settings might need to change. For example, an application might initially be written to run in a development environment, where all remote RESTful services are available without a proxy server and can connect quickly, as shown in the following example:
public Widget getRemoteWidget(String id) {
Client client = ClientBuilder.newClient();
WebTarget target = client.target("https://somehost:9443/WidgetStore/widgets/");
Widget widget = target.path(id).request().get(Widget.class);
return widget;
}
However, when this application is deployed in a production environment it might be necessary to add new settings because remote RESTful services might need a proxy server to establish connections. You can specify new settings by adding the following configuration to your server.xml
file:
<webTarget uri="https://somehost:9443/WidgetStore*" proxyHost="myProxyHost" proxyPort="55555" proxyType="HTTP"
connectionTimeout="60000" receiveTimeout="60000" />
This configuration alters the webTarget
element in the Java code to use the proxyHost
and proxyPort
attributes to specify the values for a HTTP proxy server. The connectionTimeout
and receiveTimeout
attributes are used to set connection and receive timeouts of 60 seconds (60,000 milliseconds) instead of the default timeouts.
Modify SSL configuration in development
During development, an SSL certificate might not match the server hostname that tests the application because it matches the server hostname that deploys the application in production. The configuration can be changed during development to use a different SSL configuration or to disable hostname verification of SSL certificates:
<webTarget uri="https://somehost:9443/WidgetStore*" sslConfig="mySSLRef" disableCNCheck="true" />
To maintain application security, do not disable SSL verification in production environments.
Set custom properties
If your application uses providers such as the ClientRequestFilter
or ClientResponseFilter
interfaces, they can read and react to custom properties that are set on the RESTful Web Services Client or the WebTarget
interface. You can also change the Open Liberty client implementation behavior by setting custom properties. These properties can be set programmatically by using the webTarget.property("myCustomProperty", "someValue")
configuration but you can also set custom properties by specifying the WebTarget
element in your server.xml
file:
<webTarget uri="https://somehost:9443/WidgetStore*" myCustomProperty="prod" />
For a complete list of pre-defined properties, see webTarget.
Enable MicroProfile JWT authentication for RESTful Web Services
If you add the RESTful Web Services Client feature to your server configuration along with the MicroProfile JSON Web Token feature, you can use MicroProfile JWT to authenticate RESTful Web Services. With the Open Liberty RESTful Web Services client, you can use MicroProfile JWT as an authentication method for RESTful Web Services, as shown in the following example:
<webTarget uri="http://localhost:56789/protectedResourceWithMPJWT*" authnToken="mpjwt" />
The authnToken
attribute in the webTarget
element adds MicroProfile JWT as an authorization header when the RESTful Web Services service that is specified by the http://localhost:56789/protectedResourceWithMPJWT*
endpoint URL in the uri
attribute is called.
Standard API packages provided by this feature
jakarta.activation
jakarta.annotation
jakarta.annotation.security
jakarta.annotation.sql
jakarta.ws.rs
jakarta.ws.rs.client
jakarta.ws.rs.container
jakarta.ws.rs.core
jakarta.ws.rs.ext
jakarta.ws.rs.sse
Developing a feature that depends on this feature
If you are developing a feature that depends on this feature, include the following item in the Subsystem-Content
header in your feature manifest file.
io.openliberty.restfulWSClient-3.1; type="osgi.subsystem.feature"