1 // ========================================================================
2 // Copyright (c) 2010 Mort Bay Consulting Pty. Ltd.
3 // ------------------------------------------------------------------------
4 // All rights reserved. This program and the accompanying materials
5 // are made available under the terms of the Eclipse Public License v1.0
6 // and Apache License v2.0 which accompanies this distribution.
7 // The Eclipse Public License is available at
8 // http://www.eclipse.org/legal/epl-v10.html
9 // The Apache License v2.0 is available at
10 // http://www.opensource.org/licenses/apache2.0.php
11 // You may elect to redistribute this code under either of these licenses.
12 // ========================================================================
13
14 package org.eclipse.jetty.websocket;
15
16 import java.io.IOException;
17
18 /**
19 * WebSocket Interface.
20 * <p>
21 * This interface provides the signature for a server-side end point of a websocket connection.
22 * The Interface has several nested interfaces, for each type of message that may be received.
23 */
24 public interface WebSocket
25 {
26 /**
27 * Called when a new websocket connection is accepted.
28 * @param connection The Connection object to use to send messages.
29 */
30 void onOpen(Connection connection);
31
32 /**
33 * Called when an established websocket connection closes
34 * @param closeCode
35 * @param message
36 */
37 void onClose(int closeCode, String message);
38
39 /**
40 * A nested WebSocket interface for receiving text messages
41 */
42 interface OnTextMessage extends WebSocket
43 {
44 /**
45 * Called with a complete text message when all fragments have been received.
46 * The maximum size of text message that may be aggregated from multiple frames is set with {@link Connection#setMaxTextMessageSize(int)}.
47 * @param data The message
48 */
49 void onMessage(String data);
50 }
51
52 /**
53 * A nested WebSocket interface for receiving binary messages
54 */
55 interface OnBinaryMessage extends WebSocket
56 {
57 /**
58 * Called with a complete binary message when all fragments have been received.
59 * The maximum size of binary message that may be aggregated from multiple frames is set with {@link Connection#setMaxBinaryMessageSize(int)}.
60 * @param data
61 * @param offset
62 * @param length
63 */
64 void onMessage(byte[] data, int offset, int length);
65 }
66
67 /**
68 * A nested WebSocket interface for receiving control messages
69 */
70 interface OnControl extends WebSocket
71 {
72 /**
73 * Called when a control message has been received.
74 * @param controlCode
75 * @param data
76 * @param offset
77 * @param length
78 * @return true if this call has completely handled the control message and no further processing is needed.
79 */
80 boolean onControl(byte controlCode,byte[] data, int offset, int length);
81 }
82
83 /**
84 * A nested WebSocket interface for receiving any websocket frame
85 */
86 interface OnFrame extends WebSocket
87 {
88 /**
89 * Called when any websocket frame is received.
90 * @param flags
91 * @param opcode
92 * @param data
93 * @param offset
94 * @param length
95 * @return true if this call has completely handled the frame and no further processing is needed (including aggregation and/or message delivery)
96 */
97 boolean onFrame(byte flags,byte opcode,byte[] data, int offset, int length);
98
99 void onHandshake(FrameConnection connection);
100 }
101
102 /**
103 * A Connection interface is passed to a WebSocket instance via the {@link WebSocket#onOpen(Connection)} to
104 * give the application access to the specifics of the current connection. This includes methods
105 * for sending frames and messages as well as methods for interpreting the flags and opcodes of the connection.
106 */
107 public interface Connection
108 {
109 String getProtocol();
110 void sendMessage(String data) throws IOException;
111 void sendMessage(byte[] data, int offset, int length) throws IOException;
112
113 /**
114 * @deprecated Use {@link #close()}
115 */
116 void disconnect();
117
118 /**
119 * Close the connection with normal close code.
120 */
121 void close();
122
123 /** Close the connection with specific closeCode and message.
124 * @param closeCode The close code to send, or -1 for no close code
125 * @param message The message to send or null for no message
126 */
127 void close(int closeCode,String message);
128
129 boolean isOpen();
130
131 /**
132 * @param ms The time in ms that the connection can be idle before closing
133 */
134 void setMaxIdleTime(int ms);
135
136 /**
137 * @param size size<0 No aggregation of frames to messages, >=0 max size of text frame aggregation buffer in characters
138 */
139 void setMaxTextMessageSize(int size);
140
141 /**
142 * @param size size<0 no aggregation of binary frames, >=0 size of binary frame aggregation buffer
143 */
144 void setMaxBinaryMessageSize(int size);
145
146 /**
147 * @return The time in ms that the connection can be idle before closing
148 */
149 int getMaxIdleTime();
150
151 /**
152 * Size in characters of the maximum text message to be received
153 * @return size <0 No aggregation of frames to messages, >=0 max size of text frame aggregation buffer in characters
154 */
155 int getMaxTextMessageSize();
156
157 /**
158 * Size in bytes of the maximum binary message to be received
159 * @return size <0 no aggregation of binary frames, >=0 size of binary frame aggregation buffer
160 */
161 int getMaxBinaryMessageSize();
162 }
163
164 /**
165 * Frame Level Connection
166 * <p>The Connection interface at the level of sending/receiving frames rather than messages.
167 * Also contains methods to decode/generate flags and opcodes without using constants, so that
168 * code can be written to work with multiple drafts of the protocol.
169 *
170 */
171 public interface FrameConnection extends Connection
172 {
173 /**
174 * @return The opcode of a binary message
175 */
176 byte binaryOpcode();
177
178 /**
179 * @return The opcode of a text message
180 */
181 byte textOpcode();
182
183 /**
184 * @return The opcode of a continuation frame
185 */
186 byte continuationOpcode();
187
188 /**
189 * @return Mask for the FIN bit.
190 */
191 byte finMask();
192
193 /** Set if frames larger than the frame buffer are handled with local fragmentations
194 * @param allowFragmentation
195 */
196 void setAllowFrameFragmentation(boolean allowFragmentation);
197
198 /**
199 * @param flags The flags bytes of a frame
200 * @return True of the flags indicate a final frame.
201 */
202 boolean isMessageComplete(byte flags);
203
204 /**
205 * @param opcode
206 * @return True if the opcode is for a control frame
207 */
208 boolean isControl(byte opcode);
209
210 /**
211 * @param opcode
212 * @return True if the opcode is for a text frame
213 */
214 boolean isText(byte opcode);
215
216 /**
217 * @param opcode
218 * @return True if the opcode is for a binary frame
219 */
220 boolean isBinary(byte opcode);
221
222 /**
223 * @param opcode
224 * @return True if the opcode is for a continuation frame
225 */
226 boolean isContinuation(byte opcode);
227
228 /**
229 * @param opcode
230 * @return True if the opcode is a close control
231 */
232 boolean isClose(byte opcode);
233
234 /**
235 * @param opcode
236 * @return True if the opcode is a ping control
237 */
238 boolean isPing(byte opcode);
239
240 /**
241 * @param opcode
242 * @return True if the opcode is a pong control
243 */
244 boolean isPong(byte opcode);
245
246 /**
247 * @return True if frames larger than the frame buffer are fragmented.
248 */
249 boolean isAllowFrameFragmentation();
250
251 /** Send a control frame
252 * @param control
253 * @param data
254 * @param offset
255 * @param length
256 * @throws IOException
257 */
258 void sendControl(byte control,byte[] data, int offset, int length) throws IOException;
259
260 /** Send an arbitrary frame
261 * @param flags
262 * @param opcode
263 * @param data
264 * @param offset
265 * @param length
266 * @throws IOException
267 */
268 void sendFrame(byte flags,byte opcode,byte[] data, int offset, int length) throws IOException;
269 }
270 }