Module de.cuioss.http
Package de.cuioss.http.client

Class ResilientHttpHandler<T>

java.lang.Object
de.cuioss.http.client.ResilientHttpHandler<T>
Type Parameters:
T - the target type for content conversion
public class ResilientHttpHandler<T> extends Object
ETag-aware HTTP handler with stateful caching capabilities and built-in retry logic.

This component provides HTTP-based caching using ETags and "If-None-Match" headers, with resilient HTTP operations through configurable retry strategies. It tracks whether content was loaded from cache (304 Not Modified) or freshly fetched (200 OK).

Thread-safe implementation using ReentrantLock for virtual thread compatibility.

Retry Integration

The handler integrates with RetryStrategy to provide resilient HTTP operations, solving permanent failure issues in well-known endpoint discovery and JWKS loading.
Since:
1.0
Author:
Oliver Wolff

  • Constructor Details

    • ResilientHttpHandler

      public ResilientHttpHandler(@NonNull @NonNull HttpHandlerProvider provider, @NonNull @NonNull HttpContentConverter<T> contentConverter)
      Creates a new ETag-aware HTTP handler with unified provider for HTTP operations and retry strategy.

      This constructor implements the HttpHandlerProvider pattern for unified dependency injection, providing both HTTP handling capabilities and retry resilience in a single interface.

      Parameters:
      provider - the HTTP handler provider containing both HttpHandler and RetryStrategy
      Throws:
      IllegalArgumentException - if provider is null

  • Method Details

    • withoutRetry

      public static <T> ResilientHttpHandler<T> withoutRetry(@NonNull @NonNull de.cuioss.tools.net.http.HttpHandler httpHandler, @NonNull @NonNull HttpContentConverter<T> contentConverter)
      Creates a ResilientHttpHandler instance without retry capability.

      This static factory method creates a ResilientHttpHandler that only provides ETag caching and content conversion functionality, without retry logic. For retry-capable HTTP operations, use ResilientHttpHandler(HttpHandlerProvider, HttpContentConverter) instead.

      Type Parameters:
      T - the type of content to be converted
      Parameters:
      httpHandler - the HTTP handler for making requests
      contentConverter - the converter for HTTP content
      Returns:
      a ResilientHttpHandler instance configured without retry capability

    • load

      public HttpResultObject<T> load()
      Loads HTTP content with resilient retry logic and ETag-based HTTP caching.

      This method integrates RetryStrategy to provide resilient HTTP operations, automatically retrying transient failures and preventing permanent failure states that previously affected WellKnownResolver and JWKS loading.

      Virtual Threads Integration

      The retry strategy now uses Java 21 virtual threads with non-blocking delays for efficient resource utilization. While this method maintains a synchronous API for compatibility, the internal retry operations run asynchronously on virtual threads, providing:

      • Non-blocking delays: Uses CompletableFuture.delayedExecutor() instead of Thread.sleep()
      • Resource efficiency: No blocked threads during retry delays
      • High scalability: Supports thousands of concurrent retry operations
      • Better composition: Internal async operations can be composed efficiently

      Result States

      • VALID + 200: Content freshly loaded from server (equivalent to LOADED_FROM_SERVER)
      • VALID + 304: Content unchanged, using cached version (equivalent to CACHE_ETAG)
      • VALID + no HTTP status: Content unchanged, using local cache (equivalent to CACHE_CONTENT)
      • WARNING + cached content: Error occurred but using cached data (equivalent to ERROR_WITH_CACHE)
      • ERROR + no content: Error occurred with no fallback (equivalent to ERROR_NO_CACHE)

      Retry Integration

      The method uses the configured RetryStrategy to handle transient failures:
      • Network timeouts and connection errors are retried with exponential backoff
      • HTTP 5xx server errors are retried as they're often transient
      • HTTP 4xx client errors are not retried as they're typically permanent
      • Cache responses (304 Not Modified) are not subject to retry
      Returns:
      HttpResultObject containing content and detailed state information, never null