forked from jooby-project/jooby
-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathWebSocket.java
More file actions
252 lines (231 loc) · 6.55 KB
/
WebSocket.java
File metadata and controls
252 lines (231 loc) · 6.55 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
/**
* Jooby https://jooby.io
* Apache License Version 2.0 https://jooby.io/LICENSE.txt
* Copyright 2014 Edgar Espina
*/
package io.jooby;
import javax.annotation.Nonnull;
import java.util.List;
import java.util.Map;
/**
* Websocket. Usage:
*
* <pre>{@code
*
* ws("/pattern", (ctx, configurer) -> {
* configurer.onConnect(ws -> {
* // Connect callback
* }):
*
* configurer.onMessage((ws, message) -> {
* ws.send("Got: " + message.value());
* });
*
* configurer.onClose((ws, closeStatus) -> {
* // Closing websocket
* });
*
* configurer.onError((ws, cause) -> {
*
* });
* });
*
* }</pre>
*
* NOTE: Websocket API ONLY handles text messages (not binary message).
*
* @author edgar
* @since 2.2.0
*/
public interface WebSocket {
/**
* Websocket initializer. Give you access to a read-only {@link Context} you are free to access
* to request attributes, while attempt to modify a response results in exception.
*/
interface Initializer {
/**
* Callback with a readonly context and websocket configurer.
*
* @param ctx Readonly context.
* @param configurer WebSocket configurer.
*/
void init(@Nonnull Context ctx, @Nonnull WebSocketConfigurer configurer);
}
/**
* On connect callback.
*/
interface OnConnect {
/**
* On connect callback with recently created web socket.
*
* @param ws WebSocket.
*/
void onConnect(@Nonnull WebSocket ws);
}
/**
* On message callback. When a Message is send by a client, this callback allow you to
* handle/react to it.
*/
interface OnMessage {
/**
* Generated when a client send a message.
*
* @param ws WebSocket.
* @param message Client message.
*/
void onMessage(@Nonnull WebSocket ws, @Nonnull WebSocketMessage message);
}
/**
* On close callback. Generated when client close the connection or when explicit calls to
* {@link #close(WebSocketCloseStatus)}.
*/
interface OnClose {
/**
* Generated when client close the connection or when explicit calls to
* {@link #close(WebSocketCloseStatus)}.
*
* @param ws WebSocket.
* @param closeStatus Close status.
*/
void onClose(@Nonnull WebSocket ws, @Nonnull WebSocketCloseStatus closeStatus);
}
/**
* On error callback. Generated when unexpected error occurs.
*/
interface OnError {
/**
* Error callback, let you listen for exception. Websocket might or might not be open.
*
* @param ws Websocket.
* @param cause Cause.
*/
void onError(@Nonnull WebSocket ws, @Nonnull Throwable cause);
}
/** Max message size for websocket (128K). */
int MAX_BUFFER_SIZE = 131072;
/**
* Originating HTTP context. Please note this is a read-only context, so you are not allowed
* to modify or produces a response from it.
*
* The context let give you access to originating request (then one that was upgrade it).
*
* @return Read-only originating HTTP request.
*/
@Nonnull Context getContext();
/**
* Context attributes (a.k.a request attributes).
*
* @return Context attributes.
*/
default @Nonnull Map<String, Object> getAttributes() {
return getContext().getAttributes();
}
/**
* Get an attribute by his key. This is just an utility method around {@link #getAttributes()}.
* This method look first in current context and fallback to application attributes.
*
* @param key Attribute key.
* @param <T> Attribute type.
* @return Attribute value.
*/
default @Nonnull <T> T attribute(@Nonnull String key) {
return getContext().attribute(key);
}
/**
* Set an application attribute.
*
* @param key Attribute key.
* @param value Attribute value.
* @return This router.
*/
default @Nonnull WebSocket attribute(@Nonnull String key, Object value) {
getContext().attribute(key, value);
return this;
}
/**
* Send a text message to client.
*
* @param message Text Message.
* @return This websocket.
*/
default @Nonnull WebSocket send(@Nonnull String message) {
return send(message, false);
}
/**
* Web sockets connected to the same path. This method doesn't include the current
* websocket.
*
* @return Web sockets or empty list.
*/
@Nonnull List<WebSocket> getSessions();
/**
* True if websocket is open.
*
* @return True when open.
*/
boolean isOpen();
/**
* Send a text message to current client (broadcast = false) or to ALL connected clients under the
* websocket path (broadcast = true).
*
* @param message Text Message.
* @param broadcast True to send to all connected clients.
* @return This websocket.
*/
@Nonnull WebSocket send(@Nonnull String message, boolean broadcast);
/**
* Send a text message to client.
*
* @param message Text Message.
* @return This websocket.
*/
default @Nonnull WebSocket send(@Nonnull byte[] message) {
return send(message, false);
}
/**
* Send a text message to current client (broadcast = false) or to ALL connected clients under the
* websocket path (broadcast = true).
*
* @param message Text Message.
* @param broadcast True to send to all connected clients.
* @return This websocket.
*/
@Nonnull WebSocket send(@Nonnull byte[] message, boolean broadcast);
/**
* Encode a value and send a text message to client.
*
* @param value Value to send.
* @return This websocket.
*/
default @Nonnull WebSocket render(@Nonnull Object value) {
return render(value, false);
}
/**
* Encode a value and send a text message to current client (broadcast = false) or to ALL
* connected clients under the websocket path (broadcast = true).
*
* @param value Value to send.
* @param broadcast True to send to all connected clients.
* @return This websocket.
*/
@Nonnull WebSocket render(@Nonnull Object value, boolean broadcast);
/**
* Close the web socket and send a {@link WebSocketCloseStatus#NORMAL} code to client.
*
* This method fires a {@link OnClose#onClose(WebSocket, WebSocketCloseStatus)} callback.
*
* @return This websocket.
*/
default @Nonnull WebSocket close() {
return close(WebSocketCloseStatus.NORMAL);
}
/**
* Close the web socket and send a close status code to client.
*
* This method fires a {@link OnClose#onClose(WebSocket, WebSocketCloseStatus)} callback.
*
* @param closeStatus Close status.
* @return This websocket.
*/
@Nonnull WebSocket close(@Nonnull WebSocketCloseStatus closeStatus);
}