57 * {@code onPing}, {@code onPong} and {@code onClose} methods of |
57 * {@code onPing}, {@code onPong} and {@code onClose} methods of |
58 * {@code Listener}. WebSocket initiates a receive operation by invoking a |
58 * {@code Listener}. WebSocket initiates a receive operation by invoking a |
59 * receive method on the listener. The listener then must return a |
59 * receive method on the listener. The listener then must return a |
60 * {@code CompletionStage} which completes once the operation has completed. |
60 * {@code CompletionStage} which completes once the operation has completed. |
61 * |
61 * |
62 * <p> To control message receiving, a WebSocket maintains an |
62 * <p> To control receiving of messages, a WebSocket maintains an |
63 * <a id="counter">internal counter</a>. This counter's value is a number of |
63 * <a id="counter">internal counter</a>. This counter's value is a number of |
64 * times the WebSocket has yet to invoke a receive method. While this counter is |
64 * times the WebSocket has yet to invoke a receive method. While this counter is |
65 * zero the WebSocket does not invoke receive methods. The counter is |
65 * zero the WebSocket does not invoke receive methods. The counter is |
66 * incremented by {@code n} when {@code request(n)} is called. The counter is |
66 * incremented by {@code n} when {@code request(n)} is called. The counter is |
67 * decremented by one when the WebSocket invokes a receive method. |
67 * decremented by one when the WebSocket invokes a receive method. |
68 * {@code onOpen} and {@code onError} are not receive methods. WebSocket invokes |
68 * {@code onOpen} and {@code onError} are not receive methods. WebSocket invokes |
69 * {@code onOpen} prior to any other methods on the listener. WebSocket invokes |
69 * {@code onOpen} prior to any other methods on the listener. WebSocket invokes |
70 * {@code onOpen} at most once. WebSocket may invoke {@code onError} at any |
70 * {@code onOpen} at most once. WebSocket may invoke {@code onError} at any |
71 * given time. If the WebSocket invokes {@code onError} or {@code onClose}, then |
71 * given time. If the WebSocket invokes {@code onError} or {@code onClose}, then |
72 * no further listener's methods will be invoked, no matter the value of the |
72 * no further listener's methods will be invoked, no matter the value of the |
73 * counter. For a newly built WebSocket the counter is zero. A WebSocket invokes |
73 * counter. For a newly built WebSocket the counter is zero. |
74 * methods on the listener in a thread-safe manner. |
|
75 * |
74 * |
76 * <p> Unless otherwise stated, {@code null} arguments will cause methods |
75 * <p> Unless otherwise stated, {@code null} arguments will cause methods |
77 * of {@code WebSocket} to throw {@code NullPointerException}, similarly, |
76 * of {@code WebSocket} to throw {@code NullPointerException}, similarly, |
78 * {@code WebSocket} will not pass {@code null} arguments to methods of |
77 * {@code WebSocket} will not pass {@code null} arguments to methods of |
79 * {@code Listener}. The state of a WebSocket is not changed by the invocations |
78 * {@code Listener}. The state of a WebSocket is not changed by the invocations |
218 |
217 |
219 /** |
218 /** |
220 * The receiving interface of {@code WebSocket}. |
219 * The receiving interface of {@code WebSocket}. |
221 * |
220 * |
222 * <p> A {@code WebSocket} invokes methods of the associated listener |
221 * <p> A {@code WebSocket} invokes methods of the associated listener |
223 * passing itself as an argument. When data has been received, the |
222 * passing itself as an argument. These methods are invoked in a thread-safe |
224 * {@code WebSocket} invokes a receive method. Methods {@code onText}, |
223 * manner, such that the next invocation may start only after the previous |
225 * {@code onBinary}, {@code onPing} and {@code onPong} must return a |
224 * one has finished. |
226 * {@code CompletionStage} that completes once the message has been received |
225 * |
227 * by the listener. |
226 * <p> When data has been received, the {@code WebSocket} invokes a receive |
|
227 * method. Methods {@code onText}, {@code onBinary}, {@code onPing} and |
|
228 * {@code onPong} must return a {@code CompletionStage} that completes once |
|
229 * the message has been received by the listener. If a listener's method |
|
230 * returns {@code null} rather than a {@code CompletionStage}, |
|
231 * {@code WebSocket} will behave as if the listener returned a |
|
232 * {@code CompletionStage} that is already completed normally. |
228 * |
233 * |
229 * <p> An {@code IOException} raised in {@code WebSocket} will result in an |
234 * <p> An {@code IOException} raised in {@code WebSocket} will result in an |
230 * invocation of {@code onError} with that exception (if the input is not |
235 * invocation of {@code onError} with that exception (if the input is not |
231 * closed). Unless otherwise stated if the listener's method throws an |
236 * closed). Unless otherwise stated if the listener's method throws an |
232 * exception or a {@code CompletionStage} returned from a method completes |
237 * exception or a {@code CompletionStage} returned from a method completes |
233 * exceptionally, the WebSocket will invoke {@code onError} with this |
238 * exceptionally, the WebSocket will invoke {@code onError} with this |
234 * exception. |
239 * exception. |
235 * |
240 * |
236 * <p> If a listener's method returns {@code null} rather than a |
241 * @apiNote <p> The strict sequential order of invocations from |
237 * {@code CompletionStage}, {@code WebSocket} will behave as if the listener |
242 * {@code WebSocket} to {@code Listener} means, in particular, that |
238 * returned a {@code CompletionStage} that is already completed normally. |
243 * {@code Listener}'s methods are treated as non-reentrant. Which means that |
239 * |
244 * {@code Listener} implementations do not need to be concerned with |
240 * @apiNote Careful attention may be required if a listener is associated |
245 * possible recursion or the order in which they call |
|
246 * {@code WebSocket.request} in relation to their processing logic. |
|
247 * |
|
248 * <p> Careful attention may be required if a listener is associated |
241 * with more than a single {@code WebSocket}. In this case invocations |
249 * with more than a single {@code WebSocket}. In this case invocations |
242 * related to different instances of {@code WebSocket} may not be ordered |
250 * related to different instances of {@code WebSocket} may not be ordered |
243 * and may even happen concurrently. |
251 * and may even happen concurrently. |
244 * |
252 * |
245 * <p> {@code CompletionStage}s returned from the receive methods have |
253 * <p> {@code CompletionStage}s returned from the receive methods have |