Package oracle.dbtools.plugin.api.servlet

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 Summary

      Fields 
      Modifier and Type Field Description
      static java.lang.String ETAG  
      static java.lang.String IF_MATCH  
      static java.lang.String IF_NONE_MATCH  

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      EntityTag.Builder builder()
      Return a new instance of an EntityTag.Builder
      EntityTag entityTag​(java.lang.String text)
      This method formats a textual value into a digested, strong EntityTag value.
      EntityTag entityTag​(javax.servlet.http.HttpServletRequest request, java.lang.String headerName)
      Parses an EntityTag value from the specified header.
      boolean etag​(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, HasGetMethod servlet)
      Adapt a HttpServletResponse to produce a strong "ETag" generated from a secure digest of the response headers and body.
      boolean etag​(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, HasGetMethod servlet, EntityTags.EntityTagType etagType)
      Adapt a HttpServletResponse to produce a strong "ETag" generated from a secure digest of the response headers and body.
      boolean hasPrecondition​(javax.servlet.http.HttpServletRequest request)
      Determine if the specified request is a conditional HTTP request.
      boolean hasPrecondition​(javax.servlet.http.HttpServletRequest request, EntityTags.EntityTagType etagType)
      Determine if the specified request is a conditional HTTP request.
      EntityTag parse​(java.lang.CharSequence text)
      Parses text into an EntityTag value.
      void validatePrecondition​(javax.servlet.http.HttpServletRequest request, java.lang.CharSequence currentEntityTag)
      Validate whether the pre-condition in the request matches the current "ETag" value of the requested resource.

    • Method Detail

      • 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,
                          java.lang.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​(java.lang.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:
        java.lang.IllegalArgumentException - if the value is not correctly formatted

      • entityTag

        EntityTag entityTag​(java.lang.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,
                    java.lang.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

      • etag

        boolean etag​(javax.servlet.http.HttpServletRequest request,
             javax.servlet.http.HttpServletResponse response,
             HasGetMethod servlet,
             EntityTags.EntityTagType etagType)
      throws javax.servlet.ServletException,
             java.io.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
        java.io.IOException - if an input or output error occurs while the request is being handled
        See Also:
        HasGetMethod

      • etag

        boolean etag​(javax.servlet.http.HttpServletRequest request,
             javax.servlet.http.HttpServletResponse response,
             HasGetMethod servlet)
      throws javax.servlet.ServletException,
             java.io.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
        java.io.IOException - if an input or output error occurs while the request is being handled
        See Also:
        HasGetMethod