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
228
229
|
/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package javax.websocket;
import java.io.IOException;
import java.io.OutputStream;
import java.io.Writer;
import java.nio.ByteBuffer;
import java.util.concurrent.Future;
public interface RemoteEndpoint {
interface Async extends RemoteEndpoint {
/**
* Obtain the timeout (in milliseconds) for sending a message
* asynchronously. The default value is determined by
* {@link WebSocketContainer#getDefaultAsyncSendTimeout()}.
* @return The current send timeout in milliseconds. A non-positive
* value means an infinite timeout.
*/
long getSendTimeout();
/**
* Set the timeout (in milliseconds) for sending a message
* asynchronously. The default value is determined by
* {@link WebSocketContainer#getDefaultAsyncSendTimeout()}.
* @param timeout The new timeout for sending messages asynchronously
* in milliseconds. A non-positive value means an
* infinite timeout.
*/
void setSendTimeout(long timeout);
/**
* Send the message asynchronously, using the SendHandler to signal to the
* client when the message has been sent.
* @param text The text message to send
* @param completion Used to signal to the client when the message has
* been sent
*/
void sendText(String text, SendHandler completion);
/**
* Send the message asynchronously, using the Future to signal to the
* client when the message has been sent.
* @param text The text message to send
* @return A Future that signals when the message has been sent.
*/
Future<Void> sendText(String text);
/**
* Send the message asynchronously, using the Future to signal to the client
* when the message has been sent.
* @param data The text message to send
* @return A Future that signals when the message has been sent.
* @throws IllegalArgumentException if {@code data} is {@code null}.
*/
Future<Void> sendBinary(ByteBuffer data);
/**
* Send the message asynchronously, using the SendHandler to signal to the
* client when the message has been sent.
* @param data The text message to send
* @param completion Used to signal to the client when the message has
* been sent
* @throws IllegalArgumentException if {@code data} or {@code completion}
* is {@code null}.
*/
void sendBinary(ByteBuffer data, SendHandler completion);
/**
* Encodes object as a message and sends it asynchronously, using the
* Future to signal to the client when the message has been sent.
* @param obj The object to be sent.
* @return A Future that signals when the message has been sent.
* @throws IllegalArgumentException if {@code obj} is {@code null}.
*/
Future<Void> sendObject(Object obj);
/**
* Encodes object as a message and sends it asynchronously, using the
* SendHandler to signal to the client when the message has been sent.
* @param obj The object to be sent.
* @param completion Used to signal to the client when the message has
* been sent
* @throws IllegalArgumentException if {@code obj} or
* {@code completion} is {@code null}.
*/
void sendObject(Object obj, SendHandler completion);
}
interface Basic extends RemoteEndpoint {
/**
* Send the message, blocking until the message is sent.
* @param text The text message to send.
* @throws IllegalArgumentException if {@code text} is {@code null}.
* @throws IOException if an I/O error occurs during the sending of the
* message.
*/
void sendText(String text) throws IOException;
/**
* Send the message, blocking until the message is sent.
* @param data The binary message to send
* @throws IllegalArgumentException if {@code data} is {@code null}.
* @throws IOException if an I/O error occurs during the sending of the
* message.
*/
void sendBinary(ByteBuffer data) throws IOException;
/**
* Sends part of a text message to the remote endpoint. Once the first part
* of a message has been sent, no other text or binary messages may be sent
* until all remaining parts of this message have been sent.
*
* @param fragment The partial message to send
* @param isLast <code>true</code> if this is the last part of the
* message, otherwise <code>false</code>
* @throws IllegalArgumentException if {@code fragment} is {@code null}.
* @throws IOException if an I/O error occurs during the sending of the
* message.
*/
void sendText(String fragment, boolean isLast) throws IOException;
/**
* Sends part of a binary message to the remote endpoint. Once the first
* part of a message has been sent, no other text or binary messages may be
* sent until all remaining parts of this message have been sent.
*
* @param partialByte The partial message to send
* @param isLast <code>true</code> if this is the last part of the
* message, otherwise <code>false</code>
* @throws IllegalArgumentException if {@code partialByte} is
* {@code null}.
* @throws IOException if an I/O error occurs during the sending of the
* message.
*/
void sendBinary(ByteBuffer partialByte, boolean isLast) throws IOException;
OutputStream getSendStream() throws IOException;
Writer getSendWriter() throws IOException;
/**
* Encodes object as a message and sends it to the remote endpoint.
* @param data The object to be sent.
* @throws EncodeException if there was a problem encoding the
* {@code data} object as a websocket message.
* @throws IllegalArgumentException if {@code data} is {@code null}.
* @throws IOException if an I/O error occurs during the sending of the
* message.
*/
void sendObject(Object data) throws IOException, EncodeException;
}
/**
* Enable or disable the batching of outgoing messages for this endpoint. If
* batching is disabled when it was previously enabled then this method will
* block until any currently batched messages have been written.
*
* @param batchingAllowed New setting
* @throws IOException If changing the value resulted in a call to
* {@link #flushBatch()} and that call threw an
* {@link IOException}.
*/
void setBatchingAllowed(boolean batchingAllowed) throws IOException;
/**
* Obtains the current batching status of the endpoint.
*
* @return <code>true</code> if batching is enabled, otherwise
* <code>false</code>.
*/
boolean getBatchingAllowed();
/**
* Flush any currently batched messages to the remote endpoint. This method
* will block until the flush completes.
*
* @throws IOException If an I/O error occurs while flushing
*/
void flushBatch() throws IOException;
/**
* Send a ping message blocking until the message has been sent. Note that
* if a message is in the process of being sent asynchronously, this method
* will block until that message and this ping has been sent.
*
* @param applicationData The payload for the ping message
*
* @throws IOException If an I/O error occurs while sending the ping
* @throws IllegalArgumentException if the applicationData is too large for
* a control message (max 125 bytes)
*/
void sendPing(ByteBuffer applicationData)
throws IOException, IllegalArgumentException;
/**
* Send a pong message blocking until the message has been sent. Note that
* if a message is in the process of being sent asynchronously, this method
* will block until that message and this pong has been sent.
*
* @param applicationData The payload for the pong message
*
* @throws IOException If an I/O error occurs while sending the pong
* @throws IllegalArgumentException if the applicationData is too large for
* a control message (max 125 bytes)
*/
void sendPong(ByteBuffer applicationData)
throws IOException, IllegalArgumentException;
}
|
