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

    All Methods Static Methods Concrete Methods
    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 Detail

    - #### 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 a security manager has been installed and it denies `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.