author | chegar |
Tue, 17 Apr 2018 08:54:17 -0700 | |
changeset 49765 | ee6f7a61f3a5 |
parent 48083 | src/jdk.incubator.httpclient/share/classes/jdk/incubator/http/WebSocket.java@b1c1b4ef4be2 |
child 50681 | 4254bed3c09d |
child 56451 | 9585061fdb04 |
permissions | -rw-r--r-- |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
1 |
/* |
49765 | 2 |
* Copyright (c) 2015, 2018, Oracle and/or its affiliates. All rights reserved. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
3 |
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
4 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
5 |
* This code is free software; you can redistribute it and/or modify it |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
6 |
* under the terms of the GNU General Public License version 2 only, as |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
7 |
* published by the Free Software Foundation. Oracle designates this |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
8 |
* particular file as subject to the "Classpath" exception as provided |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
9 |
* by Oracle in the LICENSE file that accompanied this code. |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
10 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
11 |
* This code is distributed in the hope that it will be useful, but WITHOUT |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
12 |
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
13 |
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
14 |
* version 2 for more details (a copy is included in the LICENSE file that |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
15 |
* accompanied this code). |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
16 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
17 |
* You should have received a copy of the GNU General Public License version |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
18 |
* 2 along with this work; if not, write to the Free Software Foundation, |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
19 |
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
20 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
21 |
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
22 |
* or visit www.oracle.com if you need additional information or have any |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
23 |
* questions. |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
24 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
25 |
|
49765 | 26 |
package java.net.http; |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
27 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
28 |
import java.io.IOException; |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
29 |
import java.net.URI; |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
30 |
import java.nio.ByteBuffer; |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
31 |
import java.time.Duration; |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
32 |
import java.util.concurrent.CompletableFuture; |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
33 |
import java.util.concurrent.CompletionStage; |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
34 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
35 |
/** |
49765 | 36 |
* A WebSocket Client. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
37 |
* |
49765 | 38 |
* <p> {@code WebSocket} instances can be created via {@link WebSocket.Builder}. |
48083 | 39 |
* |
49765 | 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 |
|
42 |
* remains closed. WebSocket messages are sent through a {@code WebSocket} and |
|
43 |
* received through a {@code WebSocket.Listener} associated with it. Messages |
|
44 |
* can be sent until the WebSocket's output is closed, and received until the |
|
45 |
* WebSocket's input is closed. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
46 |
* |
49765 | 47 |
* <p> A send method is any of the {@code sendText}, {@code sendBinary}, |
48 |
* {@code sendPing}, {@code sendPong} and {@code sendClose} methods of |
|
49 |
* {@code WebSocket}. A send method initiates a send operation and returns a |
|
50 |
* {@code CompletableFuture} which completes once the operation has completed. |
|
51 |
* If the {@code CompletableFuture} completes normally the operation is |
|
52 |
* considered succeeded. If the {@code CompletableFuture} completes |
|
53 |
* exceptionally, the operation is considered failed. An operation that has been |
|
54 |
* initiated but not yet completed is considered pending. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
55 |
* |
49765 | 56 |
* <p> A receive method is any of the {@code onText}, {@code onBinary}, |
57 |
* {@code onPing}, {@code onPong} and {@code onClose} methods of |
|
58 |
* {@code Listener}. A receive method initiates a receive operation and returns |
|
59 |
* a {@code CompletionStage} which completes once the operation has completed. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
60 |
* |
49765 | 61 |
* <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 |
* 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 |
* request(n)} is called. The counter is decremented by one when the WebSocket |
|
66 |
* invokes a receive method. {@code onOpen} and {@code onError} are not receive |
|
67 |
* methods. WebSocket invokes {@code onOpen} prior to any other methods on the |
|
68 |
* listener. WebSocket invokes {@code onOpen} at most once. WebSocket may invoke |
|
69 |
* {@code onError} at any given time. If the WebSocket invokes {@code onError} |
|
70 |
* or {@code onClose}, then no further listener's methods will be invoked, no |
|
71 |
* matter the value of the counter. For a newly built WebSocket the counter is |
|
72 |
* zero. A WebSocket invokes methods on the listener in a thread-safe manner. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
73 |
* |
48083 | 74 |
* <p> Unless otherwise stated, {@code null} arguments will cause methods |
75 |
* of {@code WebSocket} to throw {@code NullPointerException}, similarly, |
|
76 |
* {@code WebSocket} will not pass {@code null} arguments to methods of |
|
49765 | 77 |
* {@code Listener}. The state of a WebSocket is not changed by the invocations |
78 |
* that throw or return a {@code CompletableFuture} that completes with one of |
|
79 |
* the {@code NullPointerException}, {@code IllegalArgumentException}, |
|
80 |
* {@code IllegalStateException} exceptions. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
81 |
* |
49765 | 82 |
* <p> {@code WebSocket} handles received Ping and Close messages automatically |
83 |
* (as per the WebSocket Protocol) by replying with Pong and Close messages. If |
|
84 |
* the listener receives Ping or Close messages, no mandatory actions from the |
|
48083 | 85 |
* listener are required. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
86 |
* |
49765 | 87 |
* @apiNote The relationship between a WebSocket and the associated Listener is |
88 |
* analogous to that of a Subscription and the associated Subscriber of type |
|
89 |
* {@link java.util.concurrent.Flow}. |
|
90 |
* |
|
91 |
* @since 11 |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
92 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
93 |
public interface WebSocket { |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
94 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
95 |
/** |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
96 |
* The WebSocket Close message status code (<code>{@value}</code>), |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
97 |
* indicating normal closure, meaning that the purpose for which the |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
98 |
* connection was established has been fulfilled. |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
99 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
100 |
* @see #sendClose(int, String) |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
101 |
* @see Listener#onClose(WebSocket, int, String) |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
102 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
103 |
int NORMAL_CLOSURE = 1000; |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
104 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
105 |
/** |
49765 | 106 |
* A builder of {@linkplain WebSocket WebSocket Clients}. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
107 |
* |
49765 | 108 |
* <p> A builder can be created by invoking the |
109 |
* {@link HttpClient#newWebSocketBuilder HttpClient.newWebSocketBuilder} |
|
110 |
* method. The intermediate (setter-like) methods change the state of the |
|
111 |
* builder and return the same builder they have been invoked on. If an |
|
112 |
* intermediate method is not invoked, an appropriate default value (or |
|
113 |
* behavior) will be assumed. A {@code Builder} is not safe for use by |
|
114 |
* multiple threads without external synchronization. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
115 |
* |
49765 | 116 |
* @since 11 |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
117 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
118 |
interface Builder { |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
119 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
120 |
/** |
48083 | 121 |
* Adds the given name-value pair to the list of additional HTTP headers |
122 |
* sent during the opening handshake. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
123 |
* |
49765 | 124 |
* <p> Headers defined in the |
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 |
|
127 |
* additional HTTP headers will be sent. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
128 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
129 |
* @param name |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
130 |
* the header name |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
131 |
* @param value |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
132 |
* the header value |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
133 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
134 |
* @return this builder |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
135 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
136 |
Builder header(String name, String value); |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
137 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
138 |
/** |
48083 | 139 |
* Sets a timeout for establishing a WebSocket connection. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
140 |
* |
48083 | 141 |
* <p> If the connection is not established within the specified |
142 |
* duration then building of the {@code WebSocket} will fail with |
|
143 |
* {@link HttpTimeoutException}. If this method is not invoked then the |
|
144 |
* infinite timeout is assumed. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
145 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
146 |
* @param timeout |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
147 |
* the timeout, non-{@linkplain Duration#isNegative() negative}, |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
148 |
* non-{@linkplain Duration#ZERO ZERO} |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
149 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
150 |
* @return this builder |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
151 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
152 |
Builder connectTimeout(Duration timeout); |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
153 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
154 |
/** |
48083 | 155 |
* Sets a request for the given subprotocols. |
156 |
* |
|
157 |
* <p> After the {@code WebSocket} has been built, the actual |
|
158 |
* subprotocol can be queried via |
|
159 |
* {@link WebSocket#getSubprotocol WebSocket.getSubprotocol()}. |
|
160 |
* |
|
161 |
* <p> Subprotocols are specified in the order of preference. The most |
|
162 |
* preferred subprotocol is specified first. If there are any additional |
|
163 |
* subprotocols they are enumerated from the most preferred to the least |
|
164 |
* preferred. |
|
165 |
* |
|
166 |
* <p> Subprotocols not conforming to the syntax of subprotocol |
|
167 |
* identifiers are illegal. If this method is not invoked then no |
|
168 |
* subprotocols will be requested. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
169 |
* |
48083 | 170 |
* @param mostPreferred |
171 |
* the most preferred subprotocol |
|
172 |
* @param lesserPreferred |
|
173 |
* the lesser preferred subprotocols |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
174 |
* |
48083 | 175 |
* @return this builder |
176 |
*/ |
|
177 |
Builder subprotocols(String mostPreferred, String... lesserPreferred); |
|
178 |
||
179 |
/** |
|
180 |
* Builds a {@link WebSocket} connected to the given {@code URI} and |
|
181 |
* associated with the given {@code Listener}. |
|
182 |
* |
|
183 |
* <p> Returns a {@code CompletableFuture} which will either complete |
|
184 |
* normally with the resulting {@code WebSocket} or complete |
|
185 |
* exceptionally with one of the following errors: |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
186 |
* <ul> |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
187 |
* <li> {@link IOException} - |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
188 |
* if an I/O error occurs |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
189 |
* <li> {@link WebSocketHandshakeException} - |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
190 |
* if the opening handshake fails |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
191 |
* <li> {@link HttpTimeoutException} - |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
192 |
* if the opening handshake does not complete within |
48083 | 193 |
* the timeout |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
194 |
* <li> {@link InterruptedException} - |
48083 | 195 |
* if the operation is interrupted |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
196 |
* <li> {@link SecurityException} - |
48083 | 197 |
* if a security manager has been installed and it denies |
198 |
* {@link java.net.URLPermission access} to {@code uri}. |
|
199 |
* <a href="HttpRequest.html#securitychecks">Security checks</a> |
|
200 |
* contains more information relating to the security context |
|
201 |
* in which the the listener is invoked. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
202 |
* <li> {@link IllegalArgumentException} - |
48083 | 203 |
* if any of the arguments of this builder's methods are |
204 |
* illegal |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
205 |
* </ul> |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
206 |
* |
48083 | 207 |
* @param uri |
208 |
* the WebSocket URI |
|
209 |
* @param listener |
|
210 |
* the listener |
|
211 |
* |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
212 |
* @return a {@code CompletableFuture} with the {@code WebSocket} |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
213 |
*/ |
48083 | 214 |
CompletableFuture<WebSocket> buildAsync(URI uri, Listener listener); |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
215 |
} |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
216 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
217 |
/** |
48083 | 218 |
* The receiving interface of {@code WebSocket}. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
219 |
* |
49765 | 220 |
* <p> A {@code WebSocket} invokes methods of the associated listener |
221 |
* passing itself as an argument. When data has been received, the |
|
222 |
* {@code WebSocket} invokes a receive method. Methods {@code onText}, |
|
223 |
* {@code onBinary}, {@code onPing} and {@code onPong} must return a |
|
224 |
* {@code CompletionStage} that completes once the message has been received |
|
225 |
* by the listener. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
226 |
* |
49765 | 227 |
* <p> An {@code IOException} raised in {@code WebSocket} will result in an |
228 |
* invocation of {@code onError} with that exception (if the input is not |
|
229 |
* closed). Unless otherwise stated if the listener's method throws an |
|
230 |
* exception or a {@code CompletionStage} returned from a method completes |
|
231 |
* exceptionally, the WebSocket will invoke {@code onError} with this |
|
232 |
* exception. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
233 |
* |
48083 | 234 |
* <p> If a listener's method returns {@code null} rather than a |
235 |
* {@code CompletionStage}, {@code WebSocket} will behave as if the listener |
|
236 |
* returned a {@code CompletionStage} that is already completed normally. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
237 |
* |
49765 | 238 |
* @apiNote Careful attention may be required if a listener is associated |
239 |
* with more than a single {@code WebSocket}. In this case invocations |
|
240 |
* related to different instances of {@code WebSocket} may not be ordered |
|
241 |
* and may even happen concurrently. |
|
242 |
* |
|
243 |
* <p> {@code CompletionStage}s returned from the receive methods have |
|
244 |
* nothing to do with the |
|
245 |
* <a href="WebSocket.html#counter">counter of invocations</a>. |
|
246 |
* Namely, a {@code CompletionStage} does not have to be completed in order |
|
247 |
* to receive more invocations of the listener's methods. |
|
248 |
* Here is an example of a listener that requests invocations, one at a |
|
249 |
* time, until a complete message has been accumulated, then processes |
|
250 |
* the result, and completes the {@code CompletionStage}: |
|
251 |
* <pre>{@code WebSocket.Listener listener = new WebSocket.Listener() { |
|
252 |
* |
|
253 |
* List<CharSequence> parts = new ArrayList<>(); |
|
254 |
* CompletableFuture<?> accumulatedMessage = new CompletableFuture<>(); |
|
255 |
* |
|
256 |
* public CompletionStage<?> onText(WebSocket webSocket, |
|
257 |
* CharSequence message, |
|
258 |
* boolean last) { |
|
259 |
* parts.add(message); |
|
260 |
* webSocket.request(1); |
|
261 |
* if (last) { |
|
262 |
* processWholeText(parts); |
|
263 |
* parts = new ArrayList<>(); |
|
264 |
* accumulatedMessage.complete(null); |
|
265 |
* CompletionStage<?> cf = accumulatedMessage; |
|
266 |
* accumulatedMessage = new CompletableFuture<>(); |
|
267 |
* return cf; |
|
268 |
* } |
|
269 |
* return accumulatedMessage; |
|
270 |
* } |
|
271 |
* ... |
|
272 |
* } } </pre> |
|
273 |
* |
|
274 |
* @since 11 |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
275 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
276 |
interface Listener { |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
277 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
278 |
/** |
48083 | 279 |
* A {@code WebSocket} has been connected. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
280 |
* |
49765 | 281 |
* <p> This is the initial invocation and it is made once. It is |
282 |
* typically used to make a request for more invocations. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
283 |
* |
49765 | 284 |
* @implSpec The default implementation is equivalent to: |
285 |
* <pre>{@code webSocket.request(1); }</pre> |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
286 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
287 |
* @param webSocket |
48083 | 288 |
* the WebSocket that has been connected |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
289 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
290 |
default void onOpen(WebSocket webSocket) { webSocket.request(1); } |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
291 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
292 |
/** |
49765 | 293 |
* A textual data has been received. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
294 |
* |
48083 | 295 |
* <p> Return a {@code CompletionStage} which will be used by the |
49765 | 296 |
* {@code WebSocket} as an indication it may reclaim the |
48083 | 297 |
* {@code CharSequence}. Do not access the {@code CharSequence} after |
49765 | 298 |
* this {@code CompletionStage} has completed. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
299 |
* |
49765 | 300 |
* @implSpec The default implementation is equivalent to: |
301 |
* <pre>{@code webSocket.request(1); |
|
302 |
* return null; }</pre> |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
303 |
* |
49765 | 304 |
* @implNote The {@code data} is always a legal UTF-16 sequence. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
305 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
306 |
* @param webSocket |
49765 | 307 |
* the WebSocket on which the data has been received |
308 |
* @param data |
|
309 |
* the data |
|
310 |
* @param last |
|
311 |
* whether this invocation completes the message |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
312 |
* |
48083 | 313 |
* @return a {@code CompletionStage} which completes when the |
314 |
* {@code CharSequence} may be reclaimed; or {@code null} if it may be |
|
315 |
* reclaimed immediately |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
316 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
317 |
default CompletionStage<?> onText(WebSocket webSocket, |
49765 | 318 |
CharSequence data, |
319 |
boolean last) { |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
320 |
webSocket.request(1); |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
321 |
return null; |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
322 |
} |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
323 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
324 |
/** |
49765 | 325 |
* A binary data has been received. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
326 |
* |
49765 | 327 |
* <p> This data is located in bytes from the buffer's position to its |
328 |
* limit. |
|
48083 | 329 |
* |
330 |
* <p> Return a {@code CompletionStage} which will be used by the |
|
49765 | 331 |
* {@code WebSocket} as an indication it may reclaim the |
48083 | 332 |
* {@code ByteBuffer}. Do not access the {@code ByteBuffer} after |
49765 | 333 |
* this {@code CompletionStage} has completed. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
334 |
* |
49765 | 335 |
* @implSpec The default implementation is equivalent to: |
336 |
* <pre>{@code webSocket.request(1); |
|
337 |
* return null; }</pre> |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
338 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
339 |
* @param webSocket |
49765 | 340 |
* the WebSocket on which the data has been received |
341 |
* @param data |
|
342 |
* the data |
|
343 |
* @param last |
|
344 |
* whether this invocation completes the message |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
345 |
* |
48083 | 346 |
* @return a {@code CompletionStage} which completes when the |
347 |
* {@code ByteBuffer} may be reclaimed; or {@code null} if it may be |
|
348 |
* reclaimed immediately |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
349 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
350 |
default CompletionStage<?> onBinary(WebSocket webSocket, |
49765 | 351 |
ByteBuffer data, |
352 |
boolean last) { |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
353 |
webSocket.request(1); |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
354 |
return null; |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
355 |
} |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
356 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
357 |
/** |
48083 | 358 |
* A Ping message has been received. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
359 |
* |
49765 | 360 |
* <p> As guaranteed by the WebSocket Protocol, the message consists of |
361 |
* not more than {@code 125} bytes. These bytes are located from the |
|
362 |
* buffer's position to its limit. |
|
363 |
* |
|
364 |
* <p> Given that the WebSocket implementation will automatically send a |
|
365 |
* reciprocal pong when a ping is received, it is rarely required to |
|
366 |
* send a pong message explicitly when a ping is received. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
367 |
* |
48083 | 368 |
* <p> Return a {@code CompletionStage} which will be used by the |
369 |
* {@code WebSocket} as a signal it may reclaim the |
|
370 |
* {@code ByteBuffer}. Do not access the {@code ByteBuffer} after |
|
49765 | 371 |
* this {@code CompletionStage} has completed. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
372 |
* |
49765 | 373 |
* @implSpec The default implementation is equivalent to: |
374 |
* <pre>{@code webSocket.request(1); |
|
375 |
* return null; }</pre> |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
376 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
377 |
* @param webSocket |
48083 | 378 |
* the WebSocket on which the message has been received |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
379 |
* @param message |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
380 |
* the message |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
381 |
* |
48083 | 382 |
* @return a {@code CompletionStage} which completes when the |
383 |
* {@code ByteBuffer} may be reclaimed; or {@code null} if it may be |
|
384 |
* reclaimed immediately |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
385 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
386 |
default CompletionStage<?> onPing(WebSocket webSocket, |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
387 |
ByteBuffer message) { |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
388 |
webSocket.request(1); |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
389 |
return null; |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
390 |
} |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
391 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
392 |
/** |
48083 | 393 |
* A Pong message has been received. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
394 |
* |
49765 | 395 |
* <p> As guaranteed by the WebSocket Protocol, the message consists of |
396 |
* not more than {@code 125} bytes. These bytes are located from the |
|
397 |
* buffer's position to its limit. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
398 |
* |
48083 | 399 |
* <p> Return a {@code CompletionStage} which will be used by the |
400 |
* {@code WebSocket} as a signal it may reclaim the |
|
401 |
* {@code ByteBuffer}. Do not access the {@code ByteBuffer} after |
|
49765 | 402 |
* this {@code CompletionStage} has completed. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
403 |
* |
49765 | 404 |
* @implSpec The default implementation is equivalent to: |
405 |
* <pre>{@code webSocket.request(1); |
|
406 |
* return null; }</pre> |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
407 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
408 |
* @param webSocket |
48083 | 409 |
* the WebSocket on which the message has been received |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
410 |
* @param message |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
411 |
* the message |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
412 |
* |
48083 | 413 |
* @return a {@code CompletionStage} which completes when the |
414 |
* {@code ByteBuffer} may be reclaimed; or {@code null} if it may be |
|
415 |
* reclaimed immediately |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
416 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
417 |
default CompletionStage<?> onPong(WebSocket webSocket, |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
418 |
ByteBuffer message) { |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
419 |
webSocket.request(1); |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
420 |
return null; |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
421 |
} |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
422 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
423 |
/** |
49765 | 424 |
* Receives a Close message indicating the WebSocket's input has been |
425 |
* closed. |
|
48083 | 426 |
* |
49765 | 427 |
* <p> This is the last invocation from the specified {@code WebSocket}. |
428 |
* By the time this invocation begins the WebSocket's input will have |
|
429 |
* been closed. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
430 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
431 |
* <p> A Close message consists of a status code and a reason for |
48083 | 432 |
* closing. The status code is an integer from the range |
433 |
* {@code 1000 <= code <= 65535}. The {@code reason} is a string which |
|
49765 | 434 |
* has a UTF-8 representation not longer than {@code 123} bytes. |
435 |
* |
|
436 |
* <p> If the WebSocket's output is not already closed, the |
|
437 |
* {@code CompletionStage} returned by this method will be used as an |
|
438 |
* indication that the WebSocket's output may be closed. The WebSocket |
|
439 |
* will close its output at the earliest of completion of the returned |
|
440 |
* {@code CompletionStage} or invoking either of the {@code sendClose} |
|
441 |
* or {@code abort} methods. |
|
442 |
* |
|
443 |
* @apiNote Returning a {@code CompletionStage} that never completes, |
|
444 |
* effectively disables the reciprocating closure of the output. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
445 |
* |
49765 | 446 |
* <p> To specify a custom closure code or reason code the |
447 |
* {@code sendClose} method may be invoked from inside the |
|
448 |
* {@code onClose} invocation: |
|
449 |
* <pre>{@code public CompletionStage<?> onClose(WebSocket webSocket, |
|
450 |
* int statusCode, |
|
451 |
* String reason) { |
|
452 |
* webSocket.sendClose(CUSTOM_STATUS_CODE, CUSTOM_REASON); |
|
453 |
* return new CompletableFuture<Void>(); |
|
454 |
* } } </pre> |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
455 |
* |
49765 | 456 |
* @implSpec The default implementation of this method returns |
457 |
* {@code null}, indicating that the output should be closed |
|
458 |
* immediately. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
459 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
460 |
* @param webSocket |
48083 | 461 |
* the WebSocket on which the message has been received |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
462 |
* @param statusCode |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
463 |
* the status code |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
464 |
* @param reason |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
465 |
* the reason |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
466 |
* |
48083 | 467 |
* @return a {@code CompletionStage} which completes when the |
468 |
* {@code WebSocket} may be closed; or {@code null} if it may be |
|
469 |
* closed immediately |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
470 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
471 |
default CompletionStage<?> onClose(WebSocket webSocket, |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
472 |
int statusCode, |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
473 |
String reason) { |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
474 |
return null; |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
475 |
} |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
476 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
477 |
/** |
49765 | 478 |
* An error has occurred. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
479 |
* |
49765 | 480 |
* <p> This is the last invocation from the specified WebSocket. By the |
481 |
* time this invocation begins both the WebSocket's input and output |
|
482 |
* will have been closed. A WebSocket may invoke this method on the |
|
483 |
* associated listener at any time after it has invoked {@code onOpen}, |
|
484 |
* regardless of whether or not any invocations have been requested from |
|
485 |
* the WebSocket. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
486 |
* |
48083 | 487 |
* <p> If an exception is thrown from this method, resulting behavior is |
488 |
* undefined. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
489 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
490 |
* @param webSocket |
48083 | 491 |
* the WebSocket on which the error has occurred |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
492 |
* @param error |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
493 |
* the error |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
494 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
495 |
default void onError(WebSocket webSocket, Throwable error) { } |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
496 |
} |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
497 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
498 |
/** |
49765 | 499 |
* Sends textual data with characters from the given character sequence. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
500 |
* |
49765 | 501 |
* <p> The character sequence must not be modified until the |
502 |
* {@code CompletableFuture} returned from this method has completed. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
503 |
* |
48083 | 504 |
* <p> A {@code CompletableFuture} returned from this method can |
505 |
* complete exceptionally with: |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
506 |
* <ul> |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
507 |
* <li> {@link IllegalStateException} - |
49765 | 508 |
* if there is a pending text or binary send operation |
509 |
* or if the previous binary data does not complete the message |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
510 |
* <li> {@link IOException} - |
49765 | 511 |
* if an I/O error occurs, or if the output is closed |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
512 |
* </ul> |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
513 |
* |
49765 | 514 |
* @implNote If {@code data} is a malformed UTF-16 sequence, the operation |
515 |
* will fail with {@code IOException}. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
516 |
* |
49765 | 517 |
* @param data |
518 |
* the data |
|
519 |
* @param last |
|
520 |
* {@code true} if this invocation completes the message, |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
521 |
* {@code false} otherwise |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
522 |
* |
49765 | 523 |
* @return a {@code CompletableFuture} that completes, with this WebSocket, |
524 |
* when the data has been sent |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
525 |
*/ |
49765 | 526 |
CompletableFuture<WebSocket> sendText(CharSequence data, boolean last); |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
527 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
528 |
/** |
49765 | 529 |
* Sends binary data with bytes from the given buffer. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
530 |
* |
49765 | 531 |
* <p> The data is located in bytes from the buffer's position to its limit. |
532 |
* Upon normal completion of a {@code CompletableFuture} returned from this |
|
533 |
* method the buffer will have no remaining bytes. The buffer must not be |
|
534 |
* accessed until after that. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
535 |
* |
48083 | 536 |
* <p> The {@code CompletableFuture} returned from this method can |
537 |
* complete exceptionally with: |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
538 |
* <ul> |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
539 |
* <li> {@link IllegalStateException} - |
49765 | 540 |
* if there is a pending text or binary send operation |
541 |
* or if the previous textual data does not complete the message |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
542 |
* <li> {@link IOException} - |
49765 | 543 |
* if an I/O error occurs, or if the output is closed |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
544 |
* </ul> |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
545 |
* |
49765 | 546 |
* @param data |
547 |
* the data |
|
548 |
* @param last |
|
549 |
* {@code true} if this invocation completes the message, |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
550 |
* {@code false} otherwise |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
551 |
* |
49765 | 552 |
* @return a {@code CompletableFuture} that completes, with this WebSocket, |
553 |
* when the data has been sent |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
554 |
*/ |
49765 | 555 |
CompletableFuture<WebSocket> sendBinary(ByteBuffer data, boolean last); |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
556 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
557 |
/** |
49765 | 558 |
* Sends a Ping message with bytes from the given buffer. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
559 |
* |
48083 | 560 |
* <p> The message consists of not more than {@code 125} bytes from the |
561 |
* buffer's position to its limit. Upon normal completion of a |
|
562 |
* {@code CompletableFuture} returned from this method the buffer will |
|
563 |
* have no remaining bytes. The buffer must not be accessed until after that. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
564 |
* |
48083 | 565 |
* <p> The {@code CompletableFuture} returned from this method can |
566 |
* complete exceptionally with: |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
567 |
* <ul> |
49765 | 568 |
* <li> {@link IllegalStateException} - |
569 |
* if there is a pending ping or pong send operation |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
570 |
* <li> {@link IllegalArgumentException} - |
48083 | 571 |
* if the message is too long |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
572 |
* <li> {@link IOException} - |
49765 | 573 |
* if an I/O error occurs, or if the output is closed |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
574 |
* </ul> |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
575 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
576 |
* @param message |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
577 |
* the message |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
578 |
* |
49765 | 579 |
* @return a {@code CompletableFuture} that completes, with this WebSocket, |
580 |
* when the Ping message has been sent |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
581 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
582 |
CompletableFuture<WebSocket> sendPing(ByteBuffer message); |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
583 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
584 |
/** |
49765 | 585 |
* Sends a Pong message with bytes from the given buffer. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
586 |
* |
48083 | 587 |
* <p> The message consists of not more than {@code 125} bytes from the |
588 |
* buffer's position to its limit. Upon normal completion of a |
|
589 |
* {@code CompletableFuture} returned from this method the buffer will have |
|
590 |
* no remaining bytes. The buffer must not be accessed until after that. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
591 |
* |
49765 | 592 |
* <p> Given that the WebSocket implementation will automatically send a |
593 |
* reciprocal pong when a ping is received, it is rarely required to send a |
|
594 |
* pong message explicitly. |
|
595 |
* |
|
48083 | 596 |
* <p> The {@code CompletableFuture} returned from this method can |
597 |
* complete exceptionally with: |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
598 |
* <ul> |
49765 | 599 |
* <li> {@link IllegalStateException} - |
600 |
* if there is a pending ping or pong send operation |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
601 |
* <li> {@link IllegalArgumentException} - |
48083 | 602 |
* if the message is too long |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
603 |
* <li> {@link IOException} - |
49765 | 604 |
* if an I/O error occurs, or if the output is closed |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
605 |
* </ul> |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
606 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
607 |
* @param message |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
608 |
* the message |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
609 |
* |
49765 | 610 |
* @return a {@code CompletableFuture} that completes, with this WebSocket, |
611 |
* when the Pong message has been sent |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
612 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
613 |
CompletableFuture<WebSocket> sendPong(ByteBuffer message); |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
614 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
615 |
/** |
49765 | 616 |
* Initiates an orderly closure of this WebSocket's output by |
617 |
* sending a Close message with the given status code and the reason. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
618 |
* |
48083 | 619 |
* <p> The {@code statusCode} is an integer from the range |
620 |
* {@code 1000 <= code <= 4999}. Status codes {@code 1002}, {@code 1003}, |
|
621 |
* {@code 1006}, {@code 1007}, {@code 1009}, {@code 1010}, {@code 1012}, |
|
622 |
* {@code 1013} and {@code 1015} are illegal. Behaviour in respect to other |
|
49765 | 623 |
* status codes is implementation-specific. A legal {@code reason} is a |
624 |
* string that has a UTF-8 representation not longer than {@code 123} bytes. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
625 |
* |
48083 | 626 |
* <p> A {@code CompletableFuture} returned from this method can |
627 |
* complete exceptionally with: |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
628 |
* <ul> |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
629 |
* <li> {@link IllegalArgumentException} - |
49765 | 630 |
* if {@code statusCode} is illegal, or |
631 |
* if {@code reason} is illegal |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
632 |
* <li> {@link IOException} - |
49765 | 633 |
* if an I/O error occurs, or if the output is closed |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
634 |
* </ul> |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
635 |
* |
49765 | 636 |
* <p> Unless the {@code CompletableFuture} returned from this method |
637 |
* completes with {@code IllegalArgumentException}, or the method throws |
|
638 |
* {@code NullPointerException}, the output will be closed. |
|
639 |
* |
|
640 |
* <p> If not already closed, the input remains open until a Close message |
|
641 |
* {@linkplain Listener#onClose(WebSocket, int, String) received}, or |
|
642 |
* {@code abort} is invoked, or an |
|
643 |
* {@linkplain Listener#onError(WebSocket, Throwable) error} occurs. |
|
644 |
* |
|
645 |
* @apiNote Use the provided integer constant {@link #NORMAL_CLOSURE} as a |
|
646 |
* status code and an empty string as a reason in a typical case: |
|
647 |
* <pre>{@code CompletableFuture<WebSocket> webSocket = ... |
|
648 |
* webSocket.thenCompose(ws -> ws.sendText("Hello, ", false)) |
|
649 |
* .thenCompose(ws -> ws.sendText("world!", true)) |
|
650 |
* .thenCompose(ws -> ws.sendClose(WebSocket.NORMAL_CLOSURE, "")) |
|
651 |
* .join(); }</pre> |
|
652 |
* |
|
653 |
* The {@code sendClose} method does not close this WebSocket's input. It |
|
654 |
* merely closes this WebSocket's output by sending a Close message. To |
|
655 |
* enforce closing the input, invoke the {@code abort} method. Here is an |
|
656 |
* example of an application that sends a Close message, and then starts a |
|
657 |
* timer. Once no data has been received within the specified timeout, the |
|
658 |
* timer goes off and the alarm aborts {@code WebSocket}: |
|
659 |
* <pre>{@code MyAlarm alarm = new MyAlarm(webSocket::abort); |
|
660 |
* WebSocket.Listener listener = new WebSocket.Listener() { |
|
661 |
* |
|
662 |
* public CompletionStage<?> onText(WebSocket webSocket, |
|
663 |
* CharSequence data, |
|
664 |
* boolean last) { |
|
665 |
* alarm.snooze(); |
|
666 |
* ... |
|
667 |
* } |
|
668 |
* ... |
|
669 |
* }; |
|
670 |
* ... |
|
671 |
* Runnable startTimer = () -> { |
|
672 |
* MyTimer idleTimer = new MyTimer(); |
|
673 |
* idleTimer.add(alarm, 30, TimeUnit.SECONDS); |
|
674 |
* }; |
|
675 |
* webSocket.sendClose(WebSocket.NORMAL_CLOSURE, "ok").thenRun(startTimer); |
|
676 |
* } </pre> |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
677 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
678 |
* @param statusCode |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
679 |
* the status code |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
680 |
* @param reason |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
681 |
* the reason |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
682 |
* |
49765 | 683 |
* @return a {@code CompletableFuture} that completes, with this WebSocket, |
684 |
* when the Close message has been sent |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
685 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
686 |
CompletableFuture<WebSocket> sendClose(int statusCode, String reason); |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
687 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
688 |
/** |
49765 | 689 |
* Increments the counter of invocations of receive methods. |
690 |
* |
|
691 |
* <p> This WebSocket will invoke {@code onText}, {@code onBinary}, |
|
692 |
* {@code onPing}, {@code onPong} or {@code onClose} methods on the |
|
693 |
* associated listener (i.e. receive methods) up to {@code n} more times. |
|
694 |
* |
|
695 |
* @apiNote The parameter of this method is the number of invocations being |
|
696 |
* requested from this WebSocket to the associated listener, not the number |
|
697 |
* of messages. Sometimes a message may be delivered to the listener in a |
|
698 |
* single invocation, but not always. For example, Ping, Pong and Close |
|
699 |
* messages are delivered in a single invocation of {@code onPing}, |
|
700 |
* {@code onPong} and {@code onClose} methods respectively. However, whether |
|
701 |
* or not Text and Binary messages are delivered in a single invocation of |
|
702 |
* {@code onText} and {@code onBinary} methods depends on the boolean |
|
703 |
* argument ({@code last}) of these methods. If {@code last} is |
|
704 |
* {@code false}, then there is more to a message than has been delivered to |
|
705 |
* the invocation. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
706 |
* |
49765 | 707 |
* <p> Here is an example of a listener that requests invocations, one at a |
708 |
* time, until a complete message has been accumulated, and then processes |
|
709 |
* the result: |
|
710 |
* <pre>{@code WebSocket.Listener listener = new WebSocket.Listener() { |
|
711 |
* |
|
712 |
* StringBuilder text = new StringBuilder(); |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
713 |
* |
49765 | 714 |
* public CompletionStage<?> onText(WebSocket webSocket, |
715 |
* CharSequence message, |
|
716 |
* boolean last) { |
|
717 |
* text.append(message); |
|
718 |
* if (last) { |
|
719 |
* processCompleteTextMessage(text); |
|
720 |
* text = new StringBuilder(); |
|
721 |
* } |
|
722 |
* webSocket.request(1); |
|
723 |
* return null; |
|
724 |
* } |
|
725 |
* ... |
|
726 |
* } } </pre> |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
727 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
728 |
* @param n |
49765 | 729 |
* the number of invocations |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
730 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
731 |
* @throws IllegalArgumentException |
48083 | 732 |
* if {@code n <= 0} |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
733 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
734 |
void request(long n); |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
735 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
736 |
/** |
49765 | 737 |
* Returns the subprotocol used by this WebSocket. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
738 |
* |
49765 | 739 |
* @return the subprotocol, or an empty string if there's no subprotocol |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
740 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
741 |
String getSubprotocol(); |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
742 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
743 |
/** |
49765 | 744 |
* Tells whether this WebSocket's output is closed. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
745 |
* |
48083 | 746 |
* <p> If this method returns {@code true}, subsequent invocations will also |
49765 | 747 |
* return {@code true}. |
48083 | 748 |
* |
749 |
* @return {@code true} if closed, {@code false} otherwise |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
750 |
*/ |
48083 | 751 |
boolean isOutputClosed(); |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
752 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
753 |
/** |
49765 | 754 |
* Tells whether this WebSocket's input is closed. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
755 |
* |
48083 | 756 |
* <p> If this method returns {@code true}, subsequent invocations will also |
49765 | 757 |
* return {@code true}. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
758 |
* |
48083 | 759 |
* @return {@code true} if closed, {@code false} otherwise |
760 |
*/ |
|
761 |
boolean isInputClosed(); |
|
762 |
||
763 |
/** |
|
49765 | 764 |
* Closes this WebSocket's input and output abruptly. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
765 |
* |
49765 | 766 |
* <p> When this method returns both the input and the output will have been |
767 |
* closed. Any pending send operations will fail with {@code IOException}. |
|
768 |
* Subsequent invocations of {@code abort} will have no effect. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
769 |
*/ |
48083 | 770 |
void abort(); |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
771 |
} |