Package org.apache.juneau.rest.client

Class RecordStreamBody

java.lang.Object
org.apache.juneau.rest.client.RecordStreamBody
All Implemented Interfaces:
HttpBody
public final class RecordStreamBody extends Object implements HttpBody
A streaming HTTP request body that emits its content through a token/record-streaming cursor.

Lets a caller pass a Consumer<RecordWriter> or Consumer<TokenWriter> as the body of a request. The consumer is invoked lazily during writeTo(OutputStream) — the cursor writes directly to the live transport output stream, so arbitrarily large payloads are streamed to the wire without being buffered in memory first.

While the next-generation client negotiates a parser for inbound/response bodies (from the response Content-Type), the request-body OUTPUT format here is an explicit caller choice: the Serializer that backs the cursor is supplied directly (defaulting to JsonSerializer.DEFAULT). The body's getContentType() reflects that serializer's media type.

Repeatability:

Streaming bodies are non-repeatable by default (isRepeatable() returns false) because the caller's consumer may be backed by a one-shot source. A non-repeatable body fails fast (throws IOException) if a resend is required (i.e. writeTo(OutputStream) is invoked more than once). Callers whose consumer can be replayed safely may opt in via repeatable().

Usage:

@Remote public interface MyApi { @RemotePost("/bulk-upload") void upload(@Content RecordStreamBody body); } // Caller api.upload(RecordStreamBody.records(w -> { for (Bean b : source()) w.write(b); }));

See Also:
Since:
9.2.1

  • Method Details

    • records

      public static RecordStreamBody records(Consumer<RecordWriter> consumer)
      Creates a body that streams via a RecordWriter (whole-value record cursor) using the default JSON serializer.
      Parameters:
      consumer - The callback that emits records. Must not be null.
      Returns:
      A new body. Never null.

    • records

      public static RecordStreamBody records(Serializer serializer, Consumer<RecordWriter> consumer)
      Creates a body that streams via a RecordWriter (whole-value record cursor) using the given serializer.
      Parameters:
      serializer - The serializer that opens the record cursor. Must not be null and must implement RecordWritable.
      consumer - The callback that emits records. Must not be null.
      Returns:
      A new body. Never null.
      Throws:
      IllegalArgumentException - If the serializer does not support the record-writer surface.

    • token

      public static RecordStreamBody token(Consumer<TokenWriter> consumer)
      Creates a body that streams via a TokenWriter (fine-grained structural cursor) using the default JSON serializer.
      Parameters:
      consumer - The callback that emits structural events. Must not be null.
      Returns:
      A new body. Never null.

    • token

      public static RecordStreamBody token(Serializer serializer, Consumer<TokenWriter> consumer)
      Creates a body that streams via a TokenWriter (fine-grained structural cursor) using the given serializer.
      Parameters:
      serializer - The serializer that opens the token cursor. Must not be null and must implement TokenWritable.
      consumer - The callback that emits structural events. Must not be null.
      Returns:
      A new body. Never null.
      Throws:
      IllegalArgumentException - If the serializer does not support the token-writer surface.

    • repeatable

      public RecordStreamBody repeatable()
      Returns a copy of this body flagged as repeatable.

      Only opt in when the caller's consumer can be safely replayed (e.g. it iterates a re-readable source).

      Returns:
      A new repeatable body. Never null.

    • getContentType

      public String getContentType()
      Description copied from interface: HttpBody
      Returns the MIME content type of this body, e.g. "application/json; charset=UTF-8".
      Specified by:
      getContentType in interface HttpBody
      Returns:
      The content type, or null if unknown.

    • getContentLength

      public long getContentLength()
      Description copied from interface: HttpBody
      Returns the content length in bytes, or -1 if unknown.

      Implementations that buffer content may return the exact length; streaming implementations should return -1 to cause the transport to use chunked transfer encoding.

      Specified by:
      getContentLength in interface HttpBody
      Returns:
      The content length, or -1 if unknown.

    • isRepeatable

      public boolean isRepeatable()
      Description copied from interface: HttpBody
      Returns true if this body can be written more than once.

      Streaming bodies backed by a one-shot InputStream should return false. Buffered bodies (byte arrays, strings, files) should return true.

      Specified by:
      isRepeatable in interface HttpBody
      Returns:
      true if repeatable.

    • writeTo

      public void writeTo(OutputStream out) throws IOException
      Description copied from interface: HttpBody
      Writes the body content to the given output stream.

      Implementations must not close out.

      Specified by:
      writeTo in interface HttpBody
      Parameters:
      out - The stream to write to. Never null.
      Throws:
      IOException - If an I/O error occurs.