Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8267379

com/sun/net/httpserver/Filter improve API documentation of static methods

    XMLWordPrintable

    Details

    • Type: CSR
    • Status: Closed
    • Priority: P4
    • Resolution: Approved
    • Fix Version/s: 17
    • Component/s: core-libs
    • Labels:
      None
    • Subcomponent:
    • Compatibility Kind:
      behavioral
    • Compatibility Risk:
      minimal
    • Compatibility Risk Description:
      API doc change only. This is updating the documentation of a new API in JDK 17.
    • Interface Kind:
      Java API
    • Scope:
      JDK

      Description

      Summary

      Filter::beforeHandler and Filter::afterHandler: Clarify the exception handling for the case in which the filter operation throws an unchecked exception.

      Filter::afterHandler: Clarify the timely relation between the execution of the filter operation and the sending of the response.

      Problem

      The filter operation Consumer that is passed to the factory methods can throw an unchecked exception but the documentation does not describe the behaviour in this case.

      In the case of Filter::afterHandler, the filter operation is commonly executed after the response has been sent. This is not spelled out in the documentation.

      Solution

      Add a sentence to the documentation of both factory methods that clarifies the exception handling, as well as a sentence on the order of the filter operation and the sending of the response to Filter::afterHandler.

      Specification

      src/jdk.httpserver/share/classes/com/sun/net/httpserver/Filter.java

            * <p>The {@link Consumer operation} is the effective implementation of the
            * filter. It is executed for each {@code HttpExchange} before invoking
            * either the next filter in the chain or the exchange handler (if this is
      -     * the final filter in the chain).
      +     * the final filter in the chain). Exceptions thrown by the
      +     * {@code operation} are not handled by the filter.

      ...

            * <p>The {@link Consumer operation} is the effective implementation of the
            * filter. It is executed for each {@code HttpExchange} after invoking
            * either the next filter in the chain or the exchange handler (if this
      -     * filter is the final filter in the chain).
      +     * filter is the final filter in the chain). Exceptions thrown by the
      +     * {@code operation} are not handled by the filter.
            *
            * @apiNote
            * An afterHandler filter is typically used to examine the exchange state
            * rather than modifying it. The filter {@code operation} is executed after
            * {@link Filter.Chain#doFilter(HttpExchange)} is invoked, this means any
            * subsequent filters in the chain and the exchange handler have been
            * executed. The filter {@code operation} is not expected to handle the
            * exchange or {@linkplain HttpExchange#sendResponseHeaders(int, long) send the response headers}.
            * Doing so is likely to fail, since the exchange has commonly been handled
      -     * before the operation is invoked.
      +     * before the {@code operation} is invoked. More specifically, the response
      +     * may be sent before the filter {@code operation} is executed.

        Attachments

          Issue Links

            Activity

              People

              Assignee:
              jboes Julia Boes (Inactive)
              Reporter:
              jboes Julia Boes (Inactive)
              Reviewed By:
              Daniel Fuchs
              Votes:
              0 Vote for this issue
              Watchers:
              1 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved: