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

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

# Interface HttpRequest.BodyPublisher

All Superinterfaces:
  `Flow.Publisher<ByteBuffer>`

Enclosing class:
  HttpRequest

    public static interface HttpRequest.BodyPublisher
    extends Flow.Publisher<ByteBuffer>

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 `Flow.Subscriber` and `Flow.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.

Since:
  11
See Also:
  `HttpRequest.BodyPublishers`

- ## Method Summary

  Modifier and Type | Method | Description
  --- | --- | ---
  `long` | `contentLength()` | Returns the content length for this request body.

  ### Methods declared in interface java.util.concurrent.Flow.Publisher

  `subscribe`

- ## Method Details

  - ### contentLength

    long contentLength()
    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