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. 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 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/null means an existing representation without validators, never a missing representation. Use evaluateWithoutRepresentation(Request) for absence. A wildcard If-Match succeeds for an existing representation even with no current ETag; a wildcard If-None-Match does not. With no ETag, valid tag lists cannot match. With a weak current tag, no valid If-Match list can strongly match; weak comparison still applies to If-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. OPTIONS returns an empty ConditionalRequestResult.Proceed without 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 reports ConditionalRequestResult.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 evaluated
      entityTag - the existing representation's entity tag, or null if unavailable
      lastModified - its last-modified instant, or null if unavailable
      Returns:
      immutable conditional decision for the supplied snapshot
    • evaluateWithoutRepresentation

      Evaluates conditional fields when no current representation exists and the request can otherwise proceed, such as a creating PUT. Do not use null validators with evaluate(Request, EntityTag, Instant) to mean absence.

      On applicable methods, any valid If-Match, including a wildcard or empty list, fails. Any valid If-None-Match evaluates true, including a wildcard or empty list. Date fields are ignored because no modification time exists. This entry point cannot return ConditionalRequestResult.NotModified; its ConditionalRequestResult.Proceed has either an empty satisfied set or just IF_NONE_MATCH. Existing malformed/over-limit policies still apply, and OPTIONS always 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. OPTIONS proceeds without parsing conditional values. See evaluate(Request, EntityTag, Instant) to construct application-owned responses, and evaluateWithoutRepresentation(Request) for a missing representation.

      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

      Evaluates conditional request headers against an existing representation and builds the default response.

      Null validators mean unavailable validators, never a missing representation. OPTIONS proceeds without parsing conditional values. All failure reasons map to a bodyless 412; see evaluate(Request, EntityTag, Instant) for a fine-grained decision.

      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

      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

      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