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

Interface HttpContentConverter<T>

Type Parameters:
T - the target type for content conversion
All Known Implementing Classes:
StringContentConverter
public interface HttpContentConverter<T>
Content converter for transforming HTTP response bodies into typed objects with proper BodyHandler support.

This interface provides both content conversion and appropriate BodyHandler selection, allowing ResilientHttpHandler to leverage Java HTTP Client's type-safe body handling. The raw response type is an implementation detail hidden from clients.

Implementations should handle conversion errors gracefully by returning Optional.empty() when conversion fails or when there is no meaningful content to convert.

Since:
1.0
Author:
Oliver Wolff

  • Method Summary

    Modifier and Type
    Method
    Description
    Optional<T>
    convert(Object rawContent)
    Converts raw HTTP response body to the target type.
    T
    emptyValue()
    Provides a semantically correct empty value for this content type.
    HttpResponse.BodyHandler<?>
    getBodyHandler()
    Provides the appropriate BodyHandler for this converter.

  • Method Details

    • convert

      Optional<T> convert(Object rawContent)
      Converts raw HTTP response body to the target type.

      Returns Optional.empty() when:

      • Conversion fails due to malformed content
      • Content is empty or null
      • Content cannot be meaningfully converted
      Parameters:
      rawContent - the raw HTTP response body (may be null or empty)
      Returns:
      Optional containing converted content, or empty if conversion fails

    • getBodyHandler

      HttpResponse.BodyHandler<?> getBodyHandler()
      Provides the appropriate BodyHandler for this converter.

      This method enables proper leveraging of Java HTTP Client's type-safe body handling, avoiding unnecessary intermediate conversions and preserving data integrity. The raw type is handled internally by the implementation.

      Examples:

      • For JSON/XML: HttpResponse.BodyHandlers.ofString(charset)
      • For binary data: HttpResponse.BodyHandlers.ofByteArray()
      • For large content: HttpResponse.BodyHandlers.ofInputStream()
      Returns:
      the BodyHandler appropriate for this converter

    • emptyValue

      @NonNull T emptyValue()
      Provides a semantically correct empty value for this content type.

      This method should return a meaningful "empty" representation that makes sense for the target type T, rather than trying to convert meaningless input.

      Examples:

      • For JSON: empty JsonNode or empty object
      • For String: empty string
      • For Collections: empty collection
      • For custom objects: default/empty instance
      Returns:
      semantically correct empty value for type T, never null