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}