33 import java.util.concurrent.CompletionStage; |
33 import java.util.concurrent.CompletionStage; |
34 |
34 |
35 /** |
35 /** |
36 * A WebSocket Client. |
36 * A WebSocket Client. |
37 * |
37 * |
38 * <p> {@code WebSocket} instances can be created via {@link WebSocket.Builder}. |
38 * <p> {@code WebSocket} instances are created through {@link WebSocket.Builder}. |
39 * |
39 * |
40 * <p> WebSocket has an input and an output sides. These sides are independent |
40 * <p> WebSocket has an input and an output sides. These sides are independent |
41 * from each other. A side can either be open or closed. Once closed, the side |
41 * from each other. A side can either be open or closed. Once closed, the side |
42 * remains closed. WebSocket messages are sent through a {@code WebSocket} and |
42 * remains closed. WebSocket messages are sent through a {@code WebSocket} and |
43 * received through a {@code WebSocket.Listener} associated with it. Messages |
43 * received through a {@code WebSocket.Listener} associated with it. Messages |
53 * exceptionally, the operation is considered failed. An operation that has been |
53 * exceptionally, the operation is considered failed. An operation that has been |
54 * initiated but not yet completed is considered pending. |
54 * initiated but not yet completed is considered pending. |
55 * |
55 * |
56 * <p> A receive method is any of the {@code onText}, {@code onBinary}, |
56 * <p> A receive method is any of the {@code onText}, {@code onBinary}, |
57 * {@code onPing}, {@code onPong} and {@code onClose} methods of |
57 * {@code onPing}, {@code onPong} and {@code onClose} methods of |
58 * {@code Listener}. A receive method initiates a receive operation and returns |
58 * {@code Listener}. WebSocket initiates a receive operation by invoking a |
59 * a {@code CompletionStage} which completes once the operation has completed. |
59 * receive method on the listener. The listener then must return a |
|
60 * {@code CompletionStage} which completes once the operation has completed. |
60 * |
61 * |
61 * <p> A WebSocket maintains an <a id="counter">internal counter</a>. |
62 * <p> A WebSocket maintains an <a id="counter">internal counter</a>. |
62 * This counter's value is a number of times the WebSocket has yet to invoke a |
63 * This counter's value is a number of times the WebSocket has yet to invoke a |
63 * receive method. While this counter is zero the WebSocket does not invoke |
64 * receive method. While this counter is zero the WebSocket does not invoke |
64 * receive methods. The counter is incremented by {@code n} when {@code |
65 * receive methods. The counter is incremented by {@code n} when {@code |
103 int NORMAL_CLOSURE = 1000; |
104 int NORMAL_CLOSURE = 1000; |
104 |
105 |
105 /** |
106 /** |
106 * A builder of {@linkplain WebSocket WebSocket Clients}. |
107 * A builder of {@linkplain WebSocket WebSocket Clients}. |
107 * |
108 * |
108 * <p> A builder can be created by invoking the |
109 * <p> Builders are created by invoking |
109 * {@link HttpClient#newWebSocketBuilder HttpClient.newWebSocketBuilder} |
110 * {@link HttpClient#newWebSocketBuilder HttpClient.newWebSocketBuilder}. |
110 * method. The intermediate (setter-like) methods change the state of the |
111 * The intermediate (setter-like) methods change the state of the builder |
111 * builder and return the same builder they have been invoked on. If an |
112 * and return the same builder they have been invoked on. If an intermediate |
112 * intermediate method is not invoked, an appropriate default value (or |
113 * method is not invoked, an appropriate default value (or behavior) will be |
113 * behavior) will be assumed. A {@code Builder} is not safe for use by |
114 * assumed. A {@code Builder} is not safe for use by multiple threads |
114 * multiple threads without external synchronization. |
115 * without external synchronization. |
115 * |
116 * |
116 * @since 11 |
117 * @since 11 |
117 */ |
118 */ |
118 interface Builder { |
119 interface Builder { |
119 |
120 |
153 |
154 |
154 /** |
155 /** |
155 * Sets a request for the given subprotocols. |
156 * Sets a request for the given subprotocols. |
156 * |
157 * |
157 * <p> After the {@code WebSocket} has been built, the actual |
158 * <p> After the {@code WebSocket} has been built, the actual |
158 * subprotocol can be queried via |
159 * subprotocol can be queried through |
159 * {@link WebSocket#getSubprotocol WebSocket.getSubprotocol()}. |
160 * {@link WebSocket#getSubprotocol WebSocket.getSubprotocol()}. |
160 * |
161 * |
161 * <p> Subprotocols are specified in the order of preference. The most |
162 * <p> Subprotocols are specified in the order of preference. The most |
162 * preferred subprotocol is specified first. If there are any additional |
163 * preferred subprotocol is specified first. If there are any additional |
163 * subprotocols they are enumerated from the most preferred to the least |
164 * subprotocols they are enumerated from the most preferred to the least |