View Javadoc

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 }