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