HttpRequest.BodyPublishers (Java SE 15 & JDK 15)
Description: declaration: module: java.net.http, package: java.net.http, class: HttpRequest, class: BodyPublishers
Keywords: java.net.http.HttpRequest.BodyPublishers class

Module java.net.http
Package java.net.http

# Class HttpRequest.BodyPublishers

java.lang.Object
java.net.http.HttpRequest.BodyPublishers

Enclosing class:
  HttpRequest

    public static class HttpRequest.BodyPublishers
    extends Object

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

- ## Method Summary

  Modifier and Type | Method | Description
  --- | --- | ---
  `static HttpRequest.BodyPublisher` | `fromPublisher​(Flow.Publisher<? extends ByteBuffer> publisher)` | Returns a request body publisher whose body is retrieved from the given `Flow.Publisher`.
  `static HttpRequest.BodyPublisher` | `fromPublisher​(Flow.Publisher<? extends ByteBuffer> publisher, long contentLength)` | Returns a request body publisher whose body is retrieved from the given `Flow.Publisher`.
  `static HttpRequest.BodyPublisher` | `noBody()` | A request body publisher which sends no request body.
  `static HttpRequest.BodyPublisher` | `ofByteArray​(byte[] buf)` | Returns a request body publisher whose body is the given byte array.
  `static HttpRequest.BodyPublisher` | `ofByteArray​(byte[] buf, int offset, int length)` | Returns a request body publisher whose body is the content of the given byte array of `length` bytes starting from the specified `offset`.
  `static HttpRequest.BodyPublisher` | `ofByteArrays​(Iterable<byte[]> iter)` | A request body publisher that takes data from an `Iterable` of byte arrays.
  `static HttpRequest.BodyPublisher` | `ofFile​(Path path)` | A request body publisher that takes data from the contents of a File.
  `static HttpRequest.BodyPublisher` | `ofInputStream​(Supplier<? extends InputStream> streamSupplier)` | A request body publisher that reads its data from an `InputStream`.
  `static HttpRequest.BodyPublisher` | `ofString​(String body)` | Returns a request body publisher whose body is the given `String`, converted using the `UTF_8` character set.
  `static HttpRequest.BodyPublisher` | `ofString​(String s, Charset charset)` | Returns a request body publisher whose body is the given `String`, converted using the given character set.

  ### Methods declared in class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Method Details

  - ### fromPublisher

    public static HttpRequest.BodyPublisher fromPublisher​(Flow.Publisher<? extends ByteBuffer> publisher)
    Returns a request body publisher whose body is retrieved from the given `Flow.Publisher`. The returned request body publisher has an unknown content length.
    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.
    Parameters:
      `publisher` - the publisher responsible for publishing the body
    Returns:
      a BodyPublisher

  - ### fromPublisher

    public static HttpRequest.BodyPublisher fromPublisher​(Flow.Publisher<? extends ByteBuffer> publisher, long contentLength)
    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.

    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.
    Parameters:
      `publisher` - the publisher responsible for publishing the body
      `contentLength` - a positive number representing the exact amount of bytes the publisher will publish
    Returns:
      a BodyPublisher
    Throws:
      `IllegalArgumentException` - if the content length is non-positive

  - ### ofString

    public static HttpRequest.BodyPublisher ofString​(String body)
    Returns a request body publisher whose body is the given `String`, converted using the `UTF_8` character set.
    Parameters:
      `body` - the String containing the body
    Returns:
      a BodyPublisher

  - ### ofString

    public static HttpRequest.BodyPublisher ofString​(String s, Charset charset)
    Returns a request body publisher whose body is the given `String`, converted using the given character set.
    Parameters:
      `s` - the String containing the body
      `charset` - the character set to convert the string to bytes
    Returns:
      a BodyPublisher

  - ### ofInputStream

    public static HttpRequest.BodyPublisher ofInputStream​(Supplier<? extends InputStream> streamSupplier)
    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.
    Parameters:
      `streamSupplier` - a Supplier of open InputStreams
    Returns:
      a BodyPublisher

  - ### ofByteArray

    public static HttpRequest.BodyPublisher ofByteArray​(byte[] buf)
    Returns a request body publisher whose body is the given byte array.
    Parameters:
      `buf` - the byte array containing the body
    Returns:
      a BodyPublisher

  - ### ofByteArray

    public static HttpRequest.BodyPublisher ofByteArray​(byte[] buf, int offset, int length)
    Returns a request body publisher whose body is the content of the given byte array of `length` bytes starting from the specified `offset`.
    Parameters:
      `buf` - the byte array containing the body
      `offset` - the offset of the first byte
      `length` - the number of bytes to use
    Returns:
      a BodyPublisher
    Throws:
      `IndexOutOfBoundsException` - if the sub-range is defined to be out of bounds

  - ### ofFile

    public static HttpRequest.BodyPublisher ofFile​(Path path) throws FileNotFoundException
    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.

    Parameters:
      `path` - the path to the file containing the body
    Returns:
      a BodyPublisher
    Throws:
      `FileNotFoundException` - if the path is not found
      `SecurityException` - if opening the file for reading is denied: in the case of the system-default file system provider, and a security manager is installed, `checkRead` is invoked to check read access to the given file

  - ### ofByteArrays

    public static HttpRequest.BodyPublisher ofByteArrays​(Iterable<byte[]> iter)
    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`.
    Parameters:
      `iter` - an Iterable of byte arrays
    Returns:
      a BodyPublisher

  - ### noBody

    public static HttpRequest.BodyPublisher noBody()
    A request body publisher which sends no request body.
    Returns:
      a BodyPublisher which completes immediately and sends no request body.