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
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
|
//
// ========================================================================
// Copyright (c) 1995-2012 Mort Bay Consulting Pty. Ltd.
// ------------------------------------------------------------------------
// All rights reserved. This program and the accompanying materials
// are made available under the terms of the Eclipse Public License v1.0
// and Apache License v2.0 which accompanies this distribution.
//
// The Eclipse Public License is available at
// http://www.eclipse.org/legal/epl-v10.html
//
// The Apache License v2.0 is available at
// http://www.opensource.org/licenses/apache2.0.php
//
// You may elect to redistribute this code under either of these licenses.
// ========================================================================
//
package org.eclipse.jetty.websocket;
import java.io.IOException;
/**
* WebSocket Interface.
* <p>
* This interface provides the signature for a server-side end point of a websocket connection.
* The Interface has several nested interfaces, for each type of message that may be received.
*/
public interface WebSocket
{
/**
* Called when a new websocket connection is accepted.
* @param connection The Connection object to use to send messages.
*/
void onOpen(Connection connection);
/**
* Called when an established websocket connection closes
* @param closeCode
* @param message
*/
void onClose(int closeCode, String message);
/**
* A nested WebSocket interface for receiving text messages
*/
interface OnTextMessage extends WebSocket
{
/**
* Called with a complete text message when all fragments have been received.
* The maximum size of text message that may be aggregated from multiple frames is set with {@link Connection#setMaxTextMessageSize(int)}.
* @param data The message
*/
void onMessage(String data);
}
/**
* A nested WebSocket interface for receiving binary messages
*/
interface OnBinaryMessage extends WebSocket
{
/**
* Called with a complete binary message when all fragments have been received.
* The maximum size of binary message that may be aggregated from multiple frames is set with {@link Connection#setMaxBinaryMessageSize(int)}.
* @param data
* @param offset
* @param length
*/
void onMessage(byte[] data, int offset, int length);
}
/**
* A nested WebSocket interface for receiving control messages
*/
interface OnControl extends WebSocket
{
/**
* Called when a control message has been received.
* @param controlCode
* @param data
* @param offset
* @param length
* @return true if this call has completely handled the control message and no further processing is needed.
*/
boolean onControl(byte controlCode,byte[] data, int offset, int length);
}
/**
* A nested WebSocket interface for receiving any websocket frame
*/
interface OnFrame extends WebSocket
{
/**
* Called when any websocket frame is received.
* @param flags
* @param opcode
* @param data
* @param offset
* @param length
* @return true if this call has completely handled the frame and no further processing is needed (including aggregation and/or message delivery)
*/
boolean onFrame(byte flags,byte opcode,byte[] data, int offset, int length);
void onHandshake(FrameConnection connection);
}
/**
* A Connection interface is passed to a WebSocket instance via the {@link WebSocket#onOpen(Connection)} to
* give the application access to the specifics of the current connection. This includes methods
* for sending frames and messages as well as methods for interpreting the flags and opcodes of the connection.
*/
public interface Connection
{
String getProtocol();
void sendMessage(String data) throws IOException;
void sendMessage(byte[] data, int offset, int length) throws IOException;
/**
* @deprecated Use {@link #close()}
*/
void disconnect();
/**
* Close the connection with normal close code.
*/
void close();
/** Close the connection with specific closeCode and message.
* @param closeCode The close code to send, or -1 for no close code
* @param message The message to send or null for no message
*/
void close(int closeCode,String message);
boolean isOpen();
/**
* @param ms The time in ms that the connection can be idle before closing
*/
void setMaxIdleTime(int ms);
/**
* @param size size<0 No aggregation of frames to messages, >=0 max size of text frame aggregation buffer in characters
*/
void setMaxTextMessageSize(int size);
/**
* @param size size<0 no aggregation of binary frames, >=0 size of binary frame aggregation buffer
*/
void setMaxBinaryMessageSize(int size);
/**
* @return The time in ms that the connection can be idle before closing
*/
int getMaxIdleTime();
/**
* Size in characters of the maximum text message to be received
* @return size <0 No aggregation of frames to messages, >=0 max size of text frame aggregation buffer in characters
*/
int getMaxTextMessageSize();
/**
* Size in bytes of the maximum binary message to be received
* @return size <0 no aggregation of binary frames, >=0 size of binary frame aggregation buffer
*/
int getMaxBinaryMessageSize();
}
/**
* Frame Level Connection
* <p>The Connection interface at the level of sending/receiving frames rather than messages.
* Also contains methods to decode/generate flags and opcodes without using constants, so that
* code can be written to work with multiple drafts of the protocol.
*
*/
public interface FrameConnection extends Connection
{
/**
* @return The opcode of a binary message
*/
byte binaryOpcode();
/**
* @return The opcode of a text message
*/
byte textOpcode();
/**
* @return The opcode of a continuation frame
*/
byte continuationOpcode();
/**
* @return Mask for the FIN bit.
*/
byte finMask();
/** Set if frames larger than the frame buffer are handled with local fragmentations
* @param allowFragmentation
*/
void setAllowFrameFragmentation(boolean allowFragmentation);
/**
* @param flags The flags bytes of a frame
* @return True of the flags indicate a final frame.
*/
boolean isMessageComplete(byte flags);
/**
* @param opcode
* @return True if the opcode is for a control frame
*/
boolean isControl(byte opcode);
/**
* @param opcode
* @return True if the opcode is for a text frame
*/
boolean isText(byte opcode);
/**
* @param opcode
* @return True if the opcode is for a binary frame
*/
boolean isBinary(byte opcode);
/**
* @param opcode
* @return True if the opcode is for a continuation frame
*/
boolean isContinuation(byte opcode);
/**
* @param opcode
* @return True if the opcode is a close control
*/
boolean isClose(byte opcode);
/**
* @param opcode
* @return True if the opcode is a ping control
*/
boolean isPing(byte opcode);
/**
* @param opcode
* @return True if the opcode is a pong control
*/
boolean isPong(byte opcode);
/**
* @return True if frames larger than the frame buffer are fragmented.
*/
boolean isAllowFrameFragmentation();
/** Send a control frame
* @param control
* @param data
* @param offset
* @param length
* @throws IOException
*/
void sendControl(byte control,byte[] data, int offset, int length) throws IOException;
/** Send an arbitrary frame
* @param flags
* @param opcode
* @param data
* @param offset
* @param length
* @throws IOException
*/
void sendFrame(byte flags,byte opcode,byte[] data, int offset, int length) throws IOException;
}
}
|
