Module jdk.incubator.httpclient
Package jdk.incubator.http

Interface HttpResponse.BodySubscriber<T>

  • Type Parameters:
    T - the response body type
    All Superinterfaces:
    Flow.Subscriber<List<ByteBuffer>>
    Enclosing class:
    HttpResponse<T>
    public static interface HttpResponse.BodySubscriber<T>
extends Flow.Subscriber<List<ByteBuffer>>
    A subscriber for response bodies.
    Incubating Feature. Will be removed in a future release.

    The object acts as a Flow.Subscriber<List<ByteBuffer>> to the HTTP client implementation, which publishes unmodifiable lists of ByteBuffers containing the response body. The Flow of data, as well as the order of ByteBuffers in the Flow lists, is a strictly ordered representation of the response body. Both the Lists and the ByteBuffers, once passed to the subscriber, are no longer used by the HTTP client. The subscriber converts the incoming buffers of data to some user-defined object type T.

    The getBody() method returns a CompletionStage <T> that provides the response body object. The CompletionStage must be obtainable at any time. When it completes depends on the nature of type T. In many cases, when T represents the entire body after being read then it completes after the body has been read. If T is a streaming type such as InputStream then it completes before the body has been read, because the calling code uses it to consume the data.

    API Note:
    To ensure that all resources associated with the corresponding exchange are properly released, an implementation of BodySubscriber must ensure to request more data until onComplete or onError are signalled, or cancel its subscription if unable or unwilling to do so. Calling cancel before exhausting the data may cause the underlying HTTP connection to be closed and prevent it from being reused for subsequent operations.

    • Method Detail

      • getBody

        CompletionStage<T> getBody()
        Returns a CompletionStage which when completed will return the response body object.
        Returns:
        a CompletionStage for the response body

      • fromSubscriber

        static <S extends Flow.Subscriber<? super List<ByteBuffer>>> HttpResponse.BodySubscriber<Void> fromSubscriber​(S subscriber)
        Returns a body subscriber that forwards all response body to the given Flow.Subscriber. The getBody() completion stage} of the returned body subscriber completes after one of the given subscribers onComplete or onError has been invoked.
        API Note:
        This method can be used as an adapter between BodySubscriber and Flow.Subscriber.
        Type Parameters:
        S - the type of the Subscriber
        Parameters:
        subscriber - the subscriber
        Returns:
        a body subscriber

      • fromSubscriber

        static <S extends Flow.Subscriber<? super List<ByteBuffer>>,T> HttpResponse.BodySubscriber<T> fromSubscriber​(S subscriber,
                                                                                                             Function<S,T> finisher)
        Returns a body subscriber that forwards all response body to the given Flow.Subscriber. The getBody() completion stage} of the returned body subscriber completes after one of the given subscribers onComplete or onError has been invoked.

        The given finisher function is applied after the given subscriber's onComplete has been invoked. The finisher function is invoked with the given subscriber, and returns a value that is set as the response's body.

        API Note:
        This method can be used as an adapter between BodySubscriber and Flow.Subscriber.
        Type Parameters:
        S - the type of the Subscriber
        T - the type of the response body
        Parameters:
        subscriber - the subscriber
        finisher - a function to be applied after the subscriber has completed
        Returns:
        a body subscriber

      • asString

        static HttpResponse.BodySubscriber<String> asString​(Charset charset)
        Returns a body subscriber which stores the response body as a String converted using the given Charset.

        The HttpResponse using this subscriber is available after the entire response has been read.

        Parameters:
        charset - the character set to convert the String with
        Returns:
        a body subscriber

      • asByteArray

        static HttpResponse.BodySubscriber<byte[]> asByteArray()
        Returns a BodySubscriber which stores the response body as a byte array.

        The HttpResponse using this subscriber is available after the entire response has been read.

        Returns:
        a body subscriber

      • asFile

        static HttpResponse.BodySubscriber<Path> asFile​(Path file,
                                                OpenOption... openOptions)
        Returns a BodySubscriber which stores the response body in a file opened with the given options and name. The file will be opened with the given options using FileChannel.open just before the body is read. Any exception thrown will be returned or thrown from HttpClient::send or HttpClient::sendAsync as appropriate.

        The HttpResponse using this subscriber is available after the entire response has been read.

        Parameters:
        file - the file to store the body in
        openOptions - the list of options to open the file with
        Returns:
        a body subscriber
        Throws:
        SecurityException - If a security manager has been installed and it denies write access to the file. The checkDelete method is invoked to check delete access if the file is opened with the DELETE_ON_CLOSE option.

      • asFile

        static HttpResponse.BodySubscriber<Path> asFile​(Path file)
        Returns a BodySubscriber which stores the response body in a file opened with the given name. Has the same effect as calling asFile with the standard open options CREATE and WRITE

        The HttpResponse using this subscriber is available after the entire response has been read.

        Parameters:
        file - the file to store the body in
        Returns:
        a body subscriber
        Throws:
        SecurityException - if a security manager has been installed and it denies write access to the file

      • asByteArrayConsumer

        static HttpResponse.BodySubscriber<Void> asByteArrayConsumer​(Consumer<Optional<byte[]>> consumer)
        Returns a BodySubscriber which provides the incoming body data to the provided Consumer of Optional<byte[]>. Each call to Consumer.accept() will contain a non empty Optional, except for the final invocation after all body data has been read, when the Optional will be empty.

        The HttpResponse using this subscriber is available after the entire response has been read.

        Parameters:
        consumer - a Consumer of byte arrays
        Returns:
        a BodySubscriber

      • asInputStream

        static HttpResponse.BodySubscriber<InputStream> asInputStream()
        Returns a BodySubscriber which streams the response body as an InputStream.

        The HttpResponse using this subscriber is available immediately after the response headers have been read, without requiring to wait for the entire body to be processed. The response body can then be read directly from the InputStream.

        API Note:
        To ensure that all resources associated with the corresponding exchange are properly released the caller must ensure to either read all bytes until EOF is reached, or call InputStream.close() if it is unable or unwilling to do so. Calling close before exhausting the stream may cause the underlying HTTP connection to be closed and prevent it from being reused for subsequent operations.
        Returns:
        a body subscriber that streams the response body as an InputStream.

      • discard

        static <U> HttpResponse.BodySubscriber<U> discard​(U value)
        Returns a response subscriber which discards the response body. The supplied value is the value that will be returned from HttpResponse.body().
        Type Parameters:
        U - The type of the response body
        Parameters:
        value - the value to return from HttpResponse.body(), may be null
        Returns:
        a BodySubscriber

      • buffering

        static <T> HttpResponse.BodySubscriber<T> buffering​(HttpResponse.BodySubscriber<T> downstream,
                                                    int bufferSize)
        Returns a BodySubscriber which buffers data before delivering it to the given downstream subscriber. The subscriber guarantees to deliver buffersize bytes of data to each invocation of the downstream's onNext method, except for the final invocation, just before onComplete is invoked. The final invocation of onNext may contain fewer than buffersize bytes.

        The returned subscriber delegates its getBody() method to the downstream subscriber.

        Parameters:
        downstream - the downstream subscriber
        bufferSize - the buffer size
        Returns:
        a buffering body subscriber
        Throws:
        IllegalArgumentException - if bufferSize <= 0