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