Class ResponseCompressionPlan
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 Summary
Modifier and TypeMethodDescriptionstatic @NonNull ResponseCompressionPlanSelects a codec, letting Soklet invoke it lazily when the response needs compressed body bytes.static @NonNull ResponseCompressionPlancompress(@NonNull ResponseCompressionCodec codec, @NonNull Function<@NonNull Supplier<byte @NonNull []>, byte @NonNull []> compressedBodyProvider) Selects a codec and wraps its lazy body computation with application behavior, such as caching.getCodec()The selected codec, if this plan requests compression.The custom compressed-body provider, if supplied.The validated lowercase content coding captured from the codec when this plan was created.static @NonNull ResponseCompressionPlannone()Acquires the shared plan that declines response compression.
-
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
public static @NonNull ResponseCompressionPlan compress(@NonNull ResponseCompressionCodec codec, @NonNull Function<@NonNull Supplier<byte @NonNull []>, byte @NonNull []> compressedBodyProvider) 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 usecompressedBodyProvider- 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()fornone()
-
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-Encodingheader; later changes to a codec's reported coding cannot change a plan's meaning.- Returns:
- the content coding, or
Optional.empty()fornone()
-
getCompressedBodyProvider
public @NonNull Optional<@NonNull Function<@NonNull Supplier<byte @NonNull []>, byte @NonNull []>> 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
-