Summary

The API documentation of com.sun.net.httpserver.HttpExchange.setAttribute() and com.sun.net.httpserver.HttpExchange.getAttribute() methods will be clarified to match their current implementation and intended use.

Problem

The HttpExchange, of the jdk.httpserver, represents a request and a response that is generated in one exchange. This class has the following two methods:

public abstract void setAttribute(String name, Object value);
public abstract Object getAttribute(String name);

The default implementation of the com.sun.net.httpserver.HttpServer in the JDK, sets and retrieves these attributes from the com.sun.net.httpserver.HttpContext. A HttpContext represents a mapping between the root URI path of an application to a com.sun.net.httpserver.HttpHandler which is invoked to handle the request. A single instance of HttpContext is used for all the HttpExchange instances that are targeted for the same root URI path. Thus, the attributes that are set through the HttpExchange.setAttribute() are shared by all the HttpExchange instances of that HttpContext. This detail is not specified in the setAttribute() and getAttribute() methods of the HttpExchange which makes it look like these attributes are per exchange attribtues.

Solution

The javadoc of these two methods will be updated to formally specify the current implementation.

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
index ea2845f56f56c..ebcbaa3a773db 100644
--- a/src/jdk.httpserver/share/classes/com/sun/net/httpserver/HttpExchange.java
+++ b/src/jdk.httpserver/share/classes/com/sun/net/httpserver/HttpExchange.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2021, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2024, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -233,22 +233,29 @@ protected HttpExchange() {
     public abstract String getProtocol();

     /**
-     * {@link Filter} modules may store arbitrary objects with {@code HttpExchange}
-     * instances as an out-of-band communication mechanism. Other filters
+     * Returns the attribute's value from this exchange's
+     * {@linkplain HttpContext#getAttributes() context attributes}.
+     *
+     * @apiNote {@link Filter} modules may store arbitrary objects as attributes through
+     * {@code HttpExchange} instances as an out-of-band communication mechanism. Other filters
      * or the exchange handler may then access these objects.
      *
      * <p> Each {@code Filter} class will document the attributes which they make
      * available.
      *
      * @param name the name of the attribute to retrieve
-     * @return the attribute object, or {@code null} if it does not exist
+     * @return the attribute's value or {@code null} if either the attribute isn't set
+     *         or the attribute value is {@code null}
      * @throws NullPointerException if name is {@code null}
      */
     public abstract Object getAttribute(String name);

     /**
-     * {@link Filter} modules may store arbitrary objects with {@code HttpExchange}
-     * instances as an out-of-band communication mechanism. Other filters
+     * Sets an attribute with the given {@code name} and {@code value} in this exchange's
+     * {@linkplain HttpContext#getAttributes() context attributes}.
+     *
+     * @apiNote {@link Filter} modules may store arbitrary objects as attributes through
+     * {@code HttpExchange} instances as an out-of-band communication mechanism. Other filters
      * or the exchange handler may then access these objects.
      *
      * <p> Each {@code Filter} class will document the attributes which they make
      * available.
      *
      * @param name  the name to associate with the attribute value
      * @param value the object to store as the attribute value. {@code null}
      *              value is permitted.
      * @throws NullPointerException if name is {@code null}
      */
     public abstract void setAttribute(String name, Object value);