Class ConditionalRequests

java.lang.Object

com.soklet.ConditionalRequests

@ThreadSafe
public final class ConditionalRequests
extends Object

Utility methods for evaluating HTTP conditional requests against a selected dynamic representation.

This helper supports cache validation and optimistic concurrency for application responses without forcing resource methods into MarshaledResponse. Applications still own representation validators: choose the current EntityTag, Last-Modified instant, cache headers, and normal success response.

When a request precondition requires an immediate response, responseFor(Request, EntityTag, Instant) returns a bodyless Response with status 304 Not Modified or 412 Precondition Failed. Otherwise it returns Optional.empty() and the application should build its normal response.

Malformed entity-tag preconditions fail closed when they protect writes: malformed If-Match returns 412 Precondition Failed, and malformed If-None-Match does the same for non-GET/HEAD requests. Malformed If-None-Match on GET and HEAD is treated as a cache miss.

Author:

Mark Allen

Method Summary

Modifier and Type	Method	Description
static @NonNull Optional<Response>	responseFor(@NonNull Request request, @Nullable EntityTag entityTag, @Nullable Instant lastModified)	Evaluates conditional request headers against the supplied validators.
static @NonNull Optional<Response>	responseFor(@NonNull Request request, @Nullable EntityTag entityTag, @Nullable Instant lastModified, @Nullable Map<@NonNull String, @NonNull Set<@NonNull String>> extraHeaders)	Evaluates conditional request headers against the supplied validators.
static @NonNull Map<@NonNull String, @NonNull Set<@NonNull String>>	validatorHeaders(@Nullable EntityTag entityTag, @Nullable Instant lastModified)	Builds validator headers for the supplied representation validators.
static @NonNull Map<@NonNull String, @NonNull Set<@NonNull String>>	validatorHeaders(@Nullable EntityTag entityTag, @Nullable Instant lastModified, @Nullable Map<@NonNull String, @NonNull Set<@NonNull String>> extraHeaders)	Builds validator headers plus endpoint-specific metadata headers.

Methods inherited from class Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

responseFor

public static @NonNull Optional<Response> responseFor(@NonNull Request request,
 @Nullable EntityTag entityTag,
 @Nullable Instant lastModified)

Evaluates conditional request headers against the supplied validators.

Parameters:

request - the request whose conditional headers should be evaluated

entityTag - the current representation's entity tag, or null if unavailable

lastModified - the current representation's last-modified instant, or null if unavailable

Returns:

a short-circuit response, or Optional.empty() when the application should continue normally

responseFor

public static @NonNull Optional<Response> responseFor(@NonNull Request request,
 @Nullable EntityTag entityTag,
 @Nullable Instant lastModified,
 @Nullable Map<@NonNull String, @NonNull Set<@NonNull String>> extraHeaders)

Evaluates conditional request headers against the supplied validators.

extraHeaders are included on short-circuit 304 and 412 responses. They are intended for response metadata such as Cache-Control or Vary; validator and body-framing headers are rejected because they are controlled by this helper.

Parameters:

request - the request whose conditional headers should be evaluated

entityTag - the current representation's entity tag, or null if unavailable

lastModified - the current representation's last-modified instant, or null if unavailable

extraHeaders - endpoint-specific metadata headers to include on short-circuit responses

Returns:

a short-circuit response, or Optional.empty() when the application should continue normally

validatorHeaders

public static @NonNull Map<@NonNull String, @NonNull Set<@NonNull String>> validatorHeaders(@Nullable EntityTag entityTag,
 @Nullable Instant lastModified)

Builds validator headers for the supplied representation validators.

Parameters:

entityTag - the current representation's entity tag, or null if unavailable

lastModified - the current representation's last-modified instant, or null if unavailable

Returns:

immutable ETag and Last-Modified headers for the supplied validators

validatorHeaders

public static @NonNull Map<@NonNull String, @NonNull Set<@NonNull String>> validatorHeaders(@Nullable EntityTag entityTag,
 @Nullable Instant lastModified,
 @Nullable Map<@NonNull String, @NonNull Set<@NonNull String>> extraHeaders)

Builds validator headers plus endpoint-specific metadata headers.

extraHeaders are intended for response metadata such as Cache-Control or Vary; validator and body-framing headers are rejected because they are controlled by this helper.

Parameters:

entityTag - the current representation's entity tag, or null if unavailable

lastModified - the current representation's last-modified instant, or null if unavailable

extraHeaders - endpoint-specific metadata headers to include with the validators

Returns:

immutable combined headers