https://openjdk.java.net/ 
/*
 * 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.

 An HttpRequest instance is built through an HttpRequest builder. An HttpRequest builder is obtained from one of the newBuilder methods. A request's URI, headers, and body can be set. Request bodies are provided through a BodyPublisher supplied to one of the POST, PUT or method methods. Once all required parameters have been set in the builder, build will return the 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:

   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 BodyPublishers provides implementations of many common publishers. Alternatively, a custom BodyPublisher implementation can be used. 
Since:11
/**
 * 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.

/**
     * Creates an HttpRequest.
     */
    protected HttpRequest() {}

    
A builder of HTTP requests. 
 Instances of HttpRequest.Builder are created by calling HttpRequest.newBuilder(URI) or HttpRequest.newBuilder(). 
 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 build method returns a new HttpRequest each time it is invoked. Once built an 
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
/**
     * 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 HttpRequest's request URI. 
Params:
  • uri – the request URI
Throws:
Returns:this 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 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. 
Params:
  • enable – true if Expect continue to be sent
Returns:this builder
/**
         * 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 Version for this request. 
 The corresponding 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 HttpClient. 
Params:
  • version – the HTTP protocol version requested
Returns:this builder
/**
         * 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.

Params:
  • name – the header name
  • value – the header value
Throws:
Implementation Note: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 HttpRequest.Builder may choose to throw an IllegalArgumentException if such a header is passed to the builder.
Returns:this builder
/**
         * 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 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. 
Params:
  • headers – the list of name value pairs
Throws:
Returns:this builder
/**
         * 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 HttpTimeoutException is thrown from HttpClient::send or HttpClient::sendAsync completes exceptionally with an HttpTimeoutException. The effect of not setting a timeout is the same as setting an infinite Duration, ie. block forever. 
Params:
  • duration – the timeout duration
Throws:
Returns:this builder
/**
         * 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.

Params:
  • name – the header name
  • value – the header value
Throws:
Returns:this builder
/**
         * 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.

Returns:this builder
/**
         * 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.

Params:
  • bodyPublisher – the body publisher
Returns:this builder
/**
         * 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.

Params:
  • bodyPublisher – the body publisher
Returns:this builder
/**
         * 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.

Returns:this builder
/**
         * 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.

Params:
  • method – the method to use
  • bodyPublisher – the body publisher
Throws:
API Note:The 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 CONNECT method.
Returns:this builder
/**
         * 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 HttpRequest. 
Throws:
Returns:a new HttpRequest
/**
         * 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 Builder based on current state. The new builder can then be modified independently of this builder. 
Returns:an exact copy 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 Builder copy();
    }

    
Creates an HttpRequest builder with the given URI. 
Params:
  • uri – the request URI
Throws:
Returns:a new request builder
/**
     * 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 HttpRequest builder. 
Returns:a new request builder
/**
     * Creates an {@code HttpRequest} builder.
     *
     * @return a new request builder
     */
    public static HttpRequest.Builder newBuilder() {
        return new HttpRequestBuilderImpl();
    }

    
Returns an Optional containing the BodyPublisher set on this request. If no BodyPublisher was set in the requests's builder, then the Optional is empty. 
Returns:an Optional containing this request's BodyPublisher
/**
     * 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".

Returns:this request's method
/**
     * 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 Optional containing this request's timeout duration. If the timeout duration was not set in the request's builder, then the Optional is empty. 
Returns:an Optional containing this request's timeout duration
/**
     * 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 
expect continue setting. 
Returns:this request's expect continue setting
/**
     * 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 URI. 
Returns:this request's URI
/**
     * Returns this request's {@code URI}.
     *
     * @return this request's URI
     */
    public abstract URI uri();

    
Returns an Optional containing the HTTP protocol version that will be requested for this HttpRequest. If the version was not set in the request's builder, then the Optional is empty. In that case, the version requested will be that of the sending HttpClient. The corresponding HttpResponse should be queried to determine the version that was actually used. 
Returns:HTTP protocol version
/**
     * 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.

Returns:this request's HttpHeaders
/**
     * 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.

 If the given object is not an HttpRequest then this method returns false. Two HTTP requests are equal if their URI, method, and headers fields are all equal. 
 This method satisfies the general contract of the Object.equals method. 
Params:
  • obj – the object to which this object is to be compared
Returns:true if, and only if, the given object is an 
        HttpRequest that is equal to this HTTP request
/**
     * 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.

 The hash code is based upon the HTTP request's URI, method, and header components, and satisfies the general contract of the Object.hashCode method. 
Returns:the hash-code value for this HTTP request
/**
     * 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 BodyPublisher converts high-level Java objects into a flow of byte buffers suitable for sending as a request body. The class BodyPublishers provides implementations of many common publishers. 
 The BodyPublisher interface extends 
Flow.Publisher<ByteBuffer>, which means that a BodyPublisher acts as a publisher of byte buffers. 
 When sending a request that contains a body, the HTTP Client subscribes to the request's BodyPublisher in order to receive the flow of outgoing request body data. The normal semantics of Subscriber and Publisher are implemented by the HTTP Client and are expected from BodyPublisher implementations. Each outgoing request results in one HTTP Client Subscriber subscribing to the BodyPublisher in order to provide the sequence of byte buffers containing the request body. Instances of 
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 BodyPublisher that reports a 
content length of 0 may not be subscribed to by the HTTP Client, as it has effectively no data to publish. 
See Also:
Since:11
/**
     * 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&lt;ByteBuffer&gt;}, 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.

 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.

Returns:the content length for this request body, if known
/**
         * 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 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:
 
   // 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(); 


Since:11
/**
     * 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 Flow.Publisher. The returned request body publisher has an unknown content length. 
Params:
  • publisher – the publisher responsible for publishing the body
API Note:This method can be used as an adapter between 
BodyPublisher and Flow.Publisher, where the amount of request body that the publisher will publish is unknown.
Returns:a BodyPublisher
/**
         * 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 Flow.Publisher. The returned request body publisher has the given content length. 
 The given contentLength is a positive number, that represents the exact amount of bytes the publisher must publish. 
Params:
  • publisher – the publisher responsible for publishing the body
  • contentLength – a positive number representing the exact
                     amount of bytes the publisher will publish
Throws:
API Note:This method can be used as an adapter between 
BodyPublisher and Flow.Publisher, where the amount of request body that the publisher will publish is known.
Returns:a BodyPublisher
/**
         * 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 
String, converted using the UTF_8 character set. 
Params:
  • body – the String containing the body
Returns:a BodyPublisher
/**
         * 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 
String, converted using the given character set. 
Params:
  • s – the String containing the body
  • charset – the character set to convert the string to bytes
Returns:a BodyPublisher
/**
         * 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 InputStream. A Supplier of InputStream is used in case the request needs to be repeated, as the content is not buffered. The Supplier may return null on subsequent attempts, in which case the request fails. 
Params:
  • streamSupplier – a Supplier of open InputStreams
Returns:a BodyPublisher
/**
         * 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.

Params:
  • buf – the byte array containing the body
Returns:a BodyPublisher
/**
         * 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 length bytes starting from the specified offset. 
Params:
  • buf – the byte array containing the body
  • offset – the offset of the first byte
  • length – the number of bytes to use
Throws:
Returns:a BodyPublisher
/**
         * 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.

 Security manager permission checks are performed in this factory method, when the BodyPublisher is created. Care must be taken that the BodyPublisher is not shared with untrusted code. 
Params:
  • path – the path to the file containing the body
Throws:
Returns:a BodyPublisher
/**
         * 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 Iterable of byte arrays. An Iterable is provided which supplies Iterator instances. Each attempt to send the request results in one invocation of the Iterable. 
Params:
  • iter – an Iterable of byte arrays
Returns:a BodyPublisher
/**
         * 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.

Returns:a BodyPublisher which completes immediately and sends
        no request body.
/**
         * 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();
        }
    }
}