author | prappo |
Wed, 07 Mar 2018 17:16:28 +0000 | |
branch | http-client-branch |
changeset 56263 | 4933a477d628 |
parent 56156 | 336393c75a93 |
child 56318 | 2a96e88888b2 |
permissions | -rw-r--r-- |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
1 |
/* |
56055
7d387d151a3e
http-client-branch: (WebSocket) tiny spec simplification + test
prappo
parents:
56039
diff
changeset
|
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 |
|
56089
42208b2f224e
http-client-branch: move to standard package and module name
chegar
parents:
56087
diff
changeset
|
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; |
56151
eae2b2d7fe52
http-client-branch: clarify strict size requirement for received ping/pong messages
chegar
parents:
56089
diff
changeset
|
29 |
import java.net.ProtocolException; |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
30 |
import java.net.URI; |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
31 |
import java.nio.ByteBuffer; |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
32 |
import java.time.Duration; |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
33 |
import java.util.concurrent.CompletableFuture; |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
34 |
import java.util.concurrent.CompletionStage; |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
35 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
36 |
/** |
48083 | 37 |
* A WebSocket client. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
38 |
* |
48083 | 39 |
* <p> To create a {@code WebSocket} use the {@link HttpClient#newWebSocketBuilder} |
40 |
* method. To close a {@code WebSocket} use one of the {@code sendClose} or |
|
41 |
* {@code abort} methods. |
|
42 |
* |
|
43 |
* <p> WebSocket messages are sent through a {@code WebSocket} and received |
|
44 |
* through the {@code WebSocket}'s {@code Listener}. Messages can be sent until |
|
45 |
* the output is closed, and received until the input is closed. |
|
46 |
* A {@code WebSocket} whose output and input are both closed may be considered |
|
47 |
* itself closed. To check these states use {@link #isOutputClosed()} and |
|
48 |
* {@link #isInputClosed()}. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
49 |
* |
48083 | 50 |
* <p> Methods that send messages return {@code CompletableFuture} which |
51 |
* completes normally if the message is sent or completes exceptionally if an |
|
52 |
* error occurs. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
53 |
* |
48083 | 54 |
* <p> To receive a message, first request it. If {@code n} messages are |
55 |
* requested, the listener will receive up to {@code n} more invocations of the |
|
56 |
* designated methods from the {@code WebSocket}. To request messages use |
|
57 |
* {@link #request(long)}. Request is an additive operation, that is |
|
58 |
* {@code request(n)} followed by {@code request(m)} is equivalent to |
|
59 |
* {@code request(n + m)}. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
60 |
* |
48083 | 61 |
* <p> When sending or receiving a message in parts, a whole message is |
62 |
* transferred as a sequence of one or more invocations where the last |
|
63 |
* invocation is identified via an additional method argument. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
64 |
* |
48083 | 65 |
* <p> Unless otherwise stated, {@code null} arguments will cause methods |
66 |
* of {@code WebSocket} to throw {@code NullPointerException}, similarly, |
|
67 |
* {@code WebSocket} will not pass {@code null} arguments to methods of |
|
68 |
* {@code Listener}. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
69 |
* |
48083 | 70 |
* @implSpec Methods of {@code WebSocket} are failure-atomic in respect to |
71 |
* {@code NullPointerException}, {@code IllegalArgumentException} and |
|
72 |
* {@code IllegalStateException}. That is, if a method throws said exception, or |
|
73 |
* a returned {@code CompletableFuture} completes exceptionally with said |
|
74 |
* exception, the {@code WebSocket} will behave as if the method has not been |
|
75 |
* invoked at all. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
76 |
* |
48083 | 77 |
* <p> A {@code WebSocket} invokes methods of its listener in a thread-safe |
78 |
* manner. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
79 |
* |
48083 | 80 |
* <p> {@code WebSocket} handles Ping and Close messages automatically (as per |
81 |
* RFC 6455) by replying with Pong and Close messages respectively. If the |
|
82 |
* listener receives Ping or Close messages, no mandatory actions from the |
|
83 |
* listener are required. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
84 |
* |
56086 | 85 |
* @since 11 |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
86 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
87 |
public interface WebSocket { |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
88 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
89 |
/** |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
90 |
* 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
|
91 |
* 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
|
92 |
* connection was established has been fulfilled. |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
93 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
94 |
* @see #sendClose(int, String) |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
95 |
* @see Listener#onClose(WebSocket, int, String) |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
96 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
97 |
int NORMAL_CLOSURE = 1000; |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
98 |
|
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 |
* A builder for creating {@code WebSocket} instances. |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
101 |
* |
48083 | 102 |
* <p> To obtain a {@code WebSocket} configure a builder as required by |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
103 |
* calling intermediate methods (the ones that return the builder itself), |
48083 | 104 |
* then call {@code buildAsync()}. If an intermediate method is not called, |
105 |
* an appropriate default value (or behavior) will be assumed. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
106 |
* |
48083 | 107 |
* <p> Unless otherwise stated, {@code null} arguments will cause methods of |
108 |
* {@code Builder} to throw {@code NullPointerException}. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
109 |
* |
56086 | 110 |
* @since 11 |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
111 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
112 |
interface Builder { |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
113 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
114 |
/** |
48083 | 115 |
* Adds the given name-value pair to the list of additional HTTP headers |
116 |
* sent during the opening handshake. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
117 |
* |
56156
336393c75a93
http-client-branch: add link to illegal WebSocket headers
chegar
parents:
56151
diff
changeset
|
118 |
* <p> Headers defined in |
336393c75a93
http-client-branch: add link to illegal WebSocket headers
chegar
parents:
56151
diff
changeset
|
119 |
* <a href="https://tools.ietf.org/html/rfc6455#section-11.3">WebSocket |
336393c75a93
http-client-branch: add link to illegal WebSocket headers
chegar
parents:
56151
diff
changeset
|
120 |
* Protocol</a> are illegal. If this method is not invoked, no |
336393c75a93
http-client-branch: add link to illegal WebSocket headers
chegar
parents:
56151
diff
changeset
|
121 |
* 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
|
122 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
123 |
* @param name |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
124 |
* the header name |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
125 |
* @param value |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
126 |
* the header value |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
127 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
128 |
* @return this builder |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
129 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
130 |
Builder header(String name, String value); |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
131 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
132 |
/** |
48083 | 133 |
* 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
|
134 |
* |
48083 | 135 |
* <p> If the connection is not established within the specified |
136 |
* duration then building of the {@code WebSocket} will fail with |
|
137 |
* {@link HttpTimeoutException}. If this method is not invoked then the |
|
138 |
* infinite timeout is assumed. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
139 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
140 |
* @param timeout |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
141 |
* 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
|
142 |
* non-{@linkplain Duration#ZERO ZERO} |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
143 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
144 |
* @return this builder |
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 |
Builder connectTimeout(Duration timeout); |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
147 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
148 |
/** |
48083 | 149 |
* Sets a request for the given subprotocols. |
150 |
* |
|
151 |
* <p> After the {@code WebSocket} has been built, the actual |
|
152 |
* subprotocol can be queried via |
|
153 |
* {@link WebSocket#getSubprotocol WebSocket.getSubprotocol()}. |
|
154 |
* |
|
155 |
* <p> Subprotocols are specified in the order of preference. The most |
|
156 |
* preferred subprotocol is specified first. If there are any additional |
|
157 |
* subprotocols they are enumerated from the most preferred to the least |
|
158 |
* preferred. |
|
159 |
* |
|
160 |
* <p> Subprotocols not conforming to the syntax of subprotocol |
|
161 |
* identifiers are illegal. If this method is not invoked then no |
|
162 |
* subprotocols will be requested. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
163 |
* |
48083 | 164 |
* @param mostPreferred |
165 |
* the most preferred subprotocol |
|
166 |
* @param lesserPreferred |
|
167 |
* the lesser preferred subprotocols |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
168 |
* |
48083 | 169 |
* @return this builder |
170 |
*/ |
|
171 |
Builder subprotocols(String mostPreferred, String... lesserPreferred); |
|
172 |
||
173 |
/** |
|
174 |
* Builds a {@link WebSocket} connected to the given {@code URI} and |
|
175 |
* associated with the given {@code Listener}. |
|
176 |
* |
|
177 |
* <p> Returns a {@code CompletableFuture} which will either complete |
|
178 |
* normally with the resulting {@code WebSocket} or complete |
|
179 |
* 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
|
180 |
* <ul> |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
181 |
* <li> {@link IOException} - |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
182 |
* if an I/O error occurs |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
183 |
* <li> {@link WebSocketHandshakeException} - |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
184 |
* if the opening handshake fails |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
185 |
* <li> {@link HttpTimeoutException} - |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
186 |
* if the opening handshake does not complete within |
48083 | 187 |
* the timeout |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
188 |
* <li> {@link InterruptedException} - |
48083 | 189 |
* if the operation is interrupted |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
190 |
* <li> {@link SecurityException} - |
48083 | 191 |
* if a security manager has been installed and it denies |
192 |
* {@link java.net.URLPermission access} to {@code uri}. |
|
193 |
* <a href="HttpRequest.html#securitychecks">Security checks</a> |
|
194 |
* contains more information relating to the security context |
|
195 |
* 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
|
196 |
* <li> {@link IllegalArgumentException} - |
48083 | 197 |
* if any of the arguments of this builder's methods are |
198 |
* illegal |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
199 |
* </ul> |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
200 |
* |
48083 | 201 |
* @param uri |
202 |
* the WebSocket URI |
|
203 |
* @param listener |
|
204 |
* the listener |
|
205 |
* |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
206 |
* @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
|
207 |
*/ |
48083 | 208 |
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
|
209 |
} |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
210 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
211 |
/** |
48083 | 212 |
* 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
|
213 |
* |
48083 | 214 |
* <p> A {@code WebSocket} invokes methods on its listener when it receives |
215 |
* messages or encounters events. The invoking {@code WebSocket} is passed |
|
216 |
* as an argument to {@code Listener}'s methods. A {@code WebSocket} invokes |
|
217 |
* methods on its 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
|
218 |
* |
56151
eae2b2d7fe52
http-client-branch: clarify strict size requirement for received ping/pong messages
chegar
parents:
56089
diff
changeset
|
219 |
* <p> Messages received by the {@code Listener} conform to the WebSocket |
eae2b2d7fe52
http-client-branch: clarify strict size requirement for received ping/pong messages
chegar
parents:
56089
diff
changeset
|
220 |
* Protocol, otherwise {@code onError} with a {@link ProtocolException} is |
eae2b2d7fe52
http-client-branch: clarify strict size requirement for received ping/pong messages
chegar
parents:
56089
diff
changeset
|
221 |
* invoked. |
eae2b2d7fe52
http-client-branch: clarify strict size requirement for received ping/pong messages
chegar
parents:
56089
diff
changeset
|
222 |
* |
48083 | 223 |
* <p> Unless otherwise stated if a listener's method throws an exception or |
224 |
* a {@code CompletionStage} returned from a method completes exceptionally, |
|
225 |
* the {@code WebSocket} will invoke {@code onError} with this exception. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
226 |
* |
48083 | 227 |
* <p> If a listener's method returns {@code null} rather than a |
228 |
* {@code CompletionStage}, {@code WebSocket} will behave as if the listener |
|
229 |
* 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
|
230 |
* |
56086 | 231 |
* @since 11 |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
232 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
233 |
interface Listener { |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
234 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
235 |
/** |
48083 | 236 |
* 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
|
237 |
* |
48083 | 238 |
* <p> This is the first invocation and it is made at most once. This |
239 |
* method is typically used to make an initial request for messages. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
240 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
241 |
* @implSpec The default implementation of this method behaves as if: |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
242 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
243 |
* <pre>{@code |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
244 |
* webSocket.request(1); |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
245 |
* }</pre> |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
246 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
247 |
* @param webSocket |
48083 | 248 |
* 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
|
249 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
250 |
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
|
251 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
252 |
/** |
48083 | 253 |
* A Text message has been received. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
254 |
* |
48083 | 255 |
* <p> If a whole message has been received, this method will be invoked |
256 |
* with {@code MessagePart.WHOLE} marker. Otherwise, it will be invoked |
|
257 |
* with {@code FIRST}, possibly a number of times with {@code PART} and, |
|
258 |
* finally, with {@code LAST} markers. If this message is partial, it |
|
259 |
* may be an incomplete UTF-16 sequence. However, the concatenation of |
|
260 |
* all messages through the last will be a complete UTF-16 sequence. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
261 |
* |
48083 | 262 |
* <p> Return a {@code CompletionStage} which will be used by the |
263 |
* {@code WebSocket} as a signal it may reclaim the |
|
264 |
* {@code CharSequence}. Do not access the {@code CharSequence} after |
|
265 |
* this {@ode CompletionStage} has completed. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
266 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
267 |
* @implSpec The default implementation of this method behaves as if: |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
268 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
269 |
* <pre>{@code |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
270 |
* webSocket.request(1); |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
271 |
* return null; |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
272 |
* }</pre> |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
273 |
* |
48083 | 274 |
* @implNote This method is always invoked with character sequences |
275 |
* which are complete UTF-16 sequences. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
276 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
277 |
* @param webSocket |
48083 | 278 |
* 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
|
279 |
* @param message |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
280 |
* the message |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
281 |
* @param part |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
282 |
* the part |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
283 |
* |
48083 | 284 |
* @return a {@code CompletionStage} which completes when the |
285 |
* {@code CharSequence} may be reclaimed; or {@code null} if it may be |
|
286 |
* reclaimed immediately |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
287 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
288 |
default CompletionStage<?> onText(WebSocket webSocket, |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
289 |
CharSequence message, |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
290 |
MessagePart part) { |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
291 |
webSocket.request(1); |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
292 |
return null; |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
293 |
} |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
294 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
295 |
/** |
48083 | 296 |
* A Binary message has been received. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
297 |
* |
48083 | 298 |
* <p> If a whole message has been received, this method will be invoked |
299 |
* with {@code MessagePart.WHOLE} marker. Otherwise, it will be invoked |
|
300 |
* with {@code FIRST}, possibly a number of times with {@code PART} and, |
|
301 |
* finally, with {@code LAST} markers. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
302 |
* |
48083 | 303 |
* <p> This message consists of bytes from the buffer's position to |
304 |
* its limit. |
|
305 |
* |
|
306 |
* <p> Return a {@code CompletionStage} which will be used by the |
|
307 |
* {@code WebSocket} as a signal it may reclaim the |
|
308 |
* {@code ByteBuffer}. Do not access the {@code ByteBuffer} after |
|
309 |
* this {@ode CompletionStage} has completed. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
310 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
311 |
* @implSpec The default implementation of this method behaves as if: |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
312 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
313 |
* <pre>{@code |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
314 |
* webSocket.request(1); |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
315 |
* return null; |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
316 |
* }</pre> |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
317 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
318 |
* @param webSocket |
48083 | 319 |
* 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
|
320 |
* @param message |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
321 |
* the message |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
322 |
* @param part |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
323 |
* the part |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
324 |
* |
48083 | 325 |
* @return a {@code CompletionStage} which completes when the |
326 |
* {@code ByteBuffer} may be reclaimed; or {@code null} if it may be |
|
327 |
* reclaimed immediately |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
328 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
329 |
default CompletionStage<?> onBinary(WebSocket webSocket, |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
330 |
ByteBuffer message, |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
331 |
MessagePart part) { |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
332 |
webSocket.request(1); |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
333 |
return null; |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
334 |
} |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
335 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
336 |
/** |
48083 | 337 |
* 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
|
338 |
* |
56151
eae2b2d7fe52
http-client-branch: clarify strict size requirement for received ping/pong messages
chegar
parents:
56089
diff
changeset
|
339 |
* <p> As guaranteed by the WebSocket Protocol, the message consists of |
eae2b2d7fe52
http-client-branch: clarify strict size requirement for received ping/pong messages
chegar
parents:
56089
diff
changeset
|
340 |
* not more than {@code 125} bytes. These bytes are located from the |
eae2b2d7fe52
http-client-branch: clarify strict size requirement for received ping/pong messages
chegar
parents:
56089
diff
changeset
|
341 |
* 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
|
342 |
* |
48083 | 343 |
* <p> Return a {@code CompletionStage} which will be used by the |
344 |
* {@code WebSocket} as a signal it may reclaim the |
|
345 |
* {@code ByteBuffer}. Do not access the {@code ByteBuffer} after |
|
346 |
* this {@ode CompletionStage} has completed. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
347 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
348 |
* @implSpec The default implementation of this method behaves as if: |
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 |
* <pre>{@code |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
351 |
* webSocket.request(1); |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
352 |
* return null; |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
353 |
* }</pre> |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
354 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
355 |
* @param webSocket |
48083 | 356 |
* 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
|
357 |
* @param message |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
358 |
* the message |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
359 |
* |
48083 | 360 |
* @return a {@code CompletionStage} which completes when the |
361 |
* {@code ByteBuffer} may be reclaimed; or {@code null} if it may be |
|
362 |
* reclaimed immediately |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
363 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
364 |
default CompletionStage<?> onPing(WebSocket webSocket, |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
365 |
ByteBuffer message) { |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
366 |
webSocket.request(1); |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
367 |
return null; |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
368 |
} |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
369 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
370 |
/** |
48083 | 371 |
* 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
|
372 |
* |
56151
eae2b2d7fe52
http-client-branch: clarify strict size requirement for received ping/pong messages
chegar
parents:
56089
diff
changeset
|
373 |
* <p> As guaranteed by the WebSocket Protocol, the message consists of |
eae2b2d7fe52
http-client-branch: clarify strict size requirement for received ping/pong messages
chegar
parents:
56089
diff
changeset
|
374 |
* not more than {@code 125} bytes. These bytes are located from the |
eae2b2d7fe52
http-client-branch: clarify strict size requirement for received ping/pong messages
chegar
parents:
56089
diff
changeset
|
375 |
* 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
|
376 |
* |
48083 | 377 |
* <p> Return a {@code CompletionStage} which will be used by the |
378 |
* {@code WebSocket} as a signal it may reclaim the |
|
379 |
* {@code ByteBuffer}. Do not access the {@code ByteBuffer} after |
|
380 |
* this {@ode CompletionStage} has completed. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
381 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
382 |
* @implSpec The default implementation of this method behaves as if: |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
383 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
384 |
* <pre>{@code |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
385 |
* webSocket.request(1); |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
386 |
* return null; |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
387 |
* }</pre> |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
388 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
389 |
* @param webSocket |
48083 | 390 |
* 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
|
391 |
* @param message |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
392 |
* the message |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
393 |
* |
48083 | 394 |
* @return a {@code CompletionStage} which completes when the |
395 |
* {@code ByteBuffer} may be reclaimed; or {@code null} if it may be |
|
396 |
* reclaimed immediately |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
397 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
398 |
default CompletionStage<?> onPong(WebSocket webSocket, |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
399 |
ByteBuffer message) { |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
400 |
webSocket.request(1); |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
401 |
return null; |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
402 |
} |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
403 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
404 |
/** |
48083 | 405 |
* A Close message has been received. |
406 |
* |
|
407 |
* <p> This is the last invocation from the {@code WebSocket}. By the |
|
408 |
* time this invocation begins the {@code WebSocket}'s input will have |
|
409 |
* been closed. Be prepared to receive this invocation at any time after |
|
410 |
* {@code onOpen} regardless of whether or not any messages have been |
|
411 |
* requested from the {@code WebSocket}. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
412 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
413 |
* <p> A Close message consists of a status code and a reason for |
48083 | 414 |
* closing. The status code is an integer from the range |
415 |
* {@code 1000 <= code <= 65535}. The {@code reason} is a string which |
|
416 |
* has an 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
|
417 |
* |
48083 | 418 |
* <p> Return a {@code CompletionStage} that will be used by the |
419 |
* {@code WebSocket} as a signal that it may close the output. The |
|
420 |
* {@code WebSocket} will close the output at the earliest of completion |
|
421 |
* of the returned {@code CompletionStage} or invoking a |
|
422 |
* {@link WebSocket#sendClose(int, String) sendClose} method. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
423 |
* |
48083 | 424 |
* <p> If an exception is thrown from this method or a |
425 |
* {@code CompletionStage} returned from it completes exceptionally, |
|
426 |
* the resulting behaviour is undefined. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
427 |
* |
56039
01739771e48b
http-client-branch: add api/impl notes to WebSocket onClose
chegar
parents:
55973
diff
changeset
|
428 |
* @apiNote Returning a {@code CompletionStage} that never completes, |
01739771e48b
http-client-branch: add api/impl notes to WebSocket onClose
chegar
parents:
55973
diff
changeset
|
429 |
* effectively disables the automatic closure of the output. |
01739771e48b
http-client-branch: add api/impl notes to WebSocket onClose
chegar
parents:
55973
diff
changeset
|
430 |
* |
01739771e48b
http-client-branch: add api/impl notes to WebSocket onClose
chegar
parents:
55973
diff
changeset
|
431 |
* @implSpec The default implementation of this method returns |
01739771e48b
http-client-branch: add api/impl notes to WebSocket onClose
chegar
parents:
55973
diff
changeset
|
432 |
* {@code null}, signaling that the output may be closed. |
01739771e48b
http-client-branch: add api/impl notes to WebSocket onClose
chegar
parents:
55973
diff
changeset
|
433 |
* |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
434 |
* @param webSocket |
48083 | 435 |
* 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
|
436 |
* @param statusCode |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
437 |
* the status code |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
438 |
* @param reason |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
439 |
* the reason |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
440 |
* |
48083 | 441 |
* @return a {@code CompletionStage} which completes when the |
442 |
* {@code WebSocket} may be closed; or {@code null} if it may be |
|
443 |
* closed immediately |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
444 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
445 |
default CompletionStage<?> onClose(WebSocket webSocket, |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
446 |
int statusCode, |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
447 |
String reason) { |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
448 |
return null; |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
449 |
} |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
450 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
451 |
/** |
48083 | 452 |
* An unrecoverable error has occurred. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
453 |
* |
48083 | 454 |
* <p> This is the last invocation from the {@code WebSocket}. By the |
455 |
* time this invocation begins both {@code WebSocket}'s input and output |
|
456 |
* will have been closed. Be prepared to receive this invocation at any |
|
457 |
* time after {@code onOpen} regardless of whether or not any messages |
|
458 |
* have been requested from the {@code WebSocket}. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
459 |
* |
48083 | 460 |
* <p> If an exception is thrown from this method, resulting behavior is |
461 |
* undefined. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
462 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
463 |
* @param webSocket |
48083 | 464 |
* 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
|
465 |
* @param error |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
466 |
* the error |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
467 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
468 |
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
|
469 |
} |
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 |
/** |
48083 | 472 |
* A marker used by {@link WebSocket.Listener} for identifying partial |
473 |
* messages. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
474 |
* |
56086 | 475 |
* @since 11 |
42460
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 |
enum MessagePart { |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
478 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
479 |
/** |
48083 | 480 |
* The first part of a message. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
481 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
482 |
FIRST, |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
483 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
484 |
/** |
48083 | 485 |
* A middle part of a message. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
486 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
487 |
PART, |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
488 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
489 |
/** |
48083 | 490 |
* The last part of a message. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
491 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
492 |
LAST, |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
493 |
|
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 |
* A whole message consisting of a single part. |
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 |
WHOLE |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
498 |
} |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
499 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
500 |
/** |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
501 |
* Sends a Text message with characters from the given {@code CharSequence}. |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
502 |
* |
48083 | 503 |
* <p> To send a Text message invoke this method only after the previous |
504 |
* Text or Binary message has been sent. The character sequence must not be |
|
505 |
* modified until the {@code CompletableFuture} returned from this method |
|
506 |
* has completed. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
507 |
* |
48083 | 508 |
* <p> A {@code CompletableFuture} returned from this method can |
509 |
* complete exceptionally with: |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
510 |
* <ul> |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
511 |
* <li> {@link IllegalStateException} - |
56055
7d387d151a3e
http-client-branch: (WebSocket) tiny spec simplification + test
prappo
parents:
56039
diff
changeset
|
512 |
* if the previous Text or Binary message has not been sent yet |
7d387d151a3e
http-client-branch: (WebSocket) tiny spec simplification + test
prappo
parents:
56039
diff
changeset
|
513 |
* or if a previous Binary message has been sent with |
48083 | 514 |
* {@code isLast == false} |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
515 |
* <li> {@link IOException} - |
48083 | 516 |
* if an I/O error occurs |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
517 |
* </ul> |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
518 |
* |
56263 | 519 |
* @implNote If a partial or malformed UTF-16 sequence is passed to this |
520 |
* method, a {@code CompletableFuture} returned will complete exceptionally |
|
521 |
* with {@code IOException}. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
522 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
523 |
* @param message |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
524 |
* the message |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
525 |
* @param isLast |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
526 |
* {@code true} if this is the last part of the message, |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
527 |
* {@code false} otherwise |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
528 |
* |
48083 | 529 |
* @return a {@code CompletableFuture} that completes, with this |
530 |
* {@code WebSocket}, when the message has been sent |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
531 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
532 |
CompletableFuture<WebSocket> sendText(CharSequence message, boolean isLast); |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
533 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
534 |
/** |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
535 |
* Sends a Binary message with bytes from the given {@code ByteBuffer}. |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
536 |
* |
48083 | 537 |
* <p> To send a Binary message invoke this method only after the previous |
538 |
* Text or Binary message has been sent. The message consists of bytes from |
|
539 |
* the buffer's position to its limit. Upon normal completion of a |
|
540 |
* {@code CompletableFuture} returned from this method the buffer will have |
|
541 |
* 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
|
542 |
* |
48083 | 543 |
* <p> The {@code CompletableFuture} returned from this method can |
544 |
* complete exceptionally with: |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
545 |
* <ul> |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
546 |
* <li> {@link IllegalStateException} - |
56055
7d387d151a3e
http-client-branch: (WebSocket) tiny spec simplification + test
prappo
parents:
56039
diff
changeset
|
547 |
* if the previous Binary or Text message has not been sent yet |
7d387d151a3e
http-client-branch: (WebSocket) tiny spec simplification + test
prappo
parents:
56039
diff
changeset
|
548 |
* or if a previous Text message has been sent with |
48083 | 549 |
* {@code isLast == false} |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
550 |
* <li> {@link IOException} - |
48083 | 551 |
* if an I/O error occurs |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
552 |
* </ul> |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
553 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
554 |
* @param message |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
555 |
* the message |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
556 |
* @param isLast |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
557 |
* {@code true} if this is the last part of the message, |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
558 |
* {@code false} otherwise |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
559 |
* |
48083 | 560 |
* @return a {@code CompletableFuture} that completes, with this |
561 |
* {@code WebSocket}, when the message has been sent |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
562 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
563 |
CompletableFuture<WebSocket> sendBinary(ByteBuffer message, boolean isLast); |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
564 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
565 |
/** |
48083 | 566 |
* Sends a Ping message with bytes from the given {@code ByteBuffer}. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
567 |
* |
48083 | 568 |
* <p> The message consists of not more than {@code 125} bytes from the |
569 |
* buffer's position to its limit. Upon normal completion of a |
|
570 |
* {@code CompletableFuture} returned from this method the buffer will |
|
571 |
* 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
|
572 |
* |
48083 | 573 |
* <p> The {@code CompletableFuture} returned from this method can |
574 |
* complete exceptionally with: |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
575 |
* <ul> |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
576 |
* <li> {@link IllegalArgumentException} - |
48083 | 577 |
* 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
|
578 |
* <li> {@link IOException} - |
48083 | 579 |
* if an I/O error occurs |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
580 |
* </ul> |
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 |
* @param message |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
583 |
* the message |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
584 |
* |
48083 | 585 |
* @return a {@code CompletableFuture} that completes, with this |
586 |
* {@code WebSocket}, 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
|
587 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
588 |
CompletableFuture<WebSocket> sendPing(ByteBuffer message); |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
589 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
590 |
/** |
48083 | 591 |
* Sends a Pong message with bytes from the given {@code ByteBuffer}. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
592 |
* |
48083 | 593 |
* <p> The message consists of not more than {@code 125} bytes from the |
594 |
* buffer's position to its limit. Upon normal completion of a |
|
595 |
* {@code CompletableFuture} returned from this method the buffer will have |
|
596 |
* 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
|
597 |
* |
48083 | 598 |
* <p> The {@code CompletableFuture} returned from this method can |
599 |
* complete exceptionally with: |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
600 |
* <ul> |
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} - |
48083 | 604 |
* if an I/O error occurs |
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 |
* |
48083 | 610 |
* @return a {@code CompletableFuture} that completes, with this |
611 |
* {@code WebSocket}, 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 |
/** |
48083 | 616 |
* Sends a Close message with the given status code and the reason, |
617 |
* initiating an orderly closure. |
|
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 |
|
623 |
* status codes is implementation-specific. The {@code reason} is a string |
|
624 |
* that has an 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> Use the provided integer constant {@link #NORMAL_CLOSURE} as a status |
627 |
* code and an empty string as a reason in a typical case. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
628 |
* |
48083 | 629 |
* <p> A {@code CompletableFuture} returned from this method can |
630 |
* complete exceptionally with: |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
631 |
* <ul> |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
632 |
* <li> {@link IllegalArgumentException} - |
56263 | 633 |
* if {@code statusCode} is illegal |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
634 |
* <li> {@link IOException} - |
48083 | 635 |
* if an I/O error occurs |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
636 |
* </ul> |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
637 |
* |
56055
7d387d151a3e
http-client-branch: (WebSocket) tiny spec simplification + test
prappo
parents:
56039
diff
changeset
|
638 |
* <p> By the time the {@code CompletableFuture} returned from this method |
7d387d151a3e
http-client-branch: (WebSocket) tiny spec simplification + test
prappo
parents:
56039
diff
changeset
|
639 |
* completes normally, the output will have been closed. |
7d387d151a3e
http-client-branch: (WebSocket) tiny spec simplification + test
prappo
parents:
56039
diff
changeset
|
640 |
* |
48083 | 641 |
* @implSpec An endpoint sending a Close message might not receive a |
642 |
* complementing Close message in a timely manner for a variety of reasons. |
|
643 |
* The {@code WebSocket} implementation is responsible for providing a |
|
644 |
* closure mechanism that guarantees that once {@code sendClose} method has |
|
645 |
* been invoked the {@code WebSocket} will close regardless of whether or |
|
646 |
* not a Close frame has been received and without further intervention from |
|
647 |
* the user of this API. Method {@code sendClose} is designed to be, |
|
648 |
* possibly, the last call from the user of this API. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
649 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
650 |
* @param statusCode |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
651 |
* the status code |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
652 |
* @param reason |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
653 |
* the reason |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
654 |
* |
48083 | 655 |
* @return a {@code CompletableFuture} that completes, with this |
656 |
* {@code WebSocket}, 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
|
657 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
658 |
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
|
659 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
660 |
/** |
48083 | 661 |
* Requests {@code n} more messages from this {@code WebSocket}. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
662 |
* |
48083 | 663 |
* <p> This {@code WebSocket} will invoke its listener's {@code onText}, |
664 |
* {@code onBinary}, {@code onPing}, {@code onPong} or {@code onClose} |
|
665 |
* methods up to {@code n} more times. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
666 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
667 |
* @param n |
48083 | 668 |
* the number of messages requested |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
669 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
670 |
* @throws IllegalArgumentException |
48083 | 671 |
* if {@code n <= 0} |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
672 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
673 |
void request(long n); |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
674 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
675 |
/** |
48083 | 676 |
* Returns the subprotocol for this {@code WebSocket}. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
677 |
* |
48083 | 678 |
* @return the subprotocol for this {@code WebSocket}, or an empty |
679 |
* {@code 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
|
680 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
681 |
String getSubprotocol(); |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
682 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
683 |
/** |
48083 | 684 |
* Tells whether or not this {@code WebSocket} is permanently closed |
685 |
* for sending messages. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
686 |
* |
48083 | 687 |
* <p> If this method returns {@code true}, subsequent invocations will also |
56055
7d387d151a3e
http-client-branch: (WebSocket) tiny spec simplification + test
prappo
parents:
56039
diff
changeset
|
688 |
* return {@code true}. |
48083 | 689 |
* |
690 |
* @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
|
691 |
*/ |
48083 | 692 |
boolean isOutputClosed(); |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
693 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
694 |
/** |
48083 | 695 |
* Tells whether or not this {@code WebSocket} is permanently closed |
696 |
* for receiving messages. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
697 |
* |
48083 | 698 |
* <p> If this method returns {@code true}, subsequent invocations will also |
56055
7d387d151a3e
http-client-branch: (WebSocket) tiny spec simplification + test
prappo
parents:
56039
diff
changeset
|
699 |
* return {@code true}. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
700 |
* |
48083 | 701 |
* @return {@code true} if closed, {@code false} otherwise |
702 |
*/ |
|
703 |
boolean isInputClosed(); |
|
704 |
||
705 |
/** |
|
706 |
* Closes this {@code WebSocket} abruptly. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
707 |
* |
56055
7d387d151a3e
http-client-branch: (WebSocket) tiny spec simplification + test
prappo
parents:
56039
diff
changeset
|
708 |
* <p> When this method returns both the input and the output will have been |
7d387d151a3e
http-client-branch: (WebSocket) tiny spec simplification + test
prappo
parents:
56039
diff
changeset
|
709 |
* closed. Subsequent invocations will have no effect. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
710 |
* |
48083 | 711 |
* @apiNote Depending on its implementation, the state (for example, whether |
712 |
* or not a message is being transferred at the moment) and possible errors |
|
713 |
* while releasing associated resources, this {@code WebSocket} may invoke |
|
714 |
* its listener's {@code onError}. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
715 |
*/ |
48083 | 716 |
void abort(); |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
717 |
} |