61 * value is a number of times the WebSocket has yet to invoke a receive method. |
61 * value is a number of times the WebSocket has yet to invoke a receive method. |
62 * While this counter is zero the WebSocket does not invoke receive methods. The |
62 * While this counter is zero the WebSocket does not invoke receive methods. The |
63 * counter is incremented by {@code n} when {@code request(n)} is called. The |
63 * counter is incremented by {@code n} when {@code request(n)} is called. The |
64 * counter is decremented by one when the WebSocket invokes a receive method. |
64 * counter is decremented by one when the WebSocket invokes a receive method. |
65 * {@code onOpen} and {@code onError} are not receive methods. WebSocket invokes |
65 * {@code onOpen} and {@code onError} are not receive methods. WebSocket invokes |
66 * {@code onOpen} prior to any other methods on the listener. WebSocket may |
66 * {@code onOpen} prior to any other methods on the listener. WebSocket invokes |
67 * invoke {@code onError} at any given time. If the WebSocket invokes |
67 * {@code onOpen} at most once. WebSocket may invoke {@code onError} at any |
68 * {@code onError} or {@code onClose}, then no further listener's methods will |
68 * given time. If the WebSocket invokes {@code onError} or {@code onClose}, then |
69 * be invoked, no matter the value of the counter. For a newly built WebSocket |
69 * no further listener's methods will be invoked, no matter the value of the |
70 * the counter is zero. A WebSocket invokes methods on the listener in a |
70 * counter. For a newly built WebSocket the counter is zero. A WebSocket invokes |
71 * thread-safe manner. |
71 * methods on the listener in a thread-safe manner. |
72 * |
72 * |
73 * <p> Unless otherwise stated, {@code null} arguments will cause methods |
73 * <p> Unless otherwise stated, {@code null} arguments will cause methods |
74 * of {@code WebSocket} to throw {@code NullPointerException}, similarly, |
74 * of {@code WebSocket} to throw {@code NullPointerException}, similarly, |
75 * {@code WebSocket} will not pass {@code null} arguments to methods of |
75 * {@code WebSocket} will not pass {@code null} arguments to methods of |
76 * {@code Listener}. The state of a WebSocket is not changed by the invocations |
76 * {@code Listener}. The state of a WebSocket is not changed by the invocations |
77 * that throw or return a {@code CompletableFuture} that completes with one of |
77 * that throw or return a {@code CompletableFuture} that completes with one of |
78 * the {@code NullPointerException}, {@code IllegalArgumentException}, |
78 * the {@code NullPointerException}, {@code IllegalArgumentException}, |
79 * {@code IllegalStateException} exceptions. |
79 * {@code IllegalStateException} exceptions. |
80 * |
80 * |
81 * <p> {@code WebSocket} handles received Ping and Close messages automatically |
81 * <p> {@code WebSocket} handles received Ping and Close messages automatically |
82 * (as per RFC 6455) by replying with Pong and Close messages. If the listener |
82 * (as per the WebSocket Protocol) by replying with Pong and Close messages. If |
83 * receives Ping or Close messages, no mandatory actions from the listener are |
83 * the listener receives Ping or Close messages, no mandatory actions from the |
84 * required. |
84 * listener are required. |
85 * |
85 * |
86 * @apiNote The relationship between a WebSocket and the associated Listener is |
86 * @apiNote The relationship between a WebSocket and the associated Listener is |
87 * analogous to that of a Subscription and the associated Subscriber of type |
87 * analogous to that of a Subscription and the associated Subscriber of type |
88 * {@link java.util.concurrent.Flow}. |
88 * {@link java.util.concurrent.Flow}. |
89 * |
89 * |
119 |
119 |
120 /** |
120 /** |
121 * Adds the given name-value pair to the list of additional HTTP headers |
121 * Adds the given name-value pair to the list of additional HTTP headers |
122 * sent during the opening handshake. |
122 * sent during the opening handshake. |
123 * |
123 * |
124 * <p> Headers defined in |
124 * <p> Headers defined in the |
125 * <a href="https://tools.ietf.org/html/rfc6455#section-11.3">WebSocket |
125 * <a href="https://tools.ietf.org/html/rfc6455#section-11.3">WebSocket |
126 * Protocol</a> are illegal. If this method is not invoked, no |
126 * Protocol</a> are illegal. If this method is not invoked, no |
127 * additional HTTP headers will be sent. |
127 * additional HTTP headers will be sent. |
128 * |
128 * |
129 * @param name |
129 * @param name |