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 }