001/*
002 * Copyright 2002-2017 the original author or authors.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *      https://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017package org.springframework.web.socket.server;
018
019import java.security.Principal;
020import java.util.List;
021import java.util.Map;
022
023import org.springframework.http.server.ServerHttpRequest;
024import org.springframework.http.server.ServerHttpResponse;
025import org.springframework.lang.Nullable;
026import org.springframework.web.socket.WebSocketExtension;
027import org.springframework.web.socket.WebSocketHandler;
028
029/**
030 * A server-specific strategy for performing the actual upgrade to a WebSocket exchange.
031 *
032 * @author Rossen Stoyanchev
033 * @since 4.0
034 */
035public interface RequestUpgradeStrategy {
036
037        /**
038         * Return the supported WebSocket protocol versions.
039         */
040        String[] getSupportedVersions();
041
042        /**
043         * Return the WebSocket protocol extensions supported by the underlying WebSocket server.
044         */
045        List<WebSocketExtension> getSupportedExtensions(ServerHttpRequest request);
046
047        /**
048         * Perform runtime specific steps to complete the upgrade. Invoked after successful
049         * negotiation of the handshake request.
050         * @param request the current request
051         * @param response the current response
052         * @param selectedProtocol the selected sub-protocol, if any
053         * @param selectedExtensions the selected WebSocket protocol extensions
054         * @param user the user to associate with the WebSocket session
055         * @param wsHandler the handler for WebSocket messages
056         * @param attributes handshake request specific attributes to be set on the WebSocket
057         * session via {@link org.springframework.web.socket.server.HandshakeInterceptor} and
058         * thus made available to the {@link org.springframework.web.socket.WebSocketHandler}
059         * @throws HandshakeFailureException thrown when handshake processing failed to
060         * complete due to an internal, unrecoverable error, i.e. a server error as
061         * opposed to a failure to successfully negotiate the requirements of the
062         * handshake request.
063         */
064        void upgrade(ServerHttpRequest request, ServerHttpResponse response,
065                        @Nullable String selectedProtocol, List<WebSocketExtension> selectedExtensions,
066                        @Nullable Principal user, WebSocketHandler wsHandler, Map<String, Object> attributes)
067                        throws HandshakeFailureException;
068
069}