< prev index next >
src/jdk.incubator.httpclient/share/classes/jdk/incubator/http/HttpRequest.java
Print this page
@@ -26,38 +26,45 @@
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}
- * {@link HttpRequest.Builder builder}s. {@code HttpRequest} builders are
- * obtained by calling {@link HttpRequest#newBuilder(java.net.URI)
- * HttpRequest.newBuilder}.
- * A request's {@link java.net.URI}, headers and body can be set. Request bodies
- * are provided through a {@link BodyProcessor} object supplied to the
- * {@link Builder#DELETE(jdk.incubator.http.HttpRequest.BodyProcessor) DELETE},
- * {@link Builder#POST(jdk.incubator.http.HttpRequest.BodyProcessor) POST} or
- * {@link Builder#PUT(jdk.incubator.http.HttpRequest.BodyProcessor) PUT} methods.
+ * <p> {@code HttpRequest} instances are built from {@code HttpRequest}
+ * {@linkplain HttpRequest.Builder builders}. {@code HttpRequest} builders
+ * are obtained by calling {@link HttpRequest#newBuilder(URI) HttpRequest.newBuilder}.
+ * A request's {@linkplain URI}, headers and body can be set. Request bodies are
+ * provided through a {@link BodyPublisher} object supplied to the
+ * {@link Builder#DELETE(BodyPublisher) DELETE},
+ * {@link Builder#POST(BodyPublisher) POST} or
+ * {@link Builder#PUT(BodyPublisher) 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
- * and modified multiple times in order to build multiple related requests that
- * differ in some parameters.
+ * to return the {@code HttpRequest}. Builders can also be copied and modified
+ * multiple times in order to build multiple related requests that differ in
+ * some parameters.
*
* <p> Two simple, example HTTP interactions are shown below:
* <pre>
* {@code
* HttpClient client = HttpClient.newHttpClient();
@@ -77,27 +84,28 @@
* // 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}<{@link
* HttpResponse}>.</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>
*
@@ -107,38 +115,40 @@
*
* <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
- * below provided in {@link HttpRequest.BodyProcessor}, or else a custom implementation can be
- * used.
+ * <p> Request bodies can be sent using one of the convenience request publisher
+ * implementations below, provided in {@link BodyPublisher}. Alternatively, a
+ * custom Publisher implementation can be used.
* <ul>
- * <li>{@link BodyProcessor#fromByteArray(byte[]) fromByteArray(byte[])} from byte array</li>
- * <li>{@link BodyProcessor#fromByteArrays(Iterable) fromByteArrays(Iterable)}
+ * <li>{@link BodyPublisher#fromByteArray(byte[]) fromByteArray(byte[])} from byte array</li>
+ * <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 BodyProcessor#fromInputStream(Supplier) fromInputStream}({@link Supplier}<
+ * <li>{@link BodyPublisher#fromString(java.lang.String) fromString(String)} from a String </li>
+ * <li>{@link BodyPublisher#fromInputStream(Supplier) fromInputStream}({@link Supplier}<
* {@link InputStream}>) 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,
- * a response body handler is specified. This is a function ({@link HttpResponse.BodyHandler})
- * which will be called with the response status code and headers, once these are received. This
- * function is then expected to return a {@link HttpResponse.BodyProcessor}
- * {@code <T>} which is then used to read the response body converting it
- * into an instance of T. After this occurs, the response becomes
- * available in a {@link HttpResponse} and {@link HttpResponse#body()} can then
- * be called to obtain the body. Some implementations and examples of usage of both {@link
- * HttpResponse.BodyProcessor} and {@link HttpResponse.BodyHandler}
- * are provided in {@link HttpResponse}:
- * <p><b>Some of the pre-defined body handlers</b><br>
+ * <p> Responses bodies are handled at two levels. When sending the request,
+ * a response body handler is specified. This is a function ({@linkplain
+ * HttpResponse.BodyHandler}) which will be called with the response status code
+ * and headers, once they are received. This function is then expected to return
+ * a {@link HttpResponse.BodySubscriber}{@code <T>} which is then used to read
+ * the response body, converting it into an instance of T. After this occurs,
+ * the response becomes available in a {@link HttpResponse}, and {@link
+ * HttpResponse#body()} can then be called to obtain the actual body. Some
+ * implementations and examples of usage of both {@link
+ * HttpResponse.BodySubscriber} and {@link HttpResponse.BodyHandler} are
+ * 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>
@@ -150,52 +160,61 @@
*
* <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
- * HttpResponse.MultiProcessor}.
+ * request. These are handled using a special response subscriber called {@link
+ * 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
- * immediately with a {@link java.util.concurrent.CompletableFuture}<{@link
- * HttpResponse}> and when this object completes (in a background thread) the
- * response has been received.
+ * <p> {@link HttpClient#sendAsync(HttpRequest, HttpResponse.BodyHandler)} is
+ * asynchronous and returns immediately with a {@link CompletableFuture}<{@link
+ * HttpResponse}> and when this object completes (possibly in a different
+ * 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
- * dependencies among several asynchronous tasks, while allowing for the maximum
- * level of parallelism to be utilized.
+ * <p> Instances of {@code CompletableFuture} can be combined in different ways
+ * to declare the dependencies among several asynchronous tasks, while allowing
+ * 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
- * access any destination origin server and proxy server utilised. {@code URLPermission}s
- * should be preferred in policy files over {@code SocketPermission}s given the more
- * limited scope of {@code URLPermission}. Permission is always implicitly granted to a
- * system's default proxies. The {@code URLPermission} form used to access proxies uses
- * a method parameter of {@code "CONNECT"} (for all kinds of proxying) and a url string
- * of the form {@code "socket://host:port"} where host and port specify the proxy's
- * address.
+ * the HTTP Client's sending methods. An appropriate {@link URLPermission} is
+ * required to access the destination server, and proxy server if one has
+ * been configured. The {@code URLPermission} form used to access proxies uses a
+ * method parameter of {@code "CONNECT"} (for all kinds of proxying) and a URL
+ * string 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")));
*
@@ -237,12 +256,12 @@
*
* // 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 {
@@ -251,21 +270,22 @@
* 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
@@ -284,67 +304,67 @@
* 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
- * body. This is disabled by default. If enabled, the server is requested
- * to send an error response or a {@code 100 Continue} response before the client
- * sends the request body. This means the request processor for the
- * request will not be invoked until this interim response is received.
+ * Requests the server to acknowledge the request before sending the
+ * body. This is disabled by default. If enabled, the server is
+ * requested to send an error response or a {@code 100 Continue}
+ * response before the client sends the request body. This means the
+ * 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
- * request. The corresponding {@link HttpResponse} should be checked
- * for the version that was used. If the version is not set
- * in a request, then the version requested will be that of the
- * sending {@link HttpClient}.
+ * Sets the preferred {@link HttpClient.Version} for this request.
+ *
+ * <p> The corresponding {@link HttpResponse} should be checked for the
+ * version that was actually used. If the version is not set in a
+ * 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.
+ * To add several values to the same name then the same name must
+ * be supplied with each new value.
*
- * @param headers the list of String name value pairs
+ * @param headers the list of name value pairs
* @return this request builder
- * @throws IllegalArgumentException if there is an odd number of
- * parameters
+ * @throws IllegalArgumentException if there are an odd number of
+ * parameters, or if a 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>
*/
- // TODO (spec): consider signature change
- // 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
@@ -356,83 +376,93 @@
* 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
- * state. The new builder can then be modified independently of this
- * builder.
+ * Returns an exact duplicate copy of this {@code Builder} based on
+ * current state. The new builder can then be modified independently of
+ * this builder.
*
* @return an exact copy of this Builder
*/
public abstract Builder copy();
}
@@ -456,33 +486,34 @@
public static HttpRequest.Builder newBuilder() {
return new HttpRequestBuilderImpl();
}
/**
- * Returns an {@code Optional} containing the {@link BodyProcessor}
- * set on this request. If no {@code BodyProcessor} was set in the
- * requests's builder, then the {@code Optional} is empty.
+ * Returns an {@code Optional} containing the {@link BodyPublisher} set on
+ * this request. If no {@code BodyPublisher} was set in the requests's
+ * builder, then the {@code Optional} is empty.
*
- * @return an {@code Optional} containing this request's
- * {@code BodyProcessor}
+ * @return an {@code Optional} containing this request's {@code BodyPublisher}
*/
- public abstract Optional<BodyProcessor> bodyProcessor();
+ public abstract Optional<BodyPublisher> bodyPublisher();
/**
* 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
+ * {@code Optional} is empty.
*
- * @return this requests duration
+ * @return an {@code Optional} containing this request's timeout duration
*/
- public abstract Duration duration();
+ public abstract Optional<Duration> timeout();
/**
* Returns this request's {@link HttpRequest.Builder#expectContinue(boolean)
* expect continue } setting.
*
@@ -515,142 +546,205 @@
*
* @return this request's HttpHeaders
*/
public abstract HttpHeaders headers();
+ /**
+ * Tests this HTTP request instance for equality with the given object.
+ *
+ * <p> If the given object is not an {@code HttpRequest} then this
+ * method returns {@code false}. Two HTTP requests are equal if their URI,
+ * method, and headers fields are all equal.
+ *
+ * <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 request body handler which sends no request body.
+ * Computes a hash code for this HTTP request instance.
+ *
+ * <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 a BodyProcessor
+ * @return the hash-code value for this HTTP request
*/
- public static BodyProcessor noBody() {
- return new RequestProcessors.EmptyProcessor();
+ public final int hashCode() {
+ return method().hashCode()
+ + uri().hashCode()
+ + headers().hashCode();
}
/**
- * A processor which converts high level Java objects into flows of
- * {@link java.nio.ByteBuffer}s suitable for sending as request bodies.
+ * 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
- * act as a publisher of byte buffers.
- * <p>
- * The HTTP client implementation subscribes to the processor in
- * order to receive the flow of outgoing data buffers. The normal semantics
- * of {@link Flow.Subscriber} and {@link Flow.Publisher} are implemented
- * by the library and expected from processor implementations.
- * Each outgoing request results in one {@code Subscriber} subscribing to the
- * {@code Publisher} in order to provide the sequence of {@code ByteBuffer}s containing
- * the request body. {@code ByteBuffer}s must be allocated by the processor,
- * 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
+ *
+ * <p> The {@code BodyPublisher} class implements {@link Flow.Publisher
+ * Flow.Publisher<ByteBuffer>} which means that a {@code BodyPublisher}
+ * acts as a publisher of {@linkplain ByteBuffer byte buffers}.
+ *
+ * <p> The HTTP client implementation subscribes to the publisher in order
+ * to receive the flow of outgoing data buffers. The normal semantics of
+ * {@link Flow.Subscriber} and {@link Flow.Publisher} are implemented by the
+ * library and are expected from publisher implementations. Each outgoing
+ * request results in one {@code Subscriber} subscribing to the {@code
+ * BodyPublisher} in order to provide the sequence of byte buffers
+ * containing the request body.
+ * Instances of {@code ByteBuffer} published by the publisher must be
+ * 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.
+ *
+ * <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.
*/
- public interface BodyProcessor extends Flow.Publisher<ByteBuffer> {
+ public interface BodyPublisher extends Flow.Publisher<ByteBuffer> {
/**
- * Returns a request body processor whose body is the given {@code String},
- * converted using the {@link java.nio.charset.StandardCharsets#UTF_8 UTF_8}
+ * 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) {
- return fromString(body, StandardCharsets.UTF_8);
+ static BodyPublisher fromString(String body) {
+ return fromString(body, UTF_8);
}
/**
- * Returns a request body processor whose body is the given {@code String}, converted
- * using the given character set.
+ * Returns a request body publisher whose body is the given {@code
+ * 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) {
- return new RequestProcessors.StringProcessor(s, charset);
+ static BodyPublisher fromString(String s, Charset charset) {
+ return new RequestPublishers.StringPublisher(s, charset);
}
/**
- * A request body processor that reads its data from an {@link java.io.InputStream}.
- * A {@link Supplier} of {@code InputStream} is used in case the request needs
- * to be sent again as the content is not buffered. The {@code Supplier} may return
- * {@code null} on subsequent attempts in which case, the request fails.
+ * A request body publisher that reads its data from an {@link
+ * InputStream}. A {@link Supplier} of {@code InputStream} is used in
+ * case the request needs to be repeated, as the content is not buffered.
+ * 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) {
- return new RequestProcessors.InputStreamProcessor(streamSupplier);
+ static BodyPublisher fromInputStream(Supplier<? extends InputStream> 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) {
- return new RequestProcessors.ByteArrayProcessor(buf);
+ static BodyPublisher fromByteArray(byte[] buf) {
+ return new RequestPublishers.ByteArrayPublisher(buf);
}
/**
- * Returns a request body processor whose body is the content of the given byte
- * array of {@code length} bytes starting from the specified
+ * Returns a request body publisher whose body is the content of the
+ * 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
+ * out-of-bounds
*/
- static BodyProcessor fromByteArray(byte[] buf, int offset, int length) {
- 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);
+ }
+
+ private static String pathForSecurityCheck(Path path) {
+ return path.toFile().getPath();
}
/**
- * A request body processor that takes data from the contents of a File.
+ * 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
- * @throws java.io.FileNotFoundException if path not found
- */
- static BodyProcessor fromFile(Path path) throws FileNotFoundException {
- return new RequestProcessors.FileProcessor(path);
+ * @return a BodyPublisher
+ * @throws java.io.FileNotFoundException if the path is not found
+ * @throws SecurityException if a security manager has been installed
+ * and it denies {@link SecurityManager#checkRead(String)
+ * read access} to the given file
+ */
+ static BodyPublisher fromFile(Path path) throws FileNotFoundException {
+ Objects.requireNonNull(path);
+ SecurityManager sm = System.getSecurityManager();
+ if (sm != null)
+ sm.checkRead(pathForSecurityCheck(path));
+ if (Files.notExists(path))
+ throw new FileNotFoundException(path + " not found");
+ return new RequestPublishers.FilePublisher(path);
}
/**
- * A request body processor 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}
+ * 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) {
- return new RequestProcessors.IterableProcessor(iter);
+ static BodyPublisher fromByteArrays(Iterable<byte[]> 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
- * length content, and less than zero for an unknown content length.
+ * if no request body being sent, greater than zero for a fixed
+ * length content, or less than zero for an unknown content length.
+ *
+ * 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
+ * @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);
}
}
< prev index next >