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

Class 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 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.