Package org.apache.juneau.http.header

Class IfMatch

java.lang.Object
org.apache.juneau.http.header.BasicHeader
org.apache.juneau.http.header.BasicEntityTagsHeader
org.apache.juneau.http.header.IfMatch
All Implemented Interfaces:
Serializable, Cloneable, Header, NameValuePair
@Header("If-Match") public class IfMatch extends BasicEntityTagsHeader
Represents a parsed If-Match HTTP request header.

Only perform the action if the client supplied entity matches the same entity on the server. This is mainly for methods like PUT to only update a resource if it has not been modified since the user last updated it.

Example

If-Match: "737060cd8c284d8af7ad3082f209582d"

RFC2616 Specification
The If-Match request-header field is used with a method to make it conditional. A client that has one or more entities previously obtained from the resource can verify that one of those entities is current by including a list of their associated entity tags in the If-Match header field. Entity tags are defined in section 3.11. The purpose of this feature is to allow efficient updates of cached information with a minimum amount of transaction overhead. It is also used, on updating requests, to prevent inadvertent modification of the wrong version of a resource. As a special case, the value "*" matches any current entity of the resource.

If-Match = "If-Match" ":" ( "*" | 1#entity-tag )

If any of the entity tags match the entity tag of the entity that would have been returned in the response to a similar GET request (without the If-Match header) on that resource, or if "*" is given and any current entity exists for that resource, then the server MAY perform the requested method as if the If-Match header field did not exist.

A server MUST use the strong comparison function (see section 13.3.3) to compare the entity tags in If-Match.

If none of the entity tags match, or if "*" is given and no current entity exists, the server MUST NOT perform the requested method, and MUST return a 412 (Precondition Failed) response. This behavior is most useful when the client wants to prevent an updating method, such as PUT, from modifying a resource that has changed since the client last retrieved it.

If the request would, without the If-Match header field, result in anything other than a 2xx or 412 status, then the If-Match header MUST be ignored.

The meaning of "If-Match: *" is that the method SHOULD be performed if the representation selected by the origin server (or by a cache, possibly using the Vary mechanism, see section 14.44) exists, and MUST NOT be performed if the representation does not exist.

A request intended to update a resource (e.g., a PUT) MAY include an If-Match header field to signal that the request method MUST NOT be applied if the entity corresponding to the If-Match value (a single entity tag) is no longer a representation of that resource. This allows the user to indicate that they do not wish the request to be successful if the resource has been changed without their knowledge.

Examples:

If-Match: "xyzzy" If-Match: "xyzzy", "r2d2xxxx", "c3piozzzz" If-Match: *

The result of a request having both an If-Match header field and either an If-None-Match or an If-Modified-Since header fields is undefined by this specification.

See Also:

  • Constructor Details

    • IfMatch

      public IfMatch(String value)
      Constructor.
      Parameters:
      value - The header value.
      Must be a comma-delimited list of entity validator values (e.g. "\"xyzzy\", \"r2d2xxxx\", \"c3piozzzz\"").
      Can be null.

    • IfMatch

      public IfMatch(EntityTags value)
      Constructor.
      Parameters:
      value - The header value.
      Can be null.

    • IfMatch

      public IfMatch(Supplier<EntityTags> value)
      Constructor with delayed value.

      Header value is re-evaluated on each call to BasicEntityTagsHeader.getValue().

      Parameters:
      value - The supplier of the header value.
      Can be null.

  • Method Details

    • of

      public static IfMatch of(String value)
      Static creator.
      Parameters:
      value - The header value.
      Must be a comma-delimited list of entity validator values (e.g. "\"xyzzy\", \"r2d2xxxx\", \"c3piozzzz\"").
      Can be null.
      Returns:
      A new header bean, or null if the value is null.

    • of

      public static IfMatch of(EntityTags value)
      Static creator.
      Parameters:
      value - The header value.
      Can be null.
      Returns:
      A new header bean, or null if the value is null.

    • of

      public static IfMatch of(Supplier<EntityTags> value)
      Static creator with delayed value.

      Header value is re-evaluated on each call to BasicEntityTagsHeader.getValue().

      Parameters:
      value - The supplier of the header value.
      Can be null.
      Returns:
      A new header bean, or null if the value is null.