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}