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

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface | Description
    --- | --- | ---
    `static class` | `EntityTags.EntityTagType` |

  - ### 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.

- - ### Field Detail

    - #### IF_MATCH

          static final java.lang.String IF_MATCH

      See Also:
        RFC 2616 Section 14.24, Constant Field Values

    - #### IF_NONE_MATCH

          static final java.lang.String IF_NONE_MATCH

      See Also:
        RFC 2616 Section 14.26, Constant Field Values

    - #### ETAG

          static final java.lang.String ETAG

      See Also:
        RFC 2616 Section 14.19, Constant Field Values

  - ### 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

    - #### builder

          EntityTag.Builder 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,
                       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`