forked from TooTallNate/Java-WebSocket
/
WebSocket.java
227 lines (197 loc) · 6.79 KB
/
WebSocket.java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
/*
* Copyright (c) 2010-2019 Nathan Rajlich
*
* Permission is hereby granted, free of charge, to any person
* obtaining a copy of this software and associated documentation
* files (the "Software"), to deal in the Software without
* restriction, including without limitation the rights to use,
* copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the
* Software is furnished to do so, subject to the following
* conditions:
*
* The above copyright notice and this permission notice shall be
* included in all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
* OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
* NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
* WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
* FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
* OTHER DEALINGS IN THE SOFTWARE.
*/
package org.java_websocket;
import java.net.InetSocketAddress;
import java.nio.ByteBuffer;
import java.util.Collection;
import org.java_websocket.drafts.Draft;
import org.java_websocket.enums.Opcode;
import org.java_websocket.enums.ReadyState;
import org.java_websocket.exceptions.WebsocketNotConnectedException;
import org.java_websocket.framing.Framedata;
import javax.net.ssl.SSLEngine;
public interface WebSocket {
/**
* sends the closing handshake.
* may be send in response to an other handshake.
* @param code the closing code
* @param message the closing message
*/
void close( int code, String message );
/**
* sends the closing handshake.
* may be send in response to an other handshake.
* @param code the closing code
*/
void close( int code );
/** Convenience function which behaves like close(CloseFrame.NORMAL) */
void close();
/**
* This will close the connection immediately without a proper close handshake.
* The code and the message therefore won't be transfered over the wire also they will be forwarded to onClose/onWebsocketClose.
* @param code the closing code
* @param message the closing message
**/
void closeConnection( int code, String message );
/**
* Send Text data to the other end.
*
* @param text the text data to send
* @throws WebsocketNotConnectedException websocket is not yet connected
*/
void send( String text );
/**
* Send Binary data (plain bytes) to the other end.
*
* @param bytes the binary data to send
* @throws IllegalArgumentException the data is null
* @throws WebsocketNotConnectedException websocket is not yet connected
*/
void send( ByteBuffer bytes );
/**
* Send Binary data (plain bytes) to the other end.
*
* @param bytes the byte array to send
* @throws IllegalArgumentException the data is null
* @throws WebsocketNotConnectedException websocket is not yet connected
*/
void send( byte[] bytes );
/**
* Send a frame to the other end
* @param framedata the frame to send to the other end
*/
void sendFrame( Framedata framedata );
/**
* Send a collection of frames to the other end
* @param frames the frames to send to the other end
*/
void sendFrame( Collection<Framedata> frames );
/**
* Send a ping to the other end
* @throws WebsocketNotConnectedException websocket is not yet connected
*/
void sendPing();
/**
* Allows to send continuous/fragmented frames conveniently. <br>
* For more into on this frame type see http://tools.ietf.org/html/rfc6455#section-5.4<br>
*
* If the first frame you send is also the last then it is not a fragmented frame and will received via onMessage instead of onFragmented even though it was send by this method.
*
* @param op
* This is only important for the first frame in the sequence. Opcode.TEXT, Opcode.BINARY are allowed.
* @param buffer
* The buffer which contains the payload. It may have no bytes remaining.
* @param fin
* true means the current frame is the last in the sequence.
**/
void sendFragmentedFrame( Opcode op, ByteBuffer buffer, boolean fin );
/**
* Checks if the websocket has buffered data
* @return has the websocket buffered data
*/
boolean hasBufferedData();
/**
* Returns the address of the endpoint this socket is connected to, or{@code null} if it is unconnected.
*
* @return never returns null
*/
InetSocketAddress getRemoteSocketAddress();
/**
* Returns the address of the endpoint this socket is bound to.
*
* @return never returns null
*/
InetSocketAddress getLocalSocketAddress();
/**
* Is the websocket in the state OPEN
* @return state equals ReadyState.OPEN
*/
boolean isOpen();
/**
* Is the websocket in the state CLOSING
* @return state equals ReadyState.CLOSING
*/
boolean isClosing();
/**
* Returns true when no further frames may be submitted<br>
* This happens before the socket connection is closed.
* @return true when no further frames may be submitted
*/
boolean isFlushAndClose();
/**
* Is the websocket in the state CLOSED
* @return state equals ReadyState.CLOSED
*/
boolean isClosed();
/**
* Getter for the draft
* @return the used draft
*/
Draft getDraft();
/**
* Retrieve the WebSocket 'ReadyState'.
* This represents the state of the connection.
* It returns a numerical value, as per W3C WebSockets specs.
*
* @return Returns '0 = CONNECTING', '1 = OPEN', '2 = CLOSING' or '3 = CLOSED'
*/
ReadyState getReadyState();
/**
* Returns the HTTP Request-URI as defined by http://tools.ietf.org/html/rfc2616#section-5.1.2<br>
* If the opening handshake has not yet happened it will return null.
* @return Returns the decoded path component of this URI.
**/
String getResourceDescriptor();
/**
* Setter for an attachment on the socket connection.
* The attachment may be of any type.
*
* @param attachment The object to be attached to the user
* @param <T> The type of the attachment
* @since 1.3.7
**/
<T> void setAttachment(T attachment);
/**
* Getter for the connection attachment.
*
* @param <T> The type of the attachment
* @return Returns the user attachment
* @since 1.3.7
**/
<T> T getAttachment();
/**
* Does this websocket use an encrypted (wss/ssl) or unencrypted (ws) connection
* @return true, if the websocket does use wss and therefore has a SSLEngine
* @since 1.4.1
*/
boolean hasSSLEngine();
/**
* Returns the ssl engine of websocket, if ssl/wss is used for this instance.
* @return the ssl engine of this websocket instance
* @throws IllegalArgumentException the underlying channel does not use ssl (use hasSSLEngine() to check)
* @since 1.4.1
*/
SSLEngine getSSLEngine() throws IllegalArgumentException;
}