-
- All Superinterfaces:
Flow.Publisher<ByteBuffer>
- Enclosing class:
- HttpRequest
public static interface HttpRequest.BodyPublisher extends Flow.Publisher<ByteBuffer>
A Publisher which converts high level Java objects into flows of byte buffers suitable for sending as request bodies.
Incubating Feature. Will be removed in a future release.The
BodyPublisher
class implementsFlow.Publisher<ByteBuffer>
which means that aBodyPublisher
acts as a publisher of byte buffers.The HTTP client implementation subscribes to the publisher in order to receive the flow of outgoing data buffers. The normal semantics of
Flow.Subscriber
andFlow.Publisher
are implemented by the library and are expected from publisher implementations. Each outgoing request results in oneSubscriber
subscribing to theBodyPublisher
in order to provide the sequence of byte buffers containing the request body. Instances ofByteBuffer
published by the publisher must be allocated by the publisher, and must not be accessed after being handed over to the library. These subscriptions complete normally when the request 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 publisher that reports a content length of
0
may not be subscribed to by the HTTP client implementation, as it has effectively no data to publish.
-
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Modifier and Type Method Description long
contentLength()
Returns the content length for this request body.static HttpRequest.BodyPublisher
fromByteArray(byte[] buf)
Returns a request body publisher whose body is the given byte array.static HttpRequest.BodyPublisher
fromByteArray(byte[] buf, int offset, int length)
Returns a request body publisher whose body is the content of the given byte array oflength
bytes starting from the specifiedoffset
.static HttpRequest.BodyPublisher
fromByteArrays(Iterable<byte[]> iter)
A request body publisher that takes data from anIterable
of byte arrays.static HttpRequest.BodyPublisher
fromFile(Path path)
A request body publisher that takes data from the contents of a File.static HttpRequest.BodyPublisher
fromInputStream(Supplier<? extends InputStream> streamSupplier)
A request body publisher that reads its data from anInputStream
.static HttpRequest.BodyPublisher
fromPublisher(Flow.Publisher<? extends ByteBuffer> publisher)
Returns a request body publisher whose body is retrieved from the givenFlow.Publisher
.static HttpRequest.BodyPublisher
fromPublisher(Flow.Publisher<? extends ByteBuffer> publisher, long contentLength)
Returns a request body publisher whose body is retrieved from the givenFlow.Publisher
.static HttpRequest.BodyPublisher
fromString(String body)
Returns a request body publisher whose body is the givenString
, converted using theUTF_8
character set.static HttpRequest.BodyPublisher
fromString(String s, Charset charset)
Returns a request body publisher whose body is the givenString
, converted using the given character set.static HttpRequest.BodyPublisher
noBody()
A request body publisher which sends no request body.-
Methods declared in interface java.util.concurrent.Flow.Publisher
subscribe
-
-
-
-
Method Detail
-
fromPublisher
static HttpRequest.BodyPublisher fromPublisher(Flow.Publisher<? extends ByteBuffer> publisher)
Returns a request body publisher whose body is retrieved from the givenFlow.Publisher
. The returned request body publisher has an unknown content length.- API Note:
- This method can be used as an adapter between
BodyPublisher
andFlow.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
static HttpRequest.BodyPublisher fromPublisher(Flow.Publisher<? extends ByteBuffer> publisher, long contentLength)
Returns a request body publisher whose body is retrieved from the givenFlow.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 thepublisher
must publish.- API Note:
- This method can be used as an adapter between
BodyPublisher
andFlow.Publisher
, where the amount of request body that the publisher will publish is known. - Parameters:
publisher
- the publisher responsible for publishing the bodycontentLength
- 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
-
fromString
static HttpRequest.BodyPublisher fromString(String body)
Returns a request body publisher whose body is the givenString
, converted using theUTF_8
character set.- Parameters:
body
- the String containing the body- Returns:
- a BodyPublisher
-
fromString
static HttpRequest.BodyPublisher fromString(String s, Charset charset)
Returns a request body publisher whose body is the givenString
, converted using the given character set.- Parameters:
s
- the String containing the bodycharset
- the character set to convert the string to bytes- Returns:
- a BodyPublisher
-
fromInputStream
static HttpRequest.BodyPublisher fromInputStream(Supplier<? extends InputStream> streamSupplier)
A request body publisher that reads its data from anInputStream
. ASupplier
ofInputStream
is used in case the request needs to be repeated, as the content is not buffered. TheSupplier
may returnnull
on subsequent attempts, in which case the request fails.- Parameters:
streamSupplier
- a Supplier of open InputStreams- Returns:
- a BodyPublisher
-
fromByteArray
static HttpRequest.BodyPublisher fromByteArray(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
-
fromByteArray
static HttpRequest.BodyPublisher fromByteArray(byte[] buf, int offset, int length)
Returns a request body publisher whose body is the content of the given byte array oflength
bytes starting from the specifiedoffset
.- Parameters:
buf
- the byte array containing the bodyoffset
- the offset of the first bytelength
- the number of bytes to use- Returns:
- a BodyPublisher
- Throws:
IndexOutOfBoundsException
- if the sub-range is defined to be out-of-bounds
-
fromFile
static HttpRequest.BodyPublisher fromFile(Path path) throws FileNotFoundException
A request body publisher that takes data from the contents of a File.- Parameters:
path
- the path to the file containing the body- Returns:
- a BodyPublisher
- Throws:
FileNotFoundException
- if the path is not foundSecurityException
- if a security manager has been installed and it deniesread access
to the given file
-
fromByteArrays
static HttpRequest.BodyPublisher fromByteArrays(Iterable<byte[]> iter)
A request body publisher that takes data from anIterable
of byte arrays. AnIterable
is provided which suppliesIterator
instances. Each attempt to send the request results in one invocation of theIterable
.- Parameters:
iter
- an Iterable of byte arrays- Returns:
- a BodyPublisher
-
noBody
static HttpRequest.BodyPublisher noBody()
A request body publisher which sends no request body.- Returns:
- a BodyPublisher which completes immediately and sends no request body.
-
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
-
-