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 void disconnect(); 113 boolean isOpen(); 114 115 /** 116 * @param size size<0 No aggregation of frames to messages, >=0 max size of text frame aggregation buffer in characters 117 */ 118 void setMaxTextMessageSize(int size); 119 120 /** 121 * @param size size<0 no aggregation of binary frames, >=0 size of binary frame aggregation buffer 122 */ 123 void setMaxBinaryMessageSize(int size); 124 125 /** 126 * Size in characters of the maximum text message to be received 127 * @return size <0 No aggregation of frames to messages, >=0 max size of text frame aggregation buffer in characters 128 */ 129 int getMaxTextMessageSize(); 130 131 /** 132 * Size in bytes of the maximum binary message to be received 133 * @return size <0 no aggregation of binary frames, >=0 size of binary frame aggregation buffer 134 */ 135 int getMaxBinaryMessageSize(); 136 } 137 138 /** 139 * Frame Level Connection 140 * <p>The Connection interface at the level of sending/receiving frames rather than messages. 141 * 142 */ 143 public interface FrameConnection extends Connection 144 { 145 boolean isMessageComplete(byte flags); 146 void close(int closeCode,String message); 147 byte binaryOpcode(); 148 byte textOpcode(); 149 150 boolean isControl(byte opcode); 151 boolean isText(byte opcode); 152 boolean isBinary(byte opcode); 153 boolean isContinuation(byte opcode); 154 boolean isClose(byte opcode); 155 boolean isPing(byte opcode); 156 boolean isPong(byte opcode); 157 158 void sendControl(byte control,byte[] data, int offset, int length) throws IOException; 159 void sendFrame(byte flags,byte opcode,byte[] data, int offset, int length) throws IOException; 160 } 161 162 }