Class ConditionalRequests
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.
evaluate(Request, EntityTag, Instant) exposes the same decision as immutable data for application-owned
responses; evaluateWithoutRepresentation(Request) supports conditional creation against an absent resource.
Perform normal authorization, routing, and resource checks first. These helpers do not override an otherwise
applicable failure such as 401, 403, 404 on a non-creating endpoint, or 405.
A typed RequestBody is unmarshaled before its resource method is invoked, so in-method
evaluation does not promise header-before-body-validation ordering.
Evaluation describes a snapshot, not an atomic write. After a known no-effect storage race, reload fresh state and
re-evaluate the client's conditions, or enforce an explicitly equivalent predicate atomically. A failed internal
version compare-and-set alone does not justify 412. Under snapshot isolation an application may need a new
transaction; uncertain commit outcomes require application recovery rather than blind retries.
OPTIONS ignores conditional values. 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 to applicable methods. Malformed If-None-Match on GET and HEAD is treated as a
cache miss and still suppresses If-Modified-Since. The same policy applies to parser-budget exhaustion.
Applications choose required-precondition policies such as 428; this API neither imposes them nor treats a
nonempty satisfied set as adequate lost-update protection. Strong If-Match comparison is never weakened for
transport compression: a compressed response's weak ETag cannot satisfy it.
Applications constructing 304 responses own the selected representation's required cache and validator
metadata. RFC 9110 permits an application-established already-applied successful response for false
If-Match/If-Unmodified-Since, not a failed If-None-Match; the evaluator does not infer it.
- Author:
- Mark Allen
-
Method Summary
Modifier and TypeMethodDescriptionstatic @NonNull ConditionalRequestResultEvaluates conditional fields against an existing selected representation, without constructing a response.static @NonNull ConditionalRequestResultevaluateWithoutRepresentation(@NonNull Request request) Evaluates conditional fields when no current representation exists and the request can otherwise proceed, such as a creating PUT.responseFor(@NonNull Request request, @Nullable EntityTag entityTag, @Nullable Instant lastModified) Evaluates conditional request headers against an existing representation and builds the default response.responseFor(@NonNull Request request, @Nullable EntityTag entityTag, @Nullable Instant lastModified, @Nullable Map<@NonNull String, @NonNull List<@NonNull String>> extraHeaders) Evaluates conditional request headers against an existing representation and builds the default response.validatorHeaders(@Nullable EntityTag entityTag, @Nullable Instant lastModified) Builds validator headers for the supplied representation validators.validatorHeaders(@Nullable EntityTag entityTag, @Nullable Instant lastModified, @Nullable Map<@NonNull String, @NonNull List<@NonNull String>> extraHeaders) Builds validator headers plus endpoint-specific metadata headers.
-
Method Details
-
evaluate
public static @NonNull ConditionalRequestResult evaluate(@NonNull Request request, @Nullable EntityTag entityTag, @Nullable Instant lastModified) Evaluates conditional fields against an existing selected representation, without constructing a response.Either validator may be unavailable. In particular,
null/nullmeans an existing representation without validators, never a missing representation. UseevaluateWithoutRepresentation(Request)for absence. A wildcardIf-Matchsucceeds for an existing representation even with no current ETag; a wildcardIf-None-Matchdoes not. With no ETag, valid tag lists cannot match. With a weak current tag, no validIf-Matchlist can strongly match; weak comparison still applies toIf-None-Match.Repeated entity-tag fields are combined in occurrence order. Valid empty lists match nothing. Tag fields suppress their corresponding date fields even when empty or malformed. Invalid/unavailable dates are ignored, and valid dates are compared at whole-second precision. The first decisive precondition is returned; ignored or later fields are not inspected for diagnostics.
OPTIONSreturns an emptyConditionalRequestResult.Proceedwithout parsing conditional values.Entity-tag parsing first performs quote-aware bounded splitting, counting empty elements but not quoted commas. The budget is currently 256 elements. A reached limit immediately reports
ConditionalRequestResult.PreconditionFailed.Reason.ENTITY_TAG_LIST_LIMIT_EXCEEDED; otherwise an unclosed quote reportsConditionalRequestResult.PreconditionFailed.Reason.MALFORMED, then invalid individual tags do the same. No blanket malformed-versus-limit priority applies when input has both problems.- Parameters:
request- the request whose conditional fields should be evaluatedentityTag- the existing representation's entity tag, ornullif unavailablelastModified- its last-modified instant, ornullif unavailable- Returns:
- immutable conditional decision for the supplied snapshot
-
evaluateWithoutRepresentation
public static @NonNull ConditionalRequestResult evaluateWithoutRepresentation(@NonNull Request request) Evaluates conditional fields when no current representation exists and the request can otherwise proceed, such as a creating PUT. Do not use null validators withevaluate(Request, EntityTag, Instant)to mean absence.On applicable methods, any valid
If-Match, including a wildcard or empty list, fails. Any validIf-None-Matchevaluates true, including a wildcard or empty list. Date fields are ignored because no modification time exists. This entry point cannot returnConditionalRequestResult.NotModified; itsConditionalRequestResult.Proceedhas either an empty satisfied set or justIF_NONE_MATCH. Existing malformed/over-limit policies still apply, andOPTIONSalways proceeds with an empty set.Non-creating endpoints should ordinarily return their normal missing-resource response before evaluation. Conditional creation still requires an atomic insert-if-absent and fresh evaluation after a known target-identity conflict; arbitrary database errors or uncertain commits are not blind-retry signals.
- Parameters:
request- the request to evaluate against no current representation- Returns:
- immutable decision; never
ConditionalRequestResult.NotModified
-
responseFor
public static @NonNull Optional<@NonNull Response> responseFor(@NonNull Request request, @Nullable EntityTag entityTag, @Nullable Instant lastModified) Evaluates conditional request headers against an existing representation and builds the default response.Null validators mean unavailable validators, never a missing representation.
OPTIONSproceeds without parsing conditional values. Seeevaluate(Request, EntityTag, Instant)to construct application-owned responses, andevaluateWithoutRepresentation(Request)for a missing representation.- Parameters:
request- the request whose conditional headers should be evaluatedentityTag- the current representation's entity tag, ornullif unavailablelastModified- the current representation's last-modified instant, ornullif unavailable- Returns:
- a short-circuit response, or
Optional.empty()when the application should continue normally
-
responseFor
public static @NonNull Optional<@NonNull Response> responseFor(@NonNull Request request, @Nullable EntityTag entityTag, @Nullable Instant lastModified, @Nullable Map<@NonNull String, @NonNull List<@NonNull String>> extraHeaders) Evaluates conditional request headers against an existing representation and builds the default response.Null validators mean unavailable validators, never a missing representation.
OPTIONSproceeds without parsing conditional values. All failure reasons map to a bodyless412; seeevaluate(Request, EntityTag, Instant)for a fine-grained decision.extraHeadersare included on short-circuit304and412responses. They are intended for response metadata such asCache-ControlorVary; validator and body-framing headers are rejected because they are controlled by this helper.- Parameters:
request- the request whose conditional headers should be evaluatedentityTag- the current representation's entity tag, ornullif unavailablelastModified- the current representation's last-modified instant, ornullif unavailableextraHeaders- 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 List<@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, ornullif unavailablelastModified- the current representation's last-modified instant, ornullif unavailable- Returns:
- immutable
ETagandLast-Modifiedheaders for the supplied validators
-
validatorHeaders
public static @NonNull Map<@NonNull String, @NonNull List<@NonNull String>> validatorHeaders(@Nullable EntityTag entityTag, @Nullable Instant lastModified, @Nullable Map<@NonNull String, @NonNull List<@NonNull String>> extraHeaders) Builds validator headers plus endpoint-specific metadata headers.extraHeadersare intended for response metadata such asCache-ControlorVary; validator and body-framing headers are rejected because they are controlled by this helper.- Parameters:
entityTag- the current representation's entity tag, ornullif unavailablelastModified- the current representation's last-modified instant, ornullif unavailableextraHeaders- endpoint-specific metadata headers to include with the validators- Returns:
- immutable combined headers
-