Module de.cuioss.http

Package de.cuioss.http.client.retry

Interface RetryStrategy

All Known Implementing Classes:

ExponentialBackoffRetryStrategy

Functional Interface:

This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.

@FunctionalInterface
public interface RetryStrategy

HTTP-specific retry strategy interface using virtual threads and asynchronous execution.

Async Design with Virtual Threads

This interface leverages Java 21's virtual threads to provide efficient, non-blocking retry operations:

• Non-blocking delays - Uses CompletableFuture.delayedExecutor() instead of Thread.sleep()
• Virtual thread execution - Operations run on lightweight virtual threads
• Composable operations - CompletableFuture API enables natural async composition
• Resource efficient - No blocked threads during retry delays
• Scalable - Handles thousands of concurrent retry operations

Result Pattern Approach

Continues to use the CUI result pattern with enhanced async capabilities:

• No exceptions for flow control - All error states become result states
• Rich error context - HttpResultObject contains retry metrics, error codes, and details
• Forced error handling - Cannot access result without checking state
• Graceful degradation - Built-in fallback support with default results
• State-based flow - FRESH, CACHED, STALE, RECOVERED, ERROR states

Usage Patterns

Blocking Usage (Legacy Compatibility)

 RetryStrategy strategy = RetryStrategies.exponentialBackoff();
 HttpResultObject<String> result = strategy.execute(operation, context).get();

 if (!result.isValid()) {
     // Handle error cases
     useFallbackContent(result.getResult());
 } else {
     processResult(result.getResult());
 }
 

Async Composition (Recommended)

 strategy.execute(operation, context)
     .thenCompose(result -> {
         if (result.isValid()) {
             return processResult(result.getResult());
         } else {
             return handleError(result);
         }
     })
     .thenAccept(processed -> updateCache(processed))
     .exceptionally(ex -> handleException(ex));
 

Method Summary

Modifier and Type	Method	Description
<T> CompletableFuture<HttpResultObject<T>>	execute(HttpOperation<T> operation, RetryContext context)	Executes the given HTTP operation with retry logic using virtual threads and async execution.
static RetryStrategy	none()	Creates a no-op retry strategy (single attempt only).

Method Details

execute

<T> CompletableFuture<HttpResultObject<T>> execute(HttpOperation<T> operation,
 RetryContext context)

Executes the given HTTP operation with retry logic using virtual threads and async execution.

This method runs operations on virtual threads with non-blocking delays between retry attempts. The implementation uses CompletableFuture.delayedExecutor() with virtual thread executors to provide efficient, scalable retry operations without blocking threads during delays.

Type Parameters:

T - the type of result returned by the operation

Parameters:

operation - the HTTP operation to retry

context - retry context with operation name and attempt info

Returns:

CompletableFuture containing HttpResultObject with result and comprehensive error/retry information

none

static RetryStrategy none()

Creates a no-op retry strategy (single attempt only). Useful for disabling retry in specific scenarios or configurations.

Returns:

a retry strategy that executes the operation exactly once using virtual threads