jdk-sandbox: comparison src/jdk.incubator.httpclient/share/classes/jdk/incubator/http/HttpRequest.java

equal deleted inserted replaced

-:89829dd3cc54
+:b1c1b4ef4be2
 package jdk.incubator.http;
 import java.io.FileNotFoundException;
 import java.io.InputStream;
 import java.net.URI;
+import java.net.URLPermission;
 import java.nio.ByteBuffer;
-import java.nio.charset.*;
+import java.nio.charset.Charset;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
 import java.nio.file.Path;
+import java.security.AccessController;
+import java.security.PrivilegedAction;
 import java.time.Duration;
 import java.util.Iterator;
+import java.util.Objects;
 import java.util.Optional;
 import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.Executor;
 import java.util.concurrent.Flow;
 import java.util.function.Supplier;
+import static java.nio.charset.StandardCharsets.UTF_8;
 /**
 * Represents one HTTP request which can be sent to a server.
 * {@Incubating }
 *
-* <p> {@code HttpRequest}s are built from {@code HttpRequest}
+* <p> {@code HttpRequest} instances are built from {@code HttpRequest}
-* {@link HttpRequest.Builder builder}s. {@code HttpRequest} builders are
+* {@linkplain HttpRequest.Builder builders}. {@code HttpRequest} builders
-* obtained by calling {@link HttpRequest#newBuilder(java.net.URI)
+* are obtained by calling {@link HttpRequest#newBuilder(URI) HttpRequest.newBuilder}.
-* HttpRequest.newBuilder}.
+* A request's {@linkplain URI}, headers and body can be set. Request bodies are
-* A request's {@link java.net.URI}, headers and body can be set. Request bodies
+* provided through a {@link BodyPublisher} object supplied to the
-* are provided through a {@link BodyProcessor} object supplied to the
+* {@link Builder#DELETE(BodyPublisher) DELETE},
-* {@link Builder#DELETE(jdk.incubator.http.HttpRequest.BodyProcessor) DELETE},
+* {@link Builder#POST(BodyPublisher) POST} or
-* {@link Builder#POST(jdk.incubator.http.HttpRequest.BodyProcessor) POST} or
+* {@link Builder#PUT(BodyPublisher) PUT} methods.
-* {@link Builder#PUT(jdk.incubator.http.HttpRequest.BodyProcessor) PUT} methods.
 * {@link Builder#GET() GET} does not take a body. Once all required
 * parameters have been set in the builder, {@link Builder#build() } is called
-* to return the {@code HttpRequest}. Builders can also be copied
+* to return the {@code HttpRequest}. Builders can also be copied and modified
-* and modified multiple times in order to build multiple related requests that
+* multiple times in order to build multiple related requests that differ in
-* differ in some parameters.
+* some parameters.
 *
 * <p> Two simple, example HTTP interactions are shown below:
 * <pre>
 * {@code
 *      HttpClient client = HttpClient.newHttpClient();
 *      // POST
 *      HttpResponse<Path> response = client.send(
 *          HttpRequest
 *              .newBuilder(new URI("http://www.foo.com/"))
 *              .headers("Foo", "foovalue", "Bar", "barvalue")
-*              .POST(BodyProcessor.fromString("Hello world"))
+*              .POST(BodyPublisher.fromString("Hello world"))
 *              .build(),
 *          BodyHandler.asFile(Paths.get("/path"))
 *      );
 *      int statusCode = response.statusCode();
 *      Path body = response.body(); // should be "/path"
 * }
 * </pre>
+*
 * <p> The request is sent and the response obtained by calling one of the
 * following methods in {@link HttpClient}.
 * <ul><li>{@link HttpClient#send(HttpRequest, HttpResponse.BodyHandler)} blocks
 * until the entire request has been sent and the response has been received.</li>
 * <li>{@link HttpClient#sendAsync(HttpRequest,HttpResponse.BodyHandler)} sends the
 * request and receives the response asynchronously. Returns immediately with a
 * {@link java.util.concurrent.CompletableFuture CompletableFuture}&lt;{@link
 * HttpResponse}&gt;.</li>
-* <li>{@link HttpClient#sendAsync(HttpRequest,HttpResponse.MultiProcessor) }
+* <li>{@link HttpClient#sendAsync(HttpRequest, HttpResponse.MultiSubscriber) }
 * sends the request asynchronously, expecting multiple responses. This
 * capability is of most relevance to HTTP/2 server push, but can be used for
 * single responses (HTTP/1.1 or HTTP/2) also.</li>
 * </ul>
 *
 *
 * <p> See below for discussion of synchronous versus asynchronous usage.
 *
 * <p> <b>Request bodies</b>
 *
-* <p> Request bodies are sent using one of the request processor implementations
+* <p> Request bodies can be sent using one of the convenience request publisher
-* below provided in {@link HttpRequest.BodyProcessor}, or else a custom implementation can be
+* implementations below, provided in {@link BodyPublisher}. Alternatively, a
-* used.
+* custom Publisher implementation can be used.
 * <ul>
-* <li>{@link BodyProcessor#fromByteArray(byte[]) fromByteArray(byte[])} from byte array</li>
+* <li>{@link BodyPublisher#fromByteArray(byte[]) fromByteArray(byte[])} from byte array</li>
-* <li>{@link BodyProcessor#fromByteArrays(Iterable) fromByteArrays(Iterable)}
+* <li>{@link BodyPublisher#fromByteArrays(Iterable) fromByteArrays(Iterable)}
 *      from an Iterable of byte arrays</li>
-* <li>{@link BodyProcessor#fromFile(java.nio.file.Path) fromFile(Path)} from the file located
+* <li>{@link BodyPublisher#fromFile(java.nio.file.Path) fromFile(Path)} from the file located
 *     at the given Path</li>
-* <li>{@link BodyProcessor#fromString(java.lang.String) fromString(String)} from a String </li>
+* <li>{@link BodyPublisher#fromString(java.lang.String) fromString(String)} from a String </li>
-* <li>{@link BodyProcessor#fromInputStream(Supplier) fromInputStream}({@link Supplier}&lt;
+* <li>{@link BodyPublisher#fromInputStream(Supplier) fromInputStream}({@link Supplier}&lt;
 *      {@link InputStream}&gt;) from an InputStream obtained from a Supplier</li>
-* <li>{@link BodyProcessor#noBody() } no request body is sent</li>
+* <li>{@link BodyPublisher#noBody() } no request body is sent</li>
 * </ul>
 *
 * <p> <b>Response bodies</b>
 *
-* <p>Responses bodies are handled at two levels. When sending the request,
+* <p> Responses bodies are handled at two levels. When sending the request,
-* a response body handler is specified. This is a function ({@link HttpResponse.BodyHandler})
+* a response body handler is specified. This is a function ({@linkplain
-* which will be called with the response status code and headers, once these are received. This
+* HttpResponse.BodyHandler}) which will be called with the response status code
-* function is then expected to return a {@link HttpResponse.BodyProcessor}
+* and headers, once they are received. This function is then expected to return
-* {@code <T>} which is then used to read the response body converting it
+* a {@link HttpResponse.BodySubscriber}{@code <T>} which is then used to read
-* into an instance of T. After this occurs, the response becomes
+* the response body, converting it into an instance of T. After this occurs,
-* available in a {@link HttpResponse} and {@link HttpResponse#body()} can then
+* the response becomes available in a {@link HttpResponse}, and {@link
-* be called to obtain the body. Some implementations and examples of usage of both {@link
+* HttpResponse#body()} can then be called to obtain the actual body. Some
-* HttpResponse.BodyProcessor} and {@link HttpResponse.BodyHandler}
+* implementations and examples of usage of both {@link
-* are provided in {@link HttpResponse}:
+* HttpResponse.BodySubscriber} and {@link HttpResponse.BodyHandler} are
-* <p><b>Some of the pre-defined body handlers</b><br>
+* provided in {@link HttpResponse}:
+*
+* <p> <b>Some of the pre-defined body handlers</b><br>
 * <ul>
 * <li>{@link HttpResponse.BodyHandler#asByteArray() BodyHandler.asByteArray()}
 * stores the body in a byte array</li>
 * <li>{@link HttpResponse.BodyHandler#asString() BodyHandler.asString()}
 * stores the body as a String </li>
 *
 * <p> <b>Multi responses</b>
 *
 * <p> With HTTP/2 it is possible for a server to return a main response and zero
 * or more additional responses (known as server pushes) to a client-initiated
-* request. These are handled using a special response processor called {@link
+* request. These are handled using a special response subscriber called {@link
-* HttpResponse.MultiProcessor}.
+* HttpResponse.MultiSubscriber}.
 *
 * <p> <b>Blocking/asynchronous behavior and thread usage</b>
 *
 * <p> There are two styles of request sending: <i>synchronous</i> and
 * <i>asynchronous</i>. {@link HttpClient#send(HttpRequest, HttpResponse.BodyHandler) }
 * blocks the calling thread until the request has been sent and the response received.
 *
-* <p> {@link HttpClient#sendAsync(HttpRequest, HttpResponse.BodyHandler)}  is asynchronous and returns
+* <p> {@link HttpClient#sendAsync(HttpRequest, HttpResponse.BodyHandler)} is
-* immediately with a {@link java.util.concurrent.CompletableFuture}&lt;{@link
+* asynchronous and returns immediately with a {@link CompletableFuture}&lt;{@link
-* HttpResponse}&gt; and when this object completes (in a background thread) the
+* HttpResponse}&gt; and when this object completes (possibly in a different
-* response has been received.
+* thread) the response has been received.
 *
-* <p> {@link HttpClient#sendAsync(HttpRequest,HttpResponse.MultiProcessor)}
+* <p> {@link HttpClient#sendAsync(HttpRequest, HttpResponse.MultiSubscriber)}
 * is the variant for multi responses and is also asynchronous.
 *
-* <p> {@code CompletableFuture}s can be combined in different ways to declare the
+* <p> Instances of {@code CompletableFuture} can be combined in different ways
-* dependencies among several asynchronous tasks, while allowing for the maximum
+* to declare the dependencies among several asynchronous tasks, while allowing
-* level of parallelism to be utilized.
+* for the maximum level of parallelism to be utilized.
 *
-* <p> <b>Security checks</b>
+* <p> <a id="securitychecks"></a><b>Security checks</b></a>
 *
 * <p> If a security manager is present then security checks are performed by
-* the sending methods. A {@link java.net.URLPermission} or {@link java.net.SocketPermission} is required to
+* the HTTP Client's sending methods. An appropriate {@link URLPermission} is
-* access any destination origin server and proxy server utilised. {@code URLPermission}s
+* required to access the destination server, and proxy server if one has
-* should be preferred in policy files over {@code SocketPermission}s given the more
+* been configured. The {@code URLPermission} form used to access proxies uses a
-* limited scope of {@code URLPermission}. Permission is always implicitly granted to a
+* method parameter of {@code "CONNECT"} (for all kinds of proxying) and a URL
-* system's default proxies. The {@code URLPermission} form used to access proxies uses
+* string  of the form {@code "socket://host:port"} where host and port specify
-* a method parameter of {@code "CONNECT"} (for all kinds of proxying) and a url string
+* the proxy's address.
-* of the form {@code "socket://host:port"} where host and port specify the proxy's
+*
-* address.
+* <p> In this implementation, if an explicit {@linkplain
+* HttpClient.Builder#executor(Executor) executor} has not been set for an
+* {@code HttpClient}, and a security manager has been installed, then the
+* default executor will execute asynchronous and dependent tasks in a context
+* that is granted no permissions. Custom {@linkplain HttpRequest.BodyPublisher
+* request body publishers}, {@linkplain HttpResponse.BodyHandler response body
+* handlers}, {@linkplain HttpResponse.BodySubscriber response body subscribers},
+* and {@linkplain WebSocket.Listener WebSocket Listeners}, if executing
+* operations that require privileges, should do so  within an appropriate
+* {@linkplain AccessController#doPrivileged(PrivilegedAction) privileged context}.
 *
 * <p> <b>Examples</b>
 * <pre>{@code
 *      HttpClient client = HttpClient
 *              .newBuilder()
 *              .build();
 *
 *      HttpRequest request = HttpRequest
 *              .newBuilder(new URI("http://www.foo.com/"))
-*              .POST(BodyProcessor.fromString("Hello world"))
+*              .POST(BodyPublisher.fromString("Hello world"))
 *              .build();
 *
 *      HttpResponse<Path> response =
 *          client.send(request, BodyHandler.asFile(Paths.get("/path")));
 *
 *
 *      // all elements of futures have completed and can be examined.
 *      // Use File.exists() to check whether file was successfully downloaded
 * }
 * </pre>
-* <p>
+*
-* Unless otherwise stated, {@code null} parameter values will cause methods
+* <p> Unless otherwise stated, {@code null} parameter values will cause methods
 * of this class to throw {@code NullPointerException}.
 *
 * @since 9
 */
 public abstract class HttpRequest {
 * Creates an HttpRequest.
 */
 protected HttpRequest() {}
 /**
-* A builder of {@link HttpRequest}s.
+* A builder of {@linkplain HttpRequest HTTP Requests}.
 * {@Incubating}
 *
-* <p> {@code HttpRequest.Builder}s are created by calling {@link
+* <p> Instances of {@code HttpRequest.Builder} are created by calling {@link
 * HttpRequest#newBuilder(URI)} or {@link HttpRequest#newBuilder()}.
 *
 * <p> Each of the setter methods in this class modifies the state of the
 * builder and returns <i>this</i> (ie. the same instance). The methods are
 * not synchronized and should not be called from multiple threads without
 * external synchronization.
-* <p>Note, that not all request headers may be set by user code. Some are
+*
+* <p> Note, that not all request headers may be set by user code. Some are
 * restricted for security reasons and others such as the headers relating
 * to authentication, redirection and cookie management are managed by
 * specific APIs rather than through directly user set headers.
 *
 * <p> The {@linkplain #build() build} method returns a new {@code
 * Sets this {@code HttpRequest}'s request {@code URI}.
 *
 * @param uri the request URI
 * @return this request builder
 * @throws IllegalArgumentException if the {@code URI} scheme is not
-*         supported.
+*         supported
 */
 public abstract Builder uri(URI uri);
 /**
-* Request server to acknowledge request before sending request
+* Requests the server to acknowledge the request before sending the
-* body. This is disabled by default. If enabled, the server is requested
+* body. This is disabled by default. If enabled, the server is
-* to send an error response or a {@code 100 Continue} response before the client
+* requested to send an error response or a {@code 100 Continue}
-* sends the request body. This means the request processor for the
+* response before the client sends the request body. This means the
-* request will not be invoked until this interim response is received.
+* request publisher for the request will not be invoked until this
+* interim response is received.
 *
 * @param enable {@code true} if Expect continue to be sent
 * @return this request builder
 */
 public abstract Builder expectContinue(boolean enable);
 /**
-* Sets the preferred {@link HttpClient.Version} for this
+* Sets the preferred {@link HttpClient.Version} for this request.
-* request. The corresponding {@link HttpResponse} should be checked
+*
-* for the version that was used. If the version is not set
+* <p> The corresponding {@link HttpResponse} should be checked for the
-* in a request, then the version requested will be that of the
+* version that was actually used. If the version is not set in a
-* sending {@link HttpClient}.
+* request, then the version requested will be that of the sending
+* {@link HttpClient}.
 *
 * @param version the HTTP protocol version requested
 * @return this request builder
 */
 public abstract Builder version(HttpClient.Version version);
 /**
 * Adds the given name value pair to the set of headers for this request.
+* The given value is added to the list of values for that name.
 *
 * @param name the header name
 * @param value the header value
 * @return this request builder
+* @throws IllegalArgumentException if the header name or value is not
+*         valid, see <a href="https://tools.ietf.org/html/rfc7230#section-3.2">
+*         RFC 7230 section-3.2</a>
 */
 public abstract Builder header(String name, String value);
-//        /**
-//         * Overrides the {@code ProxySelector} set on the request's client for this
-//         * request.
-//         *
-//         * @param proxy the ProxySelector to use
-//         * @return this request builder
-//         */
-//        public abstract Builder proxy(ProxySelector proxy);
 /**
 * Adds the given name value pairs to the set of headers for this
-* request. The supplied {@code String}s must alternate as names and values.
+* request. The supplied {@code String} instances must alternate as
-*
+* header names and header values.
-* @param headers the list of String name value pairs
+* To add several values to the same name then the same name must
+* be supplied with each new value.
+*
+* @param headers the list of name value pairs
 * @return this request builder
-* @throws IllegalArgumentException if there is an odd number of
+* @throws IllegalArgumentException if there are an odd number of
-*                                  parameters
+*         parameters, or if a header name or value is not valid, see
-*/
+*         <a href="https://tools.ietf.org/html/rfc7230#section-3.2">
-// TODO (spec): consider signature change
+*         RFC 7230 section-3.2</a>
-// public abstract Builder headers(java.util.Map.Entry<String,String>... headers);
+*/
 public abstract Builder headers(String... headers);
 /**
 * Sets a timeout for this request. If the response is not received
 * within the specified timeout then a {@link HttpTimeoutException} is
 * of not setting a timeout is the same as setting an infinite Duration, ie.
 * block forever.
 *
 * @param duration the timeout duration
 * @return this request builder
+* @throws IllegalArgumentException if the duration is non-positive
 */
 public abstract Builder timeout(Duration duration);
 /**
 * Sets the given name value pair to the set of headers for this
 * request. This overwrites any previously set values for name.
 *
 * @param name the header name
 * @param value the header value
 * @return this request builder
+* @throws IllegalArgumentException if the header name or value is not valid,
+*         see <a href="https://tools.ietf.org/html/rfc7230#section-3.2">
+*         RFC 7230 section-3.2</a>
 */
 public abstract Builder setHeader(String name, String value);
 /**
 * Sets the request method of this builder to GET.
+* This is the default.
 *
 * @return a {@code HttpRequest}
 */
 public abstract Builder GET();
 /**
 * Sets the request method of this builder to POST and sets its
-* request body processor to the given value.
+* request body publisher to the given value.
 *
-* @param body the body processor
+* @param bodyPublisher the body publisher
 *
 * @return a {@code HttpRequest}
 */
-public abstract Builder POST(BodyProcessor body);
+public abstract Builder POST(BodyPublisher bodyPublisher);
 /**
 * Sets the request method of this builder to PUT and sets its
-* request body processor to the given value.
+* request body publisher to the given value.
 *
-* @param body the body processor
+* @param bodyPublisher the body publisher
 *
 * @return a {@code HttpRequest}
 */
-public abstract Builder PUT(BodyProcessor body);
+public abstract Builder PUT(BodyPublisher bodyPublisher);
 /**
 * Sets the request method of this builder to DELETE and sets its
-* request body processor to the given value.
+* request body publisher to the given value.
 *
-* @param body the body processor
+* @param bodyPublisher the body publisher
 *
 * @return a {@code HttpRequest}
 */
-public abstract Builder DELETE(BodyProcessor body);
+public abstract Builder DELETE(BodyPublisher bodyPublisher);
 /**
 * Sets the request method and request body of this builder to the
 * given values.
 *
-* @param body the body processor
+* @apiNote The {@linkplain BodyPublisher#noBody() noBody} request
+* body publisher can be used where no request body is required or
+* appropriate.
+*
 * @param method the method to use
+* @param bodyPublisher the body publisher
 * @return a {@code HttpRequest}
-* @throws IllegalArgumentException if an unrecognized method is used
+* @throws IllegalArgumentException if the method is unrecognised
 */
-public abstract Builder method(String method, BodyProcessor body);
+public abstract Builder method(String method, BodyPublisher bodyPublisher);
 /**
 * Builds and returns a {@link HttpRequest}.
 *
 * @return the request
+* @throws IllegalStateException if a URI has not been set
 */
 public abstract HttpRequest build();
 /**
-* Returns an exact duplicate copy of this {@code Builder} based on current
+* Returns an exact duplicate copy of this {@code Builder} based on
-* state. The new builder can then be modified independently of this
+* current state. The new builder can then be modified independently of
-* builder.
+* this builder.
 *
 * @return an exact copy of this Builder
 */
 public abstract Builder copy();
 }
 public static HttpRequest.Builder newBuilder() {
 return new HttpRequestBuilderImpl();
 }
 /**
-* Returns an {@code Optional} containing the {@link BodyProcessor}
+* Returns an {@code Optional} containing the {@link BodyPublisher} set on
-* set on this request. If no {@code BodyProcessor} was set in the
+* this request. If no {@code BodyPublisher} was set in the requests's
-* requests's builder, then the {@code Optional} is empty.
+* builder, then the {@code Optional} is empty.
 *
-* @return an {@code Optional} containing this request's
+* @return an {@code Optional} containing this request's {@code BodyPublisher}
-*         {@code BodyProcessor}
+*/
-*/
+public abstract Optional<BodyPublisher> bodyPublisher();
-public abstract Optional<BodyProcessor> bodyProcessor();
 /**
 * Returns the request method for this request. If not set explicitly,
 * the default method for any request is "GET".
 *
 * @return this request's method
 */
 public abstract String method();
 /**
-* Returns the duration for this request.
+* Returns an {@code Optional} containing this request's timeout duration.
-*
+* If the timeout duration was not set in the request's builder, then the
-* @return this requests duration
+* {@code Optional} is empty.
-*/
+*
-public abstract Duration duration();
+* @return an {@code Optional} containing this request's timeout duration
+*/
+public abstract Optional<Duration> timeout();
 /**
 * Returns this request's {@link HttpRequest.Builder#expectContinue(boolean)
 * expect continue } setting.
 *
 *
 * @return this request's HttpHeaders
 */
 public abstract HttpHeaders headers();
+/**
-/**
+* Tests this HTTP request instance for equality with the given object.
-* A request body handler which sends no request body.
+*
-*
+* <p> If the given object is not an {@code HttpRequest} then this
-* @return a BodyProcessor
+* method returns {@code false}. Two HTTP requests are equal if their URI,
-*/
+* method, and headers fields are all equal.
-public static BodyProcessor noBody() {
+*
-return new RequestProcessors.EmptyProcessor();
+* <p> This method satisfies the general contract of the {@link
+* Object#equals(Object) Object.equals} method.
+*
+* @param obj the object to which this object is to be compared
+* @return {@code true} if, and only if, the given object is an {@code
+*         HttpRequest} that is equal to this HTTP request
+*/
+@Override
+public final boolean equals(Object obj) {
+if (! (obj instanceof HttpRequest))
+return false;
+HttpRequest that = (HttpRequest)obj;
+if (!that.method().equals(this.method()))
+return false;
+if (!that.uri().equals(this.uri()))
+return false;
+if (!that.headers().equals(this.headers()))
+return false;
+return true;
 }
 /**
-* A processor which converts high level Java objects into flows of
+* Computes a hash code for this HTTP request instance.
-* {@link java.nio.ByteBuffer}s suitable for sending as request bodies.
+*
+* <p> The hash code is based upon the HTTP request's URI, method, and
+* header components, and satisfies the general contract of the
+* {@link Object#hashCode Object.hashCode} method.
+*
+* @return the hash-code value for this HTTP request
+*/
+public final int hashCode() {
+return method().hashCode()
++ uri().hashCode()
++ headers().hashCode();
+}
+/**
+* A Publisher which converts high level Java objects into flows of
+* byte buffers suitable for sending as request bodies.
 * {@Incubating}
-* <p>
+*
-* {@code BodyProcessor}s implement {@link Flow.Publisher} which means they
+* <p> The {@code BodyPublisher} class implements {@link Flow.Publisher
-* act as a publisher of byte buffers.
+* Flow.Publisher&lt;ByteBuffer&gt;} which means that a {@code BodyPublisher}
-* <p>
+* acts as a publisher of {@linkplain ByteBuffer byte buffers}.
-* The HTTP client implementation subscribes to the processor in
+*
-* order to receive the flow of outgoing data buffers. The normal semantics
+* <p> The HTTP client implementation subscribes to the publisher in order
-* of {@link Flow.Subscriber} and {@link Flow.Publisher} are implemented
+* to receive the flow of outgoing data buffers. The normal semantics of
-* by the library and expected from processor implementations.
+* {@link Flow.Subscriber} and {@link Flow.Publisher} are implemented by the
-* Each outgoing request results in one {@code Subscriber} subscribing to the
+* library and are expected from publisher implementations. Each outgoing
-* {@code Publisher} in order to provide the sequence of {@code ByteBuffer}s containing
+* request results in one {@code Subscriber} subscribing to the {@code
-* the request body. {@code ByteBuffer}s must be allocated by the processor,
+* BodyPublisher} in order to provide the sequence of byte buffers
-* and must not be accessed after being handed over to the library.
+* containing the request body.
-* These subscriptions complete normally when the request is fully
+* Instances of {@code ByteBuffer} published  by the publisher must be
-* sent, and can be canceled or terminated early through error. If a request
+* allocated by the publisher, and must not be accessed after being handed
+* over to the library.
+* These subscriptions complete normally when the request is fully sent,
+* and can be canceled or terminated early through error. If a request
 * needs to be resent for any reason, then a new subscription is created
 * which is expected to generate the same data as before.
-*/
+*
-public interface BodyProcessor extends Flow.Publisher<ByteBuffer> {
+* <p> A publisher that reports a {@linkplain #contentLength() content
+* length} of {@code 0} may not be subscribed to by the HTTP client
-/**
+* implementation, as it has effectively no data to publish.
-* Returns a request body processor whose body is the given {@code String},
+*/
-* converted using the {@link java.nio.charset.StandardCharsets#UTF_8 UTF_8}
+public interface BodyPublisher extends Flow.Publisher<ByteBuffer> {
+/**
+* Returns a request body publisher whose body is the given {@code
+* String}, converted using the {@link StandardCharsets#UTF_8 UTF_8}
 * character set.
 *
 * @param body the String containing the body
-* @return a BodyProcessor
+* @return a BodyPublisher
 */
-static BodyProcessor fromString(String body) {
+static BodyPublisher fromString(String body) {
-return fromString(body, StandardCharsets.UTF_8);
+return fromString(body, UTF_8);
 }
 /**
-* Returns a request body processor whose body is the given {@code String}, converted
+* Returns a request body publisher whose body is the given {@code
-* using the given character set.
+* String}, converted using the given character set.
 *
 * @param s the String containing the body
 * @param charset the character set to convert the string to bytes
-* @return a BodyProcessor
+* @return a BodyPublisher
 */
-static BodyProcessor fromString(String s, Charset charset) {
+static BodyPublisher fromString(String s, Charset charset) {
-return new RequestProcessors.StringProcessor(s, charset);
+return new RequestPublishers.StringPublisher(s, charset);
 }
 /**
-* A request body processor that reads its data from an {@link java.io.InputStream}.
+* A request body publisher that reads its data from an {@link
-* A {@link Supplier} of {@code InputStream} is used in case the request needs
+* InputStream}. A {@link Supplier} of {@code InputStream} is used in
-* to be sent again as the content is not buffered. The {@code Supplier} may return
+* case the request needs to be repeated, as the content is not buffered.
-* {@code null} on subsequent attempts in which case, the request fails.
+* The {@code Supplier} may return {@code null} on subsequent attempts,
+* in which case the request fails.
 *
 * @param streamSupplier a Supplier of open InputStreams
-* @return a BodyProcessor
+* @return a BodyPublisher
 */
 // TODO (spec): specify that the stream will be closed
-static BodyProcessor fromInputStream(Supplier<? extends InputStream> streamSupplier) {
+static BodyPublisher fromInputStream(Supplier<? extends InputStream> streamSupplier) {
-return new RequestProcessors.InputStreamProcessor(streamSupplier);
+return new RequestPublishers.InputStreamPublisher(streamSupplier);
 }
 /**
-* Returns a request body processor whose body is the given byte array.
+* Returns a request body publisher whose body is the given byte array.
 *
 * @param buf the byte array containing the body
-* @return a BodyProcessor
+* @return a BodyPublisher
 */
-static BodyProcessor fromByteArray(byte[] buf) {
+static BodyPublisher fromByteArray(byte[] buf) {
-return new RequestProcessors.ByteArrayProcessor(buf);
+return new RequestPublishers.ByteArrayPublisher(buf);
 }
 /**
-* Returns a request body processor whose body is the content of the given byte
+* Returns a request body publisher whose body is the content of the
-* array of {@code length} bytes starting from the specified
+* given byte array of {@code length} bytes starting from the specified
 * {@code offset}.
 *
 * @param buf the byte array containing the body
 * @param offset the offset of the first byte
 * @param length the number of bytes to use
-* @return a BodyProcessor
+* @return a BodyPublisher
-*/
+* @throws IndexOutOfBoundsException if the sub-range is defined to be
-static BodyProcessor fromByteArray(byte[] buf, int offset, int length) {
+*                                   out-of-bounds
-return new RequestProcessors.ByteArrayProcessor(buf, offset, length);
+*/
-}
+static BodyPublisher fromByteArray(byte[] buf, int offset, int length) {
+Objects.checkFromIndexSize(offset, length, buf.length);
-/**
+return new RequestPublishers.ByteArrayPublisher(buf, offset, length);
-* A request body processor that takes data from the contents of a File.
+}
+private static String pathForSecurityCheck(Path path) {
+return path.toFile().getPath();
+}
+/**
+* A request body publisher that takes data from the contents of a File.
 *
 * @param path the path to the file containing the body
-* @return a BodyProcessor
+* @return a BodyPublisher
-* @throws java.io.FileNotFoundException if path not found
+* @throws java.io.FileNotFoundException if the path is not found
-*/
+* @throws SecurityException if a security manager has been installed
-static BodyProcessor fromFile(Path path) throws FileNotFoundException {
+*          and it denies {@link SecurityManager#checkRead(String)
-return new RequestProcessors.FileProcessor(path);
+*          read access} to the given file
-}
+*/
+static BodyPublisher fromFile(Path path) throws FileNotFoundException {
-/**
+Objects.requireNonNull(path);
-* A request body processor that takes data from an {@code Iterable} of byte arrays.
+SecurityManager sm = System.getSecurityManager();
-* An {@link Iterable} is provided which supplies {@link Iterator} instances.
+if (sm != null)
-* Each attempt to send the request results in one invocation of the
+sm.checkRead(pathForSecurityCheck(path));
-* {@code Iterable}
+if (Files.notExists(path))
+throw new FileNotFoundException(path + " not found");
+return new RequestPublishers.FilePublisher(path);
+}
+/**
+* A request body publisher that takes data from an {@code Iterable}
+* of byte arrays. An {@link Iterable} is provided which supplies
+* {@link Iterator} instances. Each attempt to send the request results
+* in one invocation of the {@code Iterable}.
 *
 * @param iter an Iterable of byte arrays
-* @return a BodyProcessor
+* @return a BodyPublisher
 */
-static BodyProcessor fromByteArrays(Iterable<byte[]> iter) {
+static BodyPublisher fromByteArrays(Iterable<byte[]> iter) {
-return new RequestProcessors.IterableProcessor(iter);
+return new RequestPublishers.IterablePublisher(iter);
 }
+/**
+* A request body publisher which sends no request body.
+*
+* @return a BodyPublisher which completes immediately and sends
+*         no request body.
+*/
+static BodyPublisher noBody() {
+return new RequestPublishers.EmptyPublisher();
+}
 /**
 * Returns the content length for this request body. May be zero
-* if no request content being sent, greater than zero for a fixed
+* if no request body being sent, greater than zero for a fixed
-* length content, and less than zero for an unknown content length.
+* length content, or less than zero for an unknown content length.
 *
-* @return the content length for this request body if known
+* This method may be invoked before the publisher is subscribed to.
+* This method may be invoked more than once by the HTTP client
+* implementation, and MUST return the same constant value each time.
+*
+* @return the content length for this request body, if known
 */
 long contentLength();
-//        /**
-//         * Returns a used {@code ByteBuffer} to this request processor. When the
-//         * HTTP implementation has finished sending the contents of a buffer,
-//         * this method is called to return it to the processor for re-use.
-//         *
-//         * @param buffer a used ByteBuffer
-//         */
-//void returnBuffer(ByteBuffer buffer);
 }
 }

changeset 48083	b1c1b4ef4be2
parent 47216	71c04702a3d5
child 48408	4f830b447edf
child 55973	4d9b002587db