This article will guide you through setting connection timeout and read timeout in Jersey using ClientConfig. When developing RESTful applications using Jersey, it is crucial to manage timeouts effectively. Timeouts help prevent requests from hanging indefinitely when the server is slow to respond or unreachable.

1. Understanding Connection Timeout and Read Timeout

Properly setting these timeouts (connection and read) ensures our application does not wait indefinitely for responses, improving resilience and performance.

1.1 Connection Timeout

The connection timeout defines the maximum duration, in milliseconds, that the client will wait while attempting to establish a connection with the server. If the connection is not successfully established within this specified time limit, the request is aborted, and a timeout exception is thrown. Properly configuring this timeout helps prevent indefinite waiting periods and ensures that the application can handle network delays or unresponsive servers more effectively.

1.2 Read Timeout

The read timeout specifies the maximum duration, in milliseconds, that the client will wait for a response after sending a request to the server. If the server fails to respond within the defined time limit, the request is terminated, and a timeout exception is triggered. Configuring an appropriate read timeout helps prevent prolonged waiting periods, improves application responsiveness, and ensures efficient handling of slow or unresponsive servers

2. Dependencies Required

Before implementing the solution, it is essential to include the necessary dependencies in the pom.xml file:

<dependencies>
 <!-- Jersey Core Client -->
 <dependency>
 <groupId>org.glassfish.jersey.core</groupId>
 <artifactId>jersey-client</artifactId>
 <version>3.1.9</version>
 </dependency>

 <!-- Jersey Injection for Dependency Management -->
 <dependency>
 <groupId>org.glassfish.jersey.inject</groupId>
 <artifactId>jersey-hk2</artifactId>
 <version>3.1.9</version>
 </dependency>
</dependencies>

For Gradle users, add:

dependencies {
 implementation 'org.glassfish.jersey.core:jersey-client:3.1.9'
 implementation 'org.glassfish.jersey.inject:jersey-hk2:3.1.9'
}

3. Configuring Connection Timeout and Read Timeout

To set timeouts in Jersey, we configure ClientConfig using ClientProperties. Below is a complete example demonstrating how to configure connection timeout and read timeout in Jersey.

public class JerseyTimeoutExample {
 
 private static final Logger logger = Logger.getLogger(JerseyTimeoutExample.class.getName());
 
 public static void main(String[] args) {
 
 // Create a ClientConfig instance
 ClientConfig clientConfig = new ClientConfig();
 clientConfig.property(ClientProperties.CONNECT_TIMEOUT, 5000);
 clientConfig.property(ClientProperties.READ_TIMEOUT, 10000);

 // Create a client using the configured settings
 Client client = ClientBuilder.newClient(clientConfig);

 // Define the target URL
 WebTarget target = client.target("https://jsonplaceholder.typicode.com/posts/1");
 try (Response response = target.request().get()) {

 logger.log(Level.INFO, "Response Code: {0}", response.getStatus());
 logger.log(Level.INFO, "Response Body: {0}", response.readEntity(String.class));
 } catch (Exception e) {
 logger.log(Level.WARNING, "Request failed: {0}", e.getMessage());
 
 } finally {
 client.close();
 }
 }
}

3.1 Code Walkthrough and Analysis

Step 1: Configuring Client Timeout Settings

A ClientConfig object is created to apply custom configurations for managing timeouts. The ClientProperties.CONNECT_TIMEOUT is set to 5000 milliseconds (5 seconds), ensuring that the client does not wait indefinitely while attempting to establish a connection. Additionally, the ClientProperties.READ_TIMEOUT is set to 10000 milliseconds (10 seconds), defining the maximum duration the client will wait for a response from the server before triggering a timeout exception. These configurations help improve network efficiency and prevent long delays in request handling.

Step 2: Creating a Jersey Client

A Jersey Client instance is created using ClientBuilder.newClient(clientConfig), which applies the timeout settings.

Step 3: Defining the Target URL

The WebTarget object points to the API URL (https://jsonplaceholder.typicode.com/posts/1).

Step 4: Sending the Request and Handling the Response

A GET request is executed using target.request().get(), and if the request is successful, the response status and body are printed. In case of a timeout or failure, an error message is displayed to notify the user. To ensure proper resource management, both the response and client are closed within the finally block, preventing potential memory leaks and ensuring efficient cleanup.

3.2 Expected Output

If the request completes within the specified time, you will see:

Jan 29, 2025 4:32:09 P.M. com.jcg.examples.JerseyTimeoutExample main
INFO: Response Code: 200
Jan 29, 2025 4:32:09 P.M. com.jcg.examples.JerseyTimeoutExample main
INFO: Response Body: {
 "userId": 1,
 "id": 1,
 "title": "sunt aut facere repellat provident occaecati excepturi optio reprehenderit",
 "body": "quia et suscipit\nsuscipit recusandae consequuntur expedita et cum\nreprehenderit molestiae ut ut quas totam\nnostrum rerum est autem sunt rem eveniet architecto"
}

4. Using the client.property() Method

The client.property() method allows setting timeouts dynamically on a Jersey client instance. This approach provides flexibility by applying timeout configurations at runtime rather than during object creation.

public class JerseyClientPropertyExample {

 private static final Logger logger = Logger.getLogger(JerseyClientPropertyExample.class.getName());

 public static void main(String[] args) {
 // Create a Jersey client
 Client client = ClientBuilder.newClient();

 // Set connection and read timeouts using client.property()
 client.property(ClientProperties.CONNECT_TIMEOUT, 5000); // 5 seconds
 client.property(ClientProperties.READ_TIMEOUT, 10000); // 10 seconds

 WebTarget target = client.target("https://jsonplaceholder.typicode.com/posts/5");

 Response response = null;
 try {
 response = target.request().get();
 logger.log(Level.INFO, "Response Code: {0}", response.getStatus());
 logger.log(Level.INFO, "Response Body: {0}", response.readEntity(String.class));
 } catch (Exception e) {
 logger.log(Level.WARNING, "Request failed: {0}", e.getMessage());
 } finally {
 if (response != null) {
 response.close();
 }
 client.close();
 }
 }
}

In this example, a Jersey client is created using ClientBuilder.newClient(). The client.property() method is then used to set connection and read timeouts dynamically. The connection timeout is set to 5000 milliseconds (5 seconds) and the read timeout is set to 10000 milliseconds (10 seconds). The client then sends a GET request to a valid API endpoint, and if successful, the response status and body are printed.

5. Using the ClientBuilder API

Instead of setting properties dynamically, timeouts can be configured during client creation using the ClientBuilder API. This method is preferred for defining timeout settings at the time of client instantiation.

public class JerseyClientBuilderMain {
 
private static final int TIMEOUT = 5000; // 5 seconds
private static final Logger logger = Logger.getLogger(JerseyClientBuilderMain.class.getName());

 public static void main(String[] args) {
 JerseyClientBuilderMain clientExample = new JerseyClientBuilderMain();
 String response = clientExample.viaClientBuilder();
 logger.log(Level.INFO, "Response: {0}", response);
 }

 public String viaClientBuilder() {
 // Create a ClientBuilder instance and configure timeouts
 ClientBuilder builder = ClientBuilder.newBuilder()
 .connectTimeout(TIMEOUT, TimeUnit.MILLISECONDS)
 .readTimeout(TIMEOUT, TimeUnit.MILLISECONDS);

 // Build the client and execute the request
 return get(builder.build());
 }

 private String get(Client client) {
 WebTarget target = client.target("https://jsonplaceholder.typicode.com/posts/6");
 Response response = null;
 try {
 response = target.request().get();
 return response.readEntity(String.class);
 } catch (Exception e) {
 return "Request failed: " + e.getMessage();
 } finally {
 if (response != null) {
 response.close();
 }
 client.close();
 }
 }
}

This implementation defines a main class called JerseyClientBuilderMain, where a Jersey client is created using ClientBuilder.newBuilder(). Timeouts are set using connectTimeout() and readTimeout(), both configured to 5000 milliseconds (5 seconds). The viaClientBuilder() method initializes the client with these timeout settings and then calls the get() method to send an HTTP request.

6. Implementing a Retry Mechanism

Timeouts and temporary network failures are common, so implementing a retry mechanism improves reliability. The example below retries failed requests up to 3 times before giving up.

public class JerseyRetryExample {

 private static final Logger logger = Logger.getLogger(JerseyRetryExample.class.getName());
 private static final int MAX_RETRIES = 3; // Maximum retry attempts
 private static final int CONNECT_TIMEOUT = 5000; // 5 seconds
 private static final int READ_TIMEOUT = 10000; // 10 seconds

 public static void main(String[] args) {

 ClientConfig clientConfig = new ClientConfig();
 clientConfig.property(ClientProperties.CONNECT_TIMEOUT, CONNECT_TIMEOUT);
 clientConfig.property(ClientProperties.READ_TIMEOUT, READ_TIMEOUT);

 Client client = ClientBuilder.newClient(clientConfig);
 WebTarget target = client.target("https://jsonplaceholder.typicode.com/posts/1");

 Response response = null;
 int attempt = 0;

 while (attempt < MAX_RETRIES) {
 try {
 attempt++;
 logger.log(Level.INFO, "Attempt {0}", attempt + " to send request...");

 response = target.request().get();

 // If request is successful, print response and break retry loop
 if (response.getStatus() == 200) {
 logger.log(Level.INFO, "Response Code: {0}", response.getStatus());
 logger.log(Level.INFO, "Response Body: {0}", response.readEntity(String.class));
 break;
 } else {
 logger.log(Level.WARNING, "Request failed with status: {0}", response.getStatus());
 }
 } catch (Exception e) {
 logger.log(Level.WARNING, "Attempt {0}", attempt + " " + e.getMessage());
 }

 // Small delay before retrying
 try {
 Thread.sleep(2000); // Wait 2 seconds before retrying
 } catch (InterruptedException e) {
 Thread.currentThread().interrupt();
 }
 }

 // Close resources
 if (response != null) {
 response.close();
 }
 client.close();
 }
}

The retry logic is implemented using a while loop, allowing the request to be attempted up to MAX_RETRIES times. If a request fails, an error message is printed, and the system waits for a short delay before retrying. When a successful response (HTTP 200) is received, the loop terminates, preventing unnecessary retries. In case of failures, such as timeouts or server errors, exceptions are caught, and another attempt is initiated. To prevent overwhelming the server, a Thread.sleep(2000); introduces a 2-second delay between retries, ensuring a controlled retry mechanism.

Expected Output

If the request succeeds on the first attempt:

INFO: Attempt 1 to send request...
Jan 29, 2025 9:04:04 P.M. 
Jan 29, 2025 9:04:08 P.M. com.jcg.examples.JerseyRetryExample main
INFO: Response Code: 200
Jan 29, 2025 9:04:08 P.M. com.jcg.examples.JerseyRetryExample main
INFO: Response Body: {
 "userId": 1,
 "id": 1,
 "title": "sunt aut facere repellat provident occaecati excepturi optio reprehenderit",
 "body": "quia et suscipit\nsuscipit recusandae consequuntur expedita et cum\nreprehenderit molestiae ut ut quas totam\nnostrum rerum est autem sunt rem eveniet architecto"
}

To test the retry mechanism using an unreachable API endpoint, we can use a valid domain with a non-existent path, such as https://jsonplaceholder.typicode.com/nonexistent. This endpoint will return an HTTP 404 (Not Found) error, simulating a failed request that triggers the retry logic.

Since the /nonexistent path does not exist, the server will respond with HTTP 404 (Not Found). The client will retry the request three times before stopping:

7. Conclusion

This article explored multiple ways to configure Jersey connection and read timeouts to prevent excessive waiting periods when interacting with external APIs. We demonstrated how to set timeouts dynamically using the client.property() method and configure them during client creation using the ClientBuilder API. We also implemented a retry mechanism to automatically reattempt failed requests, ensuring improved reliability in network communication.

By configuring connection and read timeouts in Jersey, we can prevent long waits and improve application responsiveness. This ensures that our client handles network latency efficiently, leading to better performance and user experience.

8. Download the Source Code

This article covered configuring connection and read timeouts in Jersey.