Summary

The javadoc of com.sun.net.httpserver.HttpExchange.getAttribute() and com.sun.net.httpserver.HttpExchange.setAttribute() methods will be updated to relax the specification and clarify the current implementation.

Problem

In https://bugs.openjdk.org/browse/JDK-8345243 we updated the javadoc of these 2 methods to have their specification match the current implementation. However, the HttpExchange.getAttribute() and the HttpExchange.setAttribute() methods are abstract and there are subclasses of HttpExchange external to the JDK code which implement these methods differently than the JDK built-in implementation of these methods. Although the update in JDK-8345243, made the API specification of those methods match the current implementation, that normative text can potentially contradict with other existing external implementations.

Solution

The javadoc of these 2 methods will be updated to relax the normative text and introduce a @implSpec to explain the JDK built-in implementation of these methods.

As a long term solution, in a subsequent release, we are considering deprecation of these 2 methods and the introduction of newer methods on the HttpExchange to set attributes that are scoped only to a particular exchange, unlike the current implementation where these attributes are shared by exchanges belonging to the same HttpContext. Additional details of that change will be made available through a separate enhancement, after due consideration.

Specification

diff --git a/src/jdk.httpserver/share/classes/com/sun/net/httpserver/HttpExchange.java b/src/jdk.httpserver/share/classes/com/sun/net/httpserver/HttpExchange.java

     /**
-     * Returns the attribute's value from this exchange's
-     * {@linkplain HttpContext#getAttributes() context attributes}.
+     * Returns the value for the given attribute {@code name}.
+     *
+     * @implSpec The JDK built-in implementation of this method returns
+     * the attribute value from this exchange's
+     * {@linkplain HttpContext#getAttributes() context attributes}. The attribute
+     * may have been {@linkplain HttpExchange#setAttribute(String, Object) set}
+     * either through this {@code HttpExchange} instance or some
+     * other {@code HttpExchange} belonging to the same {@link HttpContext}.
      *
      * @apiNote {@link Filter} modules may store arbitrary objects as attributes through
      * {@code HttpExchange} instances as an out-of-band communication mechanism. Other filters
     ...
     public abstract Object getAttribute(String name);

     /**
-     * Sets an attribute with the given {@code name} and {@code value} in this exchange's
-     * {@linkplain HttpContext#getAttributes() context attributes}.
+     * Sets an attribute with the given {@code name} and {@code value}.
+     *
+     * @implSpec The JDK built-in implementation of this method sets
+     * the attribute in this exchange's
+     * {@linkplain HttpContext#getAttributes() context attributes}. The attribute
+     * will be {@linkplain HttpExchange#getAttribute(String) available} to all
+     * other {@code HttpExchange}s that belong to the same {@link HttpContext}.
      *
      * @apiNote {@link Filter} modules may store arbitrary objects as attributes through
      * {@code HttpExchange} instances as an out-of-band communication mechanism. Other filters
      ...
      public abstract void setAttribute(String name, Object value);