Interface EntityTags


public interface EntityTags
Provides services for validating "If-Match" and "If-None-Match" request headers. Also provides a facility for generating an "ETag" header automatically from a secure digest of a HttpServletResponse.
Author:
cdivilly
  • Field Details

  • Method Details

    • hasPrecondition

      boolean hasPrecondition(javax.servlet.http.HttpServletRequest request)
      Determine if the specified request is a conditional HTTP request. A request is conditional if it contains IF_MATCH for a PUT,POST,PATCH or DELETE method, and IF_NONE_MATCH for a GET or HEAD method
      Parameters:
      request - The HTTP request to check for presence of a pre-condition
      Returns:
      true if request has a precondition, false otherwise
    • hasPrecondition

      boolean hasPrecondition(javax.servlet.http.HttpServletRequest request, EntityTags.EntityTagType etagType)
      Determine if the specified request is a conditional HTTP request. A request is conditional if it contains IF_MATCH for a PUT,POST,PATCH or DELETE method, and IF_NONE_MATCH for a GET or HEAD method
      Parameters:
      request - The HTTP request to check for presence of a pre-condition
      etagType - The type of the EntityTag
      Returns:
      true if request has a precondition, false otherwise
    • validatePrecondition

      void validatePrecondition(javax.servlet.http.HttpServletRequest request, CharSequence currentEntityTag)
      Validate whether the pre-condition in the request matches the current "ETag" value of the requested resource.
      Parameters:
      request - The request to be validated
      currentEntityTag - The current "ETag" value of the requested resource
    • parse

      EntityTag parse(CharSequence text)
      Parses text into an EntityTag value. The value must be correctly formatted as a quoted ETag value.
      Parameters:
      text - The text value to parse
      Returns:
      EntityTag instance, or null if the supplied parameter is null or "*"
      Throws:
      IllegalArgumentException - if the value is not correctly formatted
    • entityTag

      EntityTag entityTag(String text)
      This method formats a textual value into a digested, strong EntityTag value. This method is equivalent to:
        String text = ...;
        EntityTags tags = ...;
        EntityTag tag = tags.builder().append(text).build();
       
      Parameters:
      text - The textual representation of the EntityTag
      Returns:
      Parsed EntityTag instance
    • entityTag

      EntityTag entityTag(javax.servlet.http.HttpServletRequest request, String headerName)
      Parses an EntityTag value from the specified header. If the header is "If-Match" or IF_NONE_MATCH and the value is * then a null value will be returned.
      Parameters:
      request - The request to examine
      headerName - The name of the HTTP Header
      Returns:
      The EntityTag value or null if the header is absent or has no value
    • builder

      Return a new instance of an EntityTag.Builder
      Returns:
      EntityTag.Builder instance
    • etag

      boolean etag(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, HasGetMethod servlet, EntityTags.EntityTagType etagType) throws javax.servlet.ServletException, IOException
      Adapt a HttpServletResponse to produce a strong "ETag" generated from a secure digest of the response headers and body. This method also performs any validation This provides a simple mechanism to produce a guaranteed correct "ETag", however the simplicity has some costs:
      • The CPU overhead of generating the secure digest
      • The memory overhead of buffering the entire response in order to produce the digest
      This method SHOULD NOT be used for large responses. Servlets that wish to use this method must implement the HasGetMethod interface and pass a reference to themselves as the final parameter.
      Parameters:
      request - The request being processed
      response - The response object provided by the servlet container
      servlet - The servlet which will produce the response
      etagType - The type of the EntityTag
      Returns:
      true if the servlet should proceed with processing the request, false otherwise
      Throws:
      javax.servlet.ServletException - if the HTTP request cannot be handled
      IOException - if an input or output error occurs while the request is being handled
      See Also:
    • etag

      boolean etag(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, HasGetMethod servlet) throws javax.servlet.ServletException, IOException
      Adapt a HttpServletResponse to produce a strong "ETag" generated from a secure digest of the response headers and body. This method also performs any validation This provides a simple mechanism to produce a guaranteed correct "ETag", however the simplicity has some costs:
      • The CPU overhead of generating the secure digest
      • The memory overhead of buffering the entire response in order to produce the digest
      This method SHOULD NOT be used for large responses. Servlets that wish to use this method must implement the HasGetMethod interface and pass a reference to themselves as the final parameter. All methods will be processed
      Parameters:
      request - The request being processed
      response - The response object provided by the servlet container
      servlet - The servlet which will produce the response
      Returns:
      true if the servlet should proceed with processing the request, false otherwise
      Throws:
      javax.servlet.ServletException - if the HTTP request cannot be handled
      IOException - if an input or output error occurs while the request is being handled
      See Also: