Package org.apache.juneau.rest.client

Class ResponseBody

java.lang.Object

org.apache.juneau.rest.client.ResponseBody

public final class ResponseBody
extends Object

A fluent accessor for an HTTP response body returned by RestResponse.

Provides convenient methods for reading the body as a string, byte array, or stream. The body is read lazily; each method reads and returns the body content once.

Obtain instances via RestResponse.body().

See Also:

• Next-Generation REST Client

Since:

9.2.1

Method Summary

Modifier and Type	Method	Description
<T> T	as(Class<T> type)	Parses the response body to type using the parser negotiated from the response Content-Type.
<T> T	as(Parser parser, Class<T> type)	Parses the response body to type using the given parser.
byte[]	asBytes()	Returns the response body as a byte array.
<T> T	asCursor(Class<T> type)	Opens a token/record-streaming cursor over the response body using the parser negotiated from the response Content-Type.
<T> T	asCursor(Parser parser, Class<T> type)	Opens a token/record-streaming cursor over the response body using the given parser.
SseEventReader	asEventStream()	Opens a closeable, cancellable cursor over a text/event-stream response body.
InputStream	asStream()	Returns the raw response body stream.
String	asString()	Returns the response body as a UTF-8 string.
String	asString(Charset charset)	Returns the response body decoded with the given charset.
byte[]	readAllBytes()	Reads the response body into a byte array and returns it, or returns null if there is no body.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

asString

public String asString()
                throws IOException

Returns the response body as a UTF-8 string.

Returns:

The body string, or null if the response has no body.

Throws:

IOException - If an I/O error occurs reading the body.

asString

public String asString(Charset charset)
                throws IOException

Returns the response body decoded with the given charset.

Parameters:

charset - The character set to use for decoding. Must not be null.

Returns:

The body string, or null if the response has no body.

Throws:

IOException - If an I/O error occurs reading the body.

asBytes

public byte[] asBytes()
               throws IOException

Returns the response body as a byte array.

Returns:

The body bytes, or null if the response has no body.

Throws:

IOException - If an I/O error occurs reading the body.

asStream

public InputStream asStream()

Returns the raw response body stream.

Callers should not close this stream directly; close the parent RestResponse instead.

Returns:

The body stream, or null if the response has no body.

readAllBytes

public byte[] readAllBytes()
                    throws IOException

Reads the response body into a byte array and returns it, or returns null if there is no body.

Equivalent to asBytes().

Returns:

The body bytes, or null if the response has no body.

Throws:

IOException - If an I/O error occurs reading the body.

asCursor

public <T> T asCursor(Class<T> type)
               throws IOException

Opens a token/record-streaming cursor over the response body using the parser negotiated from the response Content-Type.

Equivalent to asCursor(negotiatedParser, type) where the parser is selected from the response Content-Type header; when no registered parser matches and no default parser is configured, a 415 Unsupported Media Type is thrown. Use asCursor(Parser, Class) to read with an explicit parser.

Type Parameters:

T - The cursor type (RecordReader, TokenReader, or a concrete subtype).

Parameters:

type - The declared cursor type. Must not be null.

Returns:

A cursor over the live response body. Never null.

Throws:

IOException - If the body is missing, the parser does not support the requested cursor surface, or the produced cursor is not assignable to type.

as

public <T> T as(Class<T> type)
         throws IOException

Parses the response body to type using the parser negotiated from the response Content-Type.

When the header is absent or matches no registered parser and no default parser is configured, a 415 Unsupported Media Type is thrown. Use as(Parser, Class) to force a specific parser, bypassing content negotiation.

Type Parameters:

T - The type to parse to.

Parameters:

type - The type to parse to. Must not be null.

Returns:

The parsed body, or null if the response has no body.

Throws:

IOException - If an I/O error occurs reading the body or the body could not be parsed.

as

public <T> T as(Parser parser,
 Class<T> type)
         throws IOException

Parses the response body to type using the given parser.

This forces the supplied parser, bypassing the Content-Type negotiation performed by as(Class).

A parse failure is surfaced strictly as an IOException wrapping the underlying ParseException; the malformed body is never returned to the caller.

Type Parameters:

T - The type to parse to.

Parameters:

parser - The parser to use. Must not be null.

type - The type to parse to. Must not be null.

Returns:

The parsed body, or null if the response has no body.

Throws:

IOException - If an I/O error occurs reading the body or the body could not be parsed.

asCursor

public <T> T asCursor(Parser parser,
 Class<T> type)
               throws IOException

Opens a token/record-streaming cursor over the response body using the given parser.

This forces the supplied parser, bypassing the Content-Type negotiation performed by asCursor(Class).

The cursor reads directly from the live response stream — the body is not buffered into memory. The caller owns the returned cursor and the parent RestResponse; close them when done.

When type is (or extends) TokenReader the parser must implement TokenReadable; otherwise it must implement RecordReadable.

Type Parameters:

T - The cursor type (RecordReader, TokenReader, or a concrete subtype).

Parameters:

parser - The parser that opens the cursor. Must not be null.

type - The declared cursor type. Must not be null.

Returns:

A cursor over the live response body. Never null.

Throws:

IOException - If the body is missing, the parser does not support the requested cursor surface, or the produced cursor is not assignable to type.

asEventStream

public SseEventReader asEventStream()
                             throws IOException

Opens a closeable, cancellable cursor over a text/event-stream response body.

Reads the live response body as UTF-8 and dispatches one SseEvent at a time via the returned SseEventReader. The stream is not buffered into memory — events are parsed incrementally as bytes arrive, which is required for a long-lived Streamable-HTTP channel (see juneau-rest-client-mcp).

Closing the returned reader first closes the parent RestResponse (transport-layer cancel / release), then closes the reader itself. This ordering is what makes the cursor cancellable: callers can stop consuming an open SSE channel at any time by calling SseEventReader.close(), including from another thread, without waiting for the server to finish sending events.

Transport-specific release behavior varies: this API guarantees that both the response and reader are closed in the above order, but the exact connection-release mechanism is determined by the active transport.

Notes:

• This cursor is not thread-safe, except for using SseEventReader.close() as a cancellation signal from another thread.
• Mid-stream read failures are surfaced as UncheckedIOException from SseEventReader.hasNext() / SseEventReader.next() (per SseEventReader contract).
• Iterating after close throws.

Returns:

A cursor over the live response body. Never null.

Throws:

IOException - If the response has no body to open a stream over.