Fix jakartaee#235 - passing user properties

api/client/src/main/java/jakarta/websocket/Session.java

@@ -25,6 +25,8 @@
 import java.util.Map;
 import java.util.Set;
 
+import jakarta.websocket.server.ServerEndpointConfig;
+
 /**
  * A Web Socket session represents a conversation between two web socket endpoints. As soon as the websocket handshake
  * completes successfully, the web socket implementation provides the endpoint an open websocket session. The endpoint
@@ -307,6 +309,16 @@ public interface Session extends Closeable {
      * using this Map may no longer be kept by the container. Web socket applications running on distributed
      * implementations of the web container should make any application specific objects stored here
      * java.io.Serializable, or the object may not be recreated after a failover.
+     * <p>
+     * For server sessions, the initial contents of this Map must be a shallow copy of the user properties map returned
+     * from {@link ServerEndpointConfig#getUserProperties()} at the point the
+     * {@link jakarta.websocket.server.ServerEndpointConfig.Configurator#modifyHandshake(ServerEndpointConfig,
+     * jakarta.websocket.server.HandshakeRequest, HandshakeResponse)} method exits.
+     * <p>
+     * For client sessions, the initial contents of this Map must be a shallow copy of the user properties map returned
+     * from {@link ClientEndpointConfig#getUserProperties()} for the {@link ClientEndpointConfig} passed to
+     * {@link WebSocketContainer#connectToServer(Class, ClientEndpointConfig, URI)} or
+     * {@link WebSocketContainer#connectToServer(Endpoint, ClientEndpointConfig, URI)}.
      *
      * @return an editable Map of application data.
      */

api/server/src/main/java/jakarta/websocket/server/ServerEndpointConfig.java

@@ -171,6 +171,11 @@ public boolean checkOrigin(String originHeaderValue) {
          * <p>
          * If the developer does not override this method, no further modification of the request and response are made
          * by the implementation.
+         * <p>
+         * The user properties made available via {@link ServerEndpointConfig#getUserProperties()} must be a per
+         * WebSocket connection (i.e. per {@link jakarta.websocket.Session}) copy of the user properties. This copy,
+         * including any modifications made to the user properties during the execution of this method must be used to
+         * populate the initial contents of {@link jakarta.websocket.Session#getUserProperties()}.
          *
          * @param sec      the configuration object involved in the handshake
          * @param request  the opening handshake request.

spec/src/main/asciidoc/WebSocket.adoc

@@ -204,6 +204,12 @@ of a failover. Implementations are required to preserve developer data
 objects inserted into the WebSocket session if the data is marked
 *java.io.Serializable* [WSC 2.1.2-4].
 
+The user properties provided by the *Session* object are initially
+populated from the per *Session* shallow copy of the user properties
+provided by **EndpointConfig.getUserProperties()** that was passed to the
+*modifyHandshake()* method on the **ServerEndpointConfig.Configurator**
+including any modifications made during the execution of that method.
+
 [[receiving-messages]]
 ==== Receiving Messages
 
@@ -606,6 +612,13 @@ this, they may implement the *modifyHandshake()* method on the
 **ServerEndpointConfig.Configurator**, wherein they have full access to
 the *HandshakeRequest* and *HandshakeResponse* of the handshake.
 
+The user properties exposed during the *modifyHandshake()* method must
+be a per WebSocket connection (i.e. per *Session*) shallow copy of the
+user properties provided by **EndpointConfig.getUserProperties()**. When
+the *Session* object is created these user properties, including any
+modifications made during *modifyHandshake()*, must be used as the initial
+user properties for the *Session*.
+
 [[custom-state-or-processing-across-server-endpoint-instances]]
 ==== Custom State or Processing Across Server Endpoint Instances