Fix #210 - Add an API for client-side TLS configuration

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

@@ -22,6 +22,8 @@
 import java.util.List;
 import java.util.Map;
 
+import javax.net.ssl.SSLContext;
+
 /**
  * The ClientEndpointConfig is a special kind of endpoint configuration object that contains web socket configuration
  * information specific only to client endpoints. Developers deploying programmatic client endpoints can create
@@ -53,6 +55,18 @@ public interface ClientEndpointConfig extends EndpointConfig {
      */
     List<Extension> getExtensions();
 
+    /**
+     * Return the SSLContext to be used to establish a WebSocket (wss) connection to the server. The SSLContext will
+     * have initialised. For insecure WebSocket (ws) connections, this will be {@code null}. If there is an existing
+     * connection to the server that uses the same SSLContext and that connection supports multiplexing WebSocket
+     * connections then the container may choose to re-use that connection rather than creating a new one. Containers
+     * may provide container specific configuration to control this behaviour.
+     *
+     * @return the SSLContext to use to establish a secure connection to the server or {@code null} if an insecure
+     *         connection should be established
+     */
+    SSLContext getSSLContext();
+
     /**
      * Return the custom configurator for this configuration. If the developer did not provide one, the platform default
      * configurator is returned.
@@ -120,6 +134,7 @@ public final class Builder {
         private List<Extension> extensions = Collections.emptyList();
         private List<Class<? extends Encoder>> encoders = Collections.emptyList();
         private List<Class<? extends Decoder>> decoders = Collections.emptyList();
+        private SSLContext sslContext = null;
         private ClientEndpointConfig.Configurator clientEndpointConfigurator = new ClientEndpointConfig.Configurator() {
 
         };
@@ -145,7 +160,7 @@ public static ClientEndpointConfig.Builder create() {
          */
         public ClientEndpointConfig build() {
             return new DefaultClientEndpointConfig(this.preferredSubprotocols, this.extensions, this.encoders,
-                    this.decoders, this.clientEndpointConfigurator);
+                    this.decoders, this.sslContext, this.clientEndpointConfigurator);
         }
 
         /**
@@ -206,6 +221,19 @@ public ClientEndpointConfig.Builder decoders(List<Class<? extends Decoder>> deco
             return this;
         }
 
+        /**
+         * Assign the SSLContext to be used when connection to the WebSocket server. If there is an existing connection
+         * to the server that uses the same SSLContext and that connection supports multiplexing WebSocket connections
+         * then the container may choose to re-use that connection rather than creating a new one. Containers may
+         * provide container specific configuration to control this behaviour.
+         *
+         * @param sslContext The SSLContext which must be initialised for secure WebSocket (wss) connections or
+         *                  {@code null} for insecure WebSocket (ws) connections.
+         * @return this builder instance
+         */
+        public ClientEndpointConfig.Builder sslContext(SSLContext sslContext) {
+            this.sslContext = sslContext;
+            return this;
+        }
     }
-
 }

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

@@ -22,6 +22,8 @@
 import java.util.List;
 import java.util.Map;
 
+import javax.net.ssl.SSLContext;
+
 /**
  * The DefaultClientEndpointConfig is a concrete implementation of a client configuration.
  *
@@ -32,16 +34,18 @@ final class DefaultClientEndpointConfig implements ClientEndpointConfig {
     private List<Extension> extensions;
     private List<Class<? extends Encoder>> encoders;
     private List<Class<? extends Decoder>> decoders;
+    private SSLContext sslContext;
     private Map<String, Object> userProperties = new HashMap<>();
     private ClientEndpointConfig.Configurator clientEndpointConfigurator;
 
     DefaultClientEndpointConfig(List<String> preferredSubprotocols, List<Extension> extensions,
             List<Class<? extends Encoder>> encoders, List<Class<? extends Decoder>> decoders,
-            ClientEndpointConfig.Configurator clientEndpointConfigurator) {
+            SSLContext sslContext, ClientEndpointConfig.Configurator clientEndpointConfigurator) {
         this.preferredSubprotocols = Collections.unmodifiableList(preferredSubprotocols);
         this.extensions = Collections.unmodifiableList(extensions);
         this.encoders = Collections.unmodifiableList(encoders);
         this.decoders = Collections.unmodifiableList(decoders);
+        this.sslContext = sslContext;
         this.clientEndpointConfigurator = clientEndpointConfigurator;
     }
 
@@ -87,6 +91,17 @@ public List<Class<? extends Decoder>> getDecoders() {
         return this.decoders;
     }
 
+    /**
+     * SSLContext to use to secure WebSocket (wss) connections or {@code null} for insecure Websocket (ws) connections.
+     * If there is an existing connection to the server that uses the same SSLContext and that connection supports
+     * multiplexing WebSocket connections then the container may choose to re-use that connection rather than creating a
+     * new one. Containers may provide container specific configuration to control this behaviour.
+     */
+    @Override
+    public SSLContext getSSLContext() {
+        return this.sslContext;
+    }
+
     /**
      * Editable map of user properties.
      */

spec/src/main/asciidoc/WebSocket.adoc

@@ -668,6 +668,17 @@ extensions to send, in order of preference, the extensions, including
 parameters, that it would like to use in the opening handshake it
 formulates [WSC-3.2.2-1].
 
+[[sslcontext]]
+==== SSLContext
+
+The default client configuration uses the developer provided `SSLContext` to
+establish a secure WebSocket (wss) connection or an insecure WebSocket (ws)
+connection if the provided `SSLContext` is `null`. If there is an existing
+connection to the server that uses the same SSLContext and that connection
+supports multiplexing WebSocket connections then the container may choose to
+re-use that connection rather than creating a new one. Containers may provide
+container specific configuration to control this behaviour.
+
 [[client-configuration-modification]]
 ==== Client Configuration Modification
 
@@ -1501,6 +1512,9 @@ subsequent changes to the MessageHandlers configured for the Session.
 * https://github.com/eclipse-ee4j/websocket-api/issues/207[Issue 207]
 Add a getter for the default platform configurator.
 
+* https://github.com/eclipse-ee4j/websocket-api/issues/210[Issue 210]
+Provide an API for client-side TLS configuration.
+
 * https://github.com/eclipse-ee4j/websocket-api/issues/211[Issue 211]
 Remove the restriction that, in a Jakarta web container environment, endpoints
 can only registered during the deployment of the web application. Also add a new