Class ResponseCompressionPlan

java.lang.Object
com.soklet.ResponseCompressionPlan

@ThreadSafe public final class ResponseCompressionPlan extends Object
An immutable selection of no compression or one response-compression codec with an optional application-supplied compressed-body provider.

Creating a plan does not compress or cache a body. Soklet first checks whether the selected coding can be used for this response and client, then computes bytes only if a body will be written. In particular, HEAD planning can select compressed representation headers without invoking the codec or provider. A plan cannot bypass transport eligibility or content-coding negotiation.

A provider can wrap Soklet's lazy compression operation with an application-owned cache. Cache keys must identify the exact uncompressed representation and the codec/configuration producing its bytes; a URL or weak ETag alone is not sufficient. Cache only reusable body bytes, not another request's response headers or cookies. Applications own cache capacity, expiration, invalidation, and the handling of private content. Soklet provides no implicit cache.

Plans retain codec and provider references. Codecs must be thread-safe. A provider is invoked synchronously on its request-handling thread; if a plan or provider is reused across requests, its captured state and cache must also support concurrent use. Returned byte arrays are not copied and must remain unmodified while retained for reuse or written by any response.

Author:
Mark Allen
  • Method Details

    • none

      Acquires the shared plan that declines response compression.
      Returns:
      the no-compression plan
    • compress

      Selects a codec, letting Soklet invoke it lazily when the response needs compressed body bytes.

      The codec's content coding is validated and snapshotted during this call; compression is not run.

      Parameters:
      codec - the codec to use
      Returns:
      a compression plan without a custom body provider
      Throws:
      IllegalArgumentException - if the codec's content coding is not a valid compression token
    • compress

      Selects a codec and wraps its lazy body computation with application behavior, such as caching.

      Soklet invokes the provider at most once per written response, after transport and content-coding checks pass, and never for HEAD. Its supplier is bound to this response's exact uncompressed body and the selected codec. The supplier is lazy and memoized per response: repeated successful calls return the same byte array without repeating compression. A cache hit need not call it.

      The supplier is confined to this provider invocation and its invoking thread. Do not retain it, submit it to another thread, or call it after the provider returns. Complete all work synchronously. Cache the resulting bytes, not the supplier or request. The provider must return non-null bytes that decode to the exact response body using the selected codec's content coding; it must not mutate the supplied or returned arrays. A null result or an exception is a response-processing failure, not a request for an uncompressed fallback.

      Parameters:
      codec - the codec to use
      compressedBodyProvider - the function that returns cached bytes or obtains them from Soklet's supplier
      Returns:
      a compression plan with a custom body provider
      Throws:
      IllegalArgumentException - if the codec's content coding is not a valid compression token
    • getCodec

      The selected codec, if this plan requests compression.
      Returns:
      the codec, or Optional.empty() for none()
    • getContentEncoding

      The validated lowercase content coding captured from the codec when this plan was created.

      Soklet uses this snapshot for content-coding negotiation and the Content-Encoding header; later changes to a codec's reported coding cannot change a plan's meaning.

      Returns:
      the content coding, or Optional.empty() for none()
    • getCompressedBodyProvider

      The custom compressed-body provider, if supplied.

      An empty value means either no compression was requested, or Soklet should obtain bytes directly from the selected codec. Provider execution belongs to the transport and obeys the lifetime contract of compress(ResponseCompressionCodec, Function).

      Returns:
      the custom provider, or Optional.empty() when absent