archive/jdk
1
0
Fork 0
mirror of https://github.com/openjdk/jdk.git synced 2025-09-22 12:04:39 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

8204679: HTTP Client refresh

Browse source 
Co-authored-by: Daniel Fuchs <daniel.fuchs@oracle.com>
Co-authored-by: Michael McMahon <michael.x.mcmahon@oracle.com>
Co-authored-by: Pavel Rappo <pavel.rappo@oracle.com>
Reviewed-by: chegar, dfuchs, michaelm
This commit is contained in:
Chris Hegarty 2018-06-20 09:05:57 -07:00
parent 8c5dfa21b3
commit 659fdd8dc4
161 changed files with 8019 additions and 1853 deletions
Download patch file Download diff file Expand all files Collapse all files

76
src/java.net.http/share/classes/java/net/http/WebSocket.java
View file

@ -35,9 +35,9 @@ import java.util.concurrent.CompletionStage;
/**
* A WebSocket Client.
*
* <p> {@code WebSocket} instances can be created via {@link WebSocket.Builder}.
* <p> {@code WebSocket} instances are created through {@link WebSocket.Builder}.
*
* <p> WebSocket has an input and an output sides. These sides are independent
* <p> WebSocket has an input and an output side. These sides are independent
* from each other. A side can either be open or closed. Once closed, the side
* remains closed. WebSocket messages are sent through a {@code WebSocket} and
* received through a {@code WebSocket.Listener} associated with it. Messages
@ -55,21 +55,22 @@ import java.util.concurrent.CompletionStage;
*
* <p> A receive method is any of the {@code onText}, {@code onBinary},
* {@code onPing}, {@code onPong} and {@code onClose} methods of
* {@code Listener}. A receive method initiates a receive operation and returns
* a {@code CompletionStage} which completes once the operation has completed.
* {@code Listener}. WebSocket initiates a receive operation by invoking a
* receive method on the listener. The listener then must return a
* {@code CompletionStage} which completes once the operation has completed.
*
* <p> A WebSocket maintains an <a id="counter">internal counter</a>.
* This counter's value is a number of times the WebSocket has yet to invoke a
* receive method. While this counter is zero the WebSocket does not invoke
* receive methods. The counter is incremented by {@code n} when {@code
* request(n)} is called. The counter is decremented by one when the WebSocket
* invokes a receive method. {@code onOpen} and {@code onError} are not receive
* methods. WebSocket invokes {@code onOpen} prior to any other methods on the
* listener. WebSocket invokes {@code onOpen} at most once. WebSocket may invoke
* {@code onError} at any given time. If the WebSocket invokes {@code onError}
* or {@code onClose}, then no further listener's methods will be invoked, no
* matter the value of the counter. For a newly built WebSocket the counter is
* zero. A WebSocket invokes methods on the listener in a thread-safe manner.
* <p> To control receiving of messages, a WebSocket maintains an
* <a id="counter">internal counter</a>. This counter's value is a number of
* times the WebSocket has yet to invoke a receive method. While this counter is
* zero the WebSocket does not invoke receive methods. The counter is
* incremented by {@code n} when {@code request(n)} is called. The counter is
* decremented by one when the WebSocket invokes a receive method.
* {@code onOpen} and {@code onError} are not receive methods. WebSocket invokes
* {@code onOpen} prior to any other methods on the listener. WebSocket invokes
* {@code onOpen} at most once. WebSocket may invoke {@code onError} at any
* given time. If the WebSocket invokes {@code onError} or {@code onClose}, then
* no further listener's methods will be invoked, no matter the value of the
* counter. For a newly built WebSocket the counter is zero.
*
* <p> Unless otherwise stated, {@code null} arguments will cause methods
* of {@code WebSocket} to throw {@code NullPointerException}, similarly,
@ -105,13 +106,13 @@ public interface WebSocket {
/**
* A builder of {@linkplain WebSocket WebSocket Clients}.
*
* <p> A builder can be created by invoking the
* {@link HttpClient#newWebSocketBuilder HttpClient.newWebSocketBuilder}
* method. The intermediate (setter-like) methods change the state of the
* builder and return the same builder they have been invoked on. If an
* intermediate method is not invoked, an appropriate default value (or
* behavior) will be assumed. A {@code Builder} is not safe for use by
* multiple threads without external synchronization.
* <p> Builders are created by invoking
* {@link HttpClient#newWebSocketBuilder HttpClient.newWebSocketBuilder}.
* The intermediate (setter-like) methods change the state of the builder
* and return the same builder they have been invoked on. If an intermediate
* method is not invoked, an appropriate default value (or behavior) will be
* assumed. A {@code Builder} is not safe for use by multiple threads
* without external synchronization.
*
* @since 11
*/
@ -155,7 +156,7 @@ public interface WebSocket {
* Sets a request for the given subprotocols.
*
* <p> After the {@code WebSocket} has been built, the actual
* subprotocol can be queried via
* subprotocol can be queried through
* {@link WebSocket#getSubprotocol WebSocket.getSubprotocol()}.
*
* <p> Subprotocols are specified in the order of preference. The most
@ -218,11 +219,17 @@ public interface WebSocket {
* The receiving interface of {@code WebSocket}.
*
* <p> A {@code WebSocket} invokes methods of the associated listener
* passing itself as an argument. When data has been received, the
* {@code WebSocket} invokes a receive method. Methods {@code onText},
* {@code onBinary}, {@code onPing} and {@code onPong} must return a
* {@code CompletionStage} that completes once the message has been received
* by the listener.
* passing itself as an argument. These methods are invoked in a thread-safe
* manner, such that the next invocation may start only after the previous
* one has finished.
*
* <p> When data has been received, the {@code WebSocket} invokes a receive
* method. Methods {@code onText}, {@code onBinary}, {@code onPing} and
* {@code onPong} must return a {@code CompletionStage} that completes once
* the message has been received by the listener. If a listener's method
* returns {@code null} rather than a {@code CompletionStage},
* {@code WebSocket} will behave as if the listener returned a
* {@code CompletionStage} that is already completed normally.
*
* <p> An {@code IOException} raised in {@code WebSocket} will result in an
* invocation of {@code onError} with that exception (if the input is not
@ -231,11 +238,14 @@ public interface WebSocket {
* exceptionally, the WebSocket will invoke {@code onError} with this
* exception.
*
* <p> If a listener's method returns {@code null} rather than a
* {@code CompletionStage}, {@code WebSocket} will behave as if the listener
* returned a {@code CompletionStage} that is already completed normally.
* @apiNote The strict sequential order of invocations from
* {@code WebSocket} to {@code Listener} means, in particular, that the
* {@code Listener}'s methods are treated as non-reentrant. This means that
* {@code Listener} implementations do not need to be concerned with
* possible recursion or the order in which they invoke
* {@code WebSocket.request} in relation to their processing logic.
*
* @apiNote Careful attention may be required if a listener is associated
* <p> Careful attention may be required if a listener is associated
* with more than a single {@code WebSocket}. In this case invocations
* related to different instances of {@code WebSocket} may not be ordered
* and may even happen concurrently.