| /* |
| * Copyright (c) 2015, 2018, Oracle and/or its affiliates. All rights reserved. |
| * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
| * |
| * This code is free software; you can redistribute it and/or modify it |
| * under the terms of the GNU General Public License version 2 only, as |
| * published by the Free Software Foundation. Oracle designates this |
| * particular file as subject to the "Classpath" exception as provided |
| * by Oracle in the LICENSE file that accompanied this code. |
| * |
| * This code is distributed in the hope that it will be useful, but WITHOUT |
| * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
| * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
| * version 2 for more details (a copy is included in the LICENSE file that |
| * accompanied this code). |
| * |
| * You should have received a copy of the GNU General Public License version |
| * 2 along with this work; if not, write to the Free Software Foundation, |
| * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
| * |
| * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
| * or visit www.oracle.com if you need additional information or have any |
| * questions. |
| */ |
| |
| package java.net.http; |
| |
| import java.io.FileNotFoundException; |
| import java.io.InputStream; |
| import java.net.URI; |
| import java.nio.ByteBuffer; |
| import java.nio.charset.Charset; |
| import java.nio.charset.StandardCharsets; |
| import java.nio.file.Path; |
| import java.time.Duration; |
| import java.util.Iterator; |
| import java.util.Objects; |
| import java.util.Optional; |
| import java.util.concurrent.Flow; |
| import java.util.function.Supplier; |
| import jdk.internal.net.http.HttpRequestBuilderImpl; |
| import jdk.internal.net.http.RequestPublishers; |
| import static java.nio.charset.StandardCharsets.UTF_8; |
| |
| /** |
| * An HTTP request. |
| * |
| * <p> 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. |
| * |
| * <p> The following is an example of a GET request that prints the response |
| * body as a String: |
| * |
| * <pre>{@code 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(); }</pre> |
| * |
| * <p>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}. |
| * |
| * <p> Instances of {@code HttpRequest.Builder} are created by calling {@link |
| * HttpRequest#newBuilder(URI)} or {@link HttpRequest#newBuilder()}. |
| * |
| * <p> 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. |
| * |
| * <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 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. |
| * |
| * <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 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 <a href="https://tools.ietf.org/html/rfc7230#section-3.2"> |
| * RFC 7230 section-3.2</a>, 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 |
| * <a href="https://tools.ietf.org/html/rfc7230#section-3.2"> |
| * RFC 7230 section-3.2</a>, 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, ie. |
| * 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 <a href="https://tools.ietf.org/html/rfc7230#section-3.2"> |
| * RFC 7230 section-3.2</a>, 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 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 <a href="https://tools.ietf.org/html/rfc7230#section-3.1.1"> |
| * RFC 7230 section-3.1.1</a>, or the method is restricted by the |
| * implementation. |
| */ |
| public Builder method(String method, BodyPublisher bodyPublisher); |
| |
| /** |
| * Builds and returns an {@link HttpRequest}. |
| * |
| * @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 an {@code HttpRequest} builder. |
| * |
| * @return a new request builder |
| */ |
| public static HttpRequest.Builder newBuilder() { |
| return new HttpRequestBuilderImpl(); |
| } |
| |
| /** |
| * 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 BodyPublisher} |
| */ |
| 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 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 an {@code Optional} containing this request's timeout duration |
| */ |
| public abstract Optional<Duration> timeout(); |
| |
| /** |
| * Returns this request's {@linkplain HttpRequest.Builder#expectContinue(boolean) |
| * expect continue} setting. |
| * |
| * @return this request's expect continue setting |
| */ |
| public abstract boolean expectContinue(); |
| |
| /** |
| * Returns this request's {@code URI}. |
| * |
| * @return this request's URI |
| */ |
| public abstract URI uri(); |
| |
| /** |
| * Returns an {@code Optional} containing the HTTP protocol version that |
| * will be requested for this {@code HttpRequest}. If the version was not |
| * set in the request's builder, then the {@code Optional} is empty. |
| * In that case, the version requested will be that of the sending |
| * {@link HttpClient}. The corresponding {@link HttpResponse} should be |
| * queried to determine the version that was actually used. |
| * |
| * @return HTTP protocol version |
| */ |
| public abstract Optional<HttpClient.Version> version(); |
| |
| /** |
| * The (user-accessible) request headers that this request was (or will be) |
| * sent with. |
| * |
| * @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; |
| } |
| |
| /** |
| * 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 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. |
| * |
| * <p> 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}. |
| * |
| * <p> 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. |
| * |
| * <p> 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<ByteBuffer> { |
| |
| /** |
| * Returns the content length for this request body. May be zero |
| * if no request body being sent, greater than zero for a fixed |
| * length content, or less than zero for an unknown content length. |
| * |
| * <p> 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. |
| * |
| * <p> 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: |
| * |
| * <pre>{@code // 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(); |
| * |
| * // 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(); |
| * |
| * // Request body from a byte array |
| * HttpRequest request = HttpRequest.newBuilder() |
| * .uri(URI.create("https://foo.com/")) |
| * .POST(BodyPublishers.ofByteArray(new byte[] { ... })) |
| * .build(); }</pre> |
| * |
| * @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<? extends ByteBuffer> 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. |
| * |
| * <p> 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<? extends ByteBuffer> 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<? extends InputStream> 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. |
| * |
| * <p> Security manager permission checks are performed in this factory |
| * method, when the {@code BodyPublisher} is created. Care must be taken |
| * that the {@code BodyPublisher} is not shared with untrusted code. |
| * |
| * @param path the path to the file containing the body |
| * @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 |
| */ |
| 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<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. |
| */ |
| public static BodyPublisher noBody() { |
| return new RequestPublishers.EmptyPublisher(); |
| } |
| } |
| } |
