001/*
002 * Copyright 2002-2020 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;
018
019import java.io.Closeable;
020import java.io.IOException;
021import java.net.InetSocketAddress;
022import java.net.URI;
023import java.security.Principal;
024import java.util.List;
025import java.util.Map;
026
027import org.springframework.http.HttpHeaders;
028import org.springframework.lang.Nullable;
029
030/**
031 * A WebSocket session abstraction. Allows sending messages over a WebSocket
032 * connection and closing it.
033 *
034 * @author Rossen Stoyanchev
035 * @since 4.0
036 */
037public interface WebSocketSession extends Closeable {
038
039        /**
040         * Return a unique session identifier.
041         */
042        String getId();
043
044        /**
045         * Return the URI used to open the WebSocket connection.
046         */
047        @Nullable
048        URI getUri();
049
050        /**
051         * Return the headers used in the handshake request (never {@code null}).
052         */
053        HttpHeaders getHandshakeHeaders();
054
055        /**
056         * Return the map with attributes associated with the WebSocket session.
057         * <p>On the server side the map can be populated initially through a
058         * {@link org.springframework.web.socket.server.HandshakeInterceptor
059         * HandshakeInterceptor}. On the client side the map can be populated via
060         * {@link org.springframework.web.socket.client.WebSocketClient
061         * WebSocketClient} handshake methods.
062         * @return a Map with the session attributes (never {@code null})
063         */
064        Map<String, Object> getAttributes();
065
066        /**
067         * Return a {@link java.security.Principal} instance containing the name
068         * of the authenticated user.
069         * <p>If the user has not been authenticated, the method returns <code>null</code>.
070         */
071        @Nullable
072        Principal getPrincipal();
073
074        /**
075         * Return the address on which the request was received.
076         */
077        @Nullable
078        InetSocketAddress getLocalAddress();
079
080        /**
081         * Return the address of the remote client.
082         */
083        @Nullable
084        InetSocketAddress getRemoteAddress();
085
086        /**
087         * Return the negotiated sub-protocol.
088         * @return the protocol identifier, or {@code null} if no protocol
089         * was specified or negotiated successfully
090         */
091        @Nullable
092        String getAcceptedProtocol();
093
094        /**
095         * Configure the maximum size for an incoming text message.
096         */
097        void setTextMessageSizeLimit(int messageSizeLimit);
098
099        /**
100         * Get the configured maximum size for an incoming text message.
101         */
102        int getTextMessageSizeLimit();
103
104        /**
105         * Configure the maximum size for an incoming binary message.
106         */
107        void setBinaryMessageSizeLimit(int messageSizeLimit);
108
109        /**
110         * Get the configured maximum size for an incoming binary message.
111         */
112        int getBinaryMessageSizeLimit();
113
114        /**
115         * Determine the negotiated extensions.
116         * @return the list of extensions, or an empty list if no extension
117         * was specified or negotiated successfully
118         */
119        List<WebSocketExtension> getExtensions();
120
121        /**
122         * Send a WebSocket message: either {@link TextMessage} or {@link BinaryMessage}.
123         * <p><strong>Note:</strong> The underlying standard WebSocket session (JSR-356) does
124         * not allow concurrent sending. Therefore sending must be synchronized. To ensure
125         * that, one option is to wrap the {@code WebSocketSession} with the
126         * {@link org.springframework.web.socket.handler.ConcurrentWebSocketSessionDecorator
127         * ConcurrentWebSocketSessionDecorator}.
128         * @see org.springframework.web.socket.handler.ConcurrentWebSocketSessionDecorator
129         */
130        void sendMessage(WebSocketMessage<?> message) throws IOException;
131
132        /**
133         * Return whether the connection is still open.
134         */
135        boolean isOpen();
136
137        /**
138         * Close the WebSocket connection with status 1000, i.e. equivalent to:
139         * <pre class="code">
140         * session.close(CloseStatus.NORMAL);
141         * </pre>
142         */
143        @Override
144        void close() throws IOException;
145
146        /**
147         * Close the WebSocket connection with the given close status.
148         */
149        void close(CloseStatus status) throws IOException;
150
151}