Add new, standard method for direct upgrade to WebSocket

This will be part of the API from WebSocket 2.1 onwards
apache · Oct 7, 2021 · a182c5f · a182c5f
1 parent 151b024
commit a182c5f
Show file tree

Hide file tree

Showing 2 changed files with 53 additions and 0 deletions.
diff --git a/java/org/apache/tomcat/websocket/server/WsServerContainer.java b/java/org/apache/tomcat/websocket/server/WsServerContainer.java
@@ -313,7 +313,12 @@ boolean areEndpointsRegistered() {
      * @throws ServletException If a configuration error prevents the upgrade
      *         from taking place
      * @throws IOException If an I/O error occurs during the upgrade process
+     *
+     * @deprecated This method will be removed in Apache Tomcat 10.1 onwards. It
+     *             has been replaced by {@link #upgradeHttpToWebSocket(Object,
+     *             Object, ServerEndpointConfig, Map)}
      */
+    @Deprecated
     public void doUpgrade(HttpServletRequest request,
             HttpServletResponse response, ServerEndpointConfig sec,
             Map<String,String> pathParams)
@@ -322,6 +327,45 @@ public void doUpgrade(HttpServletRequest request,
     }
 
 
+    /**
+     * Upgrade the HTTP connection represented by the {@code HttpServletRequest} and {@code HttpServletResponse} to the
+     * WebSocket protocol and establish a WebSocket connection as per the provided {@link ServerEndpointConfig}.
+     * <p>
+     * This method is primarily intended to be used by frameworks that implement the front-controller pattern. It does
+     * not deploy the provided endpoint.
+     * <p>
+     * If the WebSocket implementation is not deployed as part of a Jakarta Servlet container, this method will throw an
+     * {@link UnsupportedOperationException}.
+     * <p>
+     * This method will be part of the Jakarta WebSocket API from version 2.1
+     *
+     * @param httpServletRequest    The {@code HttpServletRequest} to be processed as a WebSocket handshake as per
+     *                              section 4.0 of RFC 6455.
+     * @param httpServletResponse   The {@code HttpServletResponse} to be used when processing the
+     *                              {@code httpServletRequest} as a WebSocket handshake as per section 4.0 of RFC 6455.
+     * @param sec                   The server endpoint configuration to use to configure the WebSocket endpoint
+     * @param pathParameters        Provides a mapping of path parameter names and values, if any, to be used for the
+     *                              WebSocket connection established by the call to this method. If no such mapping is
+     *                              defined, an empty Map must be passed.
+     *
+     * @throws IllegalStateException if the provided request does not meet the requirements of the WebSocket handshake
+     * @throws UnsupportedOperationException if the WebSocket implementation is not deployed as part of a Jakarta
+     *                                       Servlet container
+     * @throws IOException if an I/O error occurs during the establishment of a WebSocket connection
+     * @throws DeploymentException if a configuration error prevents the establishment of a WebSocket connection
+     */
+    public void upgradeHttpToWebSocket(Object httpServletRequest, Object httpServletResponse,
+            ServerEndpointConfig sec, Map<String, String> pathParameters)
+            throws IOException, DeploymentException {
+        try {
+            UpgradeUtil.doUpgrade(this, (HttpServletRequest) httpServletRequest, (HttpServletResponse) httpServletResponse,
+                    sec, pathParameters);
+        } catch (ServletException e) {
+            throw new DeploymentException(e.getMessage(), e);
+        }
+    }
+
+
     public WsMappingResult findMapping(String path) {
 
         // Prevent registering additional endpoints once the first attempt has

diff --git a/webapps/docs/changelog.xml b/webapps/docs/changelog.xml
@@ -117,6 +117,15 @@
       </fix>
     </changelog>
   </subsection>
+  <subsection name="WebSocket">
+    <changelog>
+      <update>
+        Add a new method <code>WsServerContainer.upgradeHttpToWebSocket()</code>
+        to align with the new method that will be available from WebSocket 2.1
+        onwards. (markt)
+      </update>
+    </changelog>
+  </subsection>
 </section>
 <section name="Tomcat 10.0.12 (markt)" rtext="2021-09-28">
   <subsection name="Catalina">