An {@code HttpRequest} instance is built through an {@code HttpRequest} * {@linkplain HttpRequest.Builder builder}. An {@code HttpRequest} builder * is obtained from one of the {@link HttpRequest#newBuilder(URI) newBuilder} * methods. A request's {@link URI}, headers, and body can be set. Request * bodies are provided through a {@link BodyPublisher BodyPublisher} supplied * to one of the {@link Builder#POST(BodyPublisher) POST}, * {@link Builder#PUT(BodyPublisher) PUT} or * {@link Builder#method(String,BodyPublisher) method} methods. * Once all required parameters have been set in the builder, {@link * Builder#build() build} will return the {@code HttpRequest}. Builders can be * copied and modified many times in order to build multiple related requests * that differ in some parameters. * *
The following is an example of a GET request that prints the response * body as a String: * * {@snippet : * HttpClient client = HttpClient.newHttpClient(); * * HttpRequest request = HttpRequest.newBuilder() * .uri(URI.create("http://foo.com/")) * .build(); * * client.sendAsync(request, BodyHandlers.ofString()) * .thenApply(HttpResponse::body) * .thenAccept(System.out::println) * .join(); } * *
The class {@link BodyPublishers BodyPublishers} provides implementations * of many common publishers. Alternatively, a custom {@code BodyPublisher} * implementation can be used. * * @since 11 */ public abstract class HttpRequest { /** * Creates an HttpRequest. */ protected HttpRequest() {} /** * A builder of {@linkplain HttpRequest HTTP requests}. * *
Instances of {@code HttpRequest.Builder} are created by calling * {@link HttpRequest#newBuilder()}, {@link HttpRequest#newBuilder(URI)}, * or {@link HttpRequest#newBuilder(HttpRequest, BiPredicate)}. * *
The builder can be used to configure per-request state, such as: the * request URI, the request method (default is GET unless explicitly set), * specific request headers, etc. Each of the setter methods modifies the * state of the builder and returns the same instance. The methods are not * synchronized and should not be called from multiple threads without * external synchronization. The {@link #build() build} method returns a new * {@code HttpRequest} each time it is invoked. Once built an {@code * HttpRequest} is immutable, and can be sent multiple times. * *
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 may be managed by * specific APIs rather than through directly user set headers. * * @since 11 */ public interface Builder { /** * Sets this {@code HttpRequest}'s request {@code URI}. * * @param uri the request URI * @return this builder * @throws IllegalArgumentException if the {@code URI} scheme is not * supported */ public Builder uri(URI uri); /** * 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 builder */ public 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 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 builder */ public 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. * * @implNote An implementation may choose to restrict some header names * or values, as the HTTP Client may determine their value itself. * For example, "Content-Length", which will be determined by * the request Publisher. In such a case, an implementation of * {@code HttpRequest.Builder} may choose to throw an * {@code IllegalArgumentException} if such a header is passed * to the builder. * * @param name the header name * @param value the header value * @return this builder * @throws IllegalArgumentException if the header name or value is not * valid, see * RFC 7230 section-3.2, or the header name or value is restricted * by the implementation. */ public Builder header(String name, String value); /** * Adds the given name value pairs to the set of headers for this * 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 name value pairs * @return this builder * @throws IllegalArgumentException if there are an odd number of * parameters, or if a header name or value is not valid, see * * RFC 7230 section-3.2, or a header name or value is * {@linkplain #header(String, String) restricted} by the * implementation. */ public Builder headers(String... headers); /** * Sets a timeout for this request. If the response is not received * within the specified timeout then an {@link HttpTimeoutException} is * thrown from {@link HttpClient#send(java.net.http.HttpRequest, * java.net.http.HttpResponse.BodyHandler) HttpClient::send} or * {@link HttpClient#sendAsync(java.net.http.HttpRequest, * java.net.http.HttpResponse.BodyHandler) HttpClient::sendAsync} * completes exceptionally with an {@code HttpTimeoutException}. The effect * of not setting a timeout is the same as setting an infinite Duration, * i.e. block forever. * * @param duration the timeout duration * @return this 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 builder * @throws IllegalArgumentException if the header name or value is not valid, * see * RFC 7230 section-3.2, or the header name or value is * {@linkplain #header(String, String) restricted} by the * implementation. */ public Builder setHeader(String name, String value); /** * Sets the request method of this builder to GET. * This is the default. * * @return this builder */ public Builder GET(); /** * Sets the request method of this builder to POST and sets its * request body publisher to the given value. * * @param bodyPublisher the body publisher * * @return this builder */ public Builder POST(BodyPublisher bodyPublisher); /** * Sets the request method of this builder to PUT and sets its * request body publisher to the given value. * * @param bodyPublisher the body publisher * * @return this builder */ public Builder PUT(BodyPublisher bodyPublisher); /** * Sets the request method of this builder to DELETE. * * @return this builder */ public Builder DELETE(); /** * Sets the request method of this builder to HEAD. * * @implSpec The default implementation is expected to have the same behaviour as: * {@code return method("HEAD", BodyPublishers.noBody());} * * @return this builder * @since 18 */ default Builder HEAD() { return method("HEAD", BodyPublishers.noBody()); } /** * Sets the request method and request body of this builder to the * given values. * * @apiNote The {@link BodyPublishers#noBody() noBody} request * body publisher can be used where no request body is required or * appropriate. Whether a method is restricted, or not, is * implementation specific. For example, some implementations may choose * to restrict the {@code CONNECT} method. * * @param method the method to use * @param bodyPublisher the body publisher * @return this builder * @throws IllegalArgumentException if the method name is not * valid, see * RFC 7230 section-3.1.1, or the method is restricted by the * implementation. */ public Builder method(String method, BodyPublisher bodyPublisher); /** * Builds and returns an {@link HttpRequest}. * * @implSpec This method returns a new {@code HttpRequest} each time it is * invoked. Once built, the {@code HttpRequest} is immutable and can be * sent multiple times. * * @return a new {@code HttpRequest} * @throws IllegalStateException if a URI has not been set */ public 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. * * @return an exact copy of this builder */ public Builder copy(); } /** * Creates an {@code HttpRequest} builder with the given URI. * * @param uri the request URI * @return a new request builder * @throws IllegalArgumentException if the URI scheme is not supported. */ public static HttpRequest.Builder newBuilder(URI uri) { return new HttpRequestBuilderImpl(uri); } /** * Creates a {@code Builder} whose initial state is copied from an existing * {@code HttpRequest}. * *
This builder can be used to build an {@code HttpRequest}, equivalent * to the original, while allowing amendment of the request state prior to * construction - for example, adding additional headers. * *
The {@code filter} is applied to each header name value pair as they
* are copied from the given request. When completed, only headers that
* satisfy the condition as laid out by the {@code filter} will be present
* in the {@code Builder} returned from this method.
*
* @apiNote
* The following scenarios demonstrate typical use-cases of the filter.
* Given an {@code HttpRequest} request:
*
*
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. * *
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; } /** * Computes a hash code for this HTTP request instance. * *
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 {@code BodyPublisher} converts high-level Java objects into a flow of * byte buffers suitable for sending as a request body. The class * {@link BodyPublishers BodyPublishers} provides implementations of many * common publishers. * *
The {@code BodyPublisher} interface extends {@link Flow.Publisher * Flow.Publisher<ByteBuffer>}, which means that a {@code BodyPublisher} * acts as a publisher of {@linkplain ByteBuffer byte buffers}. * *
When sending a request that contains a body, the HTTP Client * subscribes to the request's {@code BodyPublisher} in order to receive the * flow of outgoing request body data. The normal semantics of {@link * Flow.Subscriber} and {@link Flow.Publisher} are implemented by the HTTP * Client and are expected from {@code BodyPublisher} implementations. Each * outgoing request results in one HTTP Client {@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 published to the HTTP * Client. These subscriptions complete normally when the request body 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. * *
A {@code BodyPublisher} that reports a {@linkplain #contentLength()
* content length} of {@code 0} may not be subscribed to by the HTTP Client,
* as it has effectively no data to publish.
*
* @see BodyPublishers
* @since 11
*/
public interface BodyPublisher extends Flow.Publisher 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();
}
/**
* Implementations of {@link BodyPublisher BodyPublisher} that implement
* various useful publishers, such as publishing the request body from a
* String, or from a file.
*
* The following are examples of using the predefined body publishers to
* convert common high-level Java objects into a flow of data suitable for
* sending as a request body:
*
* {@snippet :
* // Request body from a String
* HttpRequest request = HttpRequest.newBuilder()
* .uri(URI.create("https://foo.com/"))
* .header("Content-Type", "text/plain; charset=UTF-8")
* .POST(BodyPublishers.ofString("some body text"))
* .build(); }
*
* {@snippet :
* // Request body from a File
* HttpRequest request = HttpRequest.newBuilder()
* .uri(URI.create("https://foo.com/"))
* .header("Content-Type", "application/json")
* .POST(BodyPublishers.ofFile(Paths.get("file.json")))
* .build(); }
*
* {@snippet :
* // Request body from a byte array
* HttpRequest request = HttpRequest.newBuilder()
* .uri(URI.create("https://foo.com/"))
* .POST(BodyPublishers.ofByteArray(new byte[] { ... }))
* .build(); }
*
* @since 11
*/
public static class BodyPublishers {
private BodyPublishers() { }
/**
* Returns a request body publisher whose body is retrieved from the
* given {@code Flow.Publisher}. The returned request body publisher
* has an unknown content length.
*
* @apiNote This method can be used as an adapter between {@code
* BodyPublisher} and {@code Flow.Publisher}, where the amount of
* request body that the publisher will publish is unknown.
*
* @param publisher the publisher responsible for publishing the body
* @return a BodyPublisher
*/
public static BodyPublisher
fromPublisher(Flow.Publisher publisher) {
return new RequestPublishers.PublisherAdapter(publisher, -1L);
}
/**
* Returns a request body publisher whose body is retrieved from the
* given {@code Flow.Publisher}. The returned request body publisher
* has the given content length.
*
* The given {@code contentLength} is a positive number, that
* represents the exact amount of bytes the {@code publisher} must
* publish.
*
* @apiNote This method can be used as an adapter between {@code
* BodyPublisher} and {@code Flow.Publisher}, where the amount of
* request body that the publisher will publish is known.
*
* @param publisher the publisher responsible for publishing the body
* @param contentLength a positive number representing the exact
* amount of bytes the publisher will publish
* @throws IllegalArgumentException if the content length is
* non-positive
* @return a BodyPublisher
*/
public static BodyPublisher
fromPublisher(Flow.Publisher publisher,
long contentLength) {
if (contentLength < 1)
throw new IllegalArgumentException("non-positive contentLength: "
+ contentLength);
return new RequestPublishers.PublisherAdapter(publisher, contentLength);
}
/**
* 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 BodyPublisher
*/
public static BodyPublisher ofString(String body) {
return ofString(body, UTF_8);
}
/**
* 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 BodyPublisher
*/
public static BodyPublisher ofString(String s, Charset charset) {
return new RequestPublishers.StringPublisher(s, charset);
}
/**
* 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 BodyPublisher
*/
// TODO (spec): specify that the stream will be closed
public static BodyPublisher ofInputStream(Supplier streamSupplier) {
return new RequestPublishers.InputStreamPublisher(streamSupplier);
}
/**
* Returns a request body publisher whose body is the given byte array.
*
* @param buf the byte array containing the body
* @return a BodyPublisher
*/
public static BodyPublisher ofByteArray(byte[] buf) {
return new RequestPublishers.ByteArrayPublisher(buf);
}
/**
* 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 BodyPublisher
* @throws IndexOutOfBoundsException if the sub-range is defined to be
* out of bounds
*/
public static BodyPublisher ofByteArray(byte[] buf, int offset, int length) {
Objects.checkFromIndexSize(offset, length, buf.length);
return new RequestPublishers.ByteArrayPublisher(buf, offset, length);
}
/**
* 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 BodyPublisher
* @throws java.io.FileNotFoundException if the path is not found
*/
public static BodyPublisher ofFile(Path path) throws FileNotFoundException {
Objects.requireNonNull(path);
return RequestPublishers.FilePublisher.create(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 BodyPublisher
*/
public static BodyPublisher ofByteArrays(Iterable If the sequence is empty an {@linkplain #noBody() empty} publisher
* is returned. Otherwise, if the sequence contains a single element,
* that publisher is returned. Otherwise a concatenation publisher
* is returned.
*
* The request body published by a concatenation publisher
* is logically equivalent to the request body that would have
* been published by concatenating all the bytes of each publisher
* in sequence.
*
* Each publisher is lazily subscribed to in turn,
* until all the body bytes are published, an error occurs, or the
* concatenation publisher's subscription is cancelled.
* The concatenation publisher may be subscribed to more than once,
* which in turn may result in the publishers in the sequence being
* subscribed to more than once.
*
* The concatenation publisher has a known content
* length only if all publishers in the sequence have a known content
* length. The {@link BodyPublisher#contentLength() contentLength}
* reported by the concatenation publisher is computed as follows:
*
*
*
* @implNote If the concatenation publisher's subscription is
* {@linkplain Flow.Subscription#cancel() cancelled}, or an error occurs
* while publishing the bytes, not all publishers in the sequence may
* be subscribed to.
*
* @param publishers a sequence of publishers.
* @return An aggregate publisher that publishes a request body
* logically equivalent to the concatenation of all bytes published
* by each publisher in the sequence.
*
* @since 16
*/
public static BodyPublisher concat(BodyPublisher... publishers) {
return RequestPublishers.concat(Objects.requireNonNull(publishers));
}
}
}