1 /*
2 * Copyright 2002-2015 the original author or authors.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17 package org.springframework.web.socket;
18
19 import java.io.Closeable;
20 import java.io.IOException;
21 import java.net.InetSocketAddress;
22 import java.net.URI;
23 import java.security.Principal;
24 import java.util.List;
25 import java.util.Map;
26
27 import org.springframework.http.HttpHeaders;
28
29 /**
30 * A WebSocket session abstraction. Allows sending messages over a WebSocket
31 * connection and closing it.
32 *
33 * @author Rossen Stoyanchev
34 * @since 4.0
35 */
36 public interface WebSocketSession extends Closeable {
37
38 /**
39 * Return a unique session identifier.
40 */
41 String getId();
42
43 /**
44 * Return the URI used to open the WebSocket connection.
45 */
46 URI getUri();
47
48 /**
49 * Return the headers used in the handshake request.
50 */
51 HttpHeaders getHandshakeHeaders();
52
53 /**
54 * Return the map with attributes associated with the WebSocket session.
55 * <p>On the server side the map can be populated initially through a
56 * {@link org.springframework.web.socket.server.HandshakeInterceptor
57 * HandshakeInterceptor}. On the client side the map can be populated via
58 * {@link org.springframework.web.socket.client.WebSocketClient
59 * WebSocketClient} handshake methods.
60 * @return a Map with the session attributes, never {@code null}.
61 */
62 Map<String, Object> getAttributes();
63
64 /**
65 * Return a {@link java.security.Principal} instance containing the name of the
66 * authenticated user.
67 * <p>If the user has not been authenticated, the method returns <code>null</code>.
68 */
69 Principal getPrincipal();
70
71 /**
72 * Return the address on which the request was received.
73 */
74 InetSocketAddress getLocalAddress();
75
76 /**
77 * Return the address of the remote client.
78 */
79 InetSocketAddress getRemoteAddress();
80
81 /**
82 * Return the negotiated sub-protocol or {@code null} if none was specified or
83 * negotiated successfully.
84 */
85 String getAcceptedProtocol();
86
87 /**
88 * Configure the maximum size for an incoming text message.
89 */
90 void setTextMessageSizeLimit(int messageSizeLimit);
91
92 /**
93 * Get the configured maximum size for an incoming text message.
94 */
95 int getTextMessageSizeLimit();
96
97 /**
98 * Configure the maximum size for an incoming binary message.
99 */
100 void setBinaryMessageSizeLimit(int messageSizeLimit);
101
102 /**
103 * Get the configured maximum size for an incoming binary message.
104 */
105 int getBinaryMessageSizeLimit();
106
107 /**
108 * Return the negotiated extensions or {@code null} if none was specified or
109 * negotiated successfully.
110 */
111 List<WebSocketExtension> getExtensions();
112
113 /**
114 * Send a WebSocket message: either {@link TextMessage} or {@link BinaryMessage}.
115 */
116 void sendMessage(WebSocketMessage<?> message) throws IOException;
117
118 /**
119 * Return whether the connection is still open.
120 */
121 boolean isOpen();
122
123 /**
124 * Close the WebSocket connection with status 1000, i.e. equivalent to:
125 * <pre class="code">
126 * session.close(CloseStatus.NORMAL);
127 * </pre>
128 */
129 @Override
130 void close() throws IOException;
131
132 /**
133 * Close the WebSocket connection with the given close status.
134 */
135 void close(CloseStatus status) throws IOException;
136
137 }